docs/agent-playbooks/known-surprises.md

# Known Surprises

This file tracks repository-specific confusion points that caused agent mistakes.

## Entry Criteria

Add an entry only if all are true:

- It is specific to this repository (not generic advice).
- It is likely to recur for future agents.
- It has a concrete mitigation that can be followed.

If uncertain, ask the developer before adding an entry.

## Entry Template

```md
### [Short title]

- **Date:** YYYY-MM-DD
- **Observed by:** agent name or contributor
- **Context:** where/when it happened
- **What was surprising:** concrete unexpected behavior
- **Impact:** what went wrong or could go wrong
- **Mitigation:** exact step future agents should take
- **Status:** confirmed | superseded
```

## Entries

### Portless breaks Windows installs

- **Date:** 2026-03-04
- **Observed by:** Codex
- **Context:** GitHub Actions `Test Windows` dependency install on `windows-2022`
- **What was surprising:** `portless@0.5.2` is a local dev-only tool, but keeping it in `devDependencies` makes `yarn install` fail on Windows because the package declares `win32` unsupported.
- **Impact:** Windows CI fails before build steps run, even though the app does not need `portless` there.
- **Mitigation:** Keep `portless` in `optionalDependencies` and make `yarn start` fall back to direct `vite` startup when `portless` is unavailable.
- **Status:** confirmed

### Do not add plebbit-js directly for Electron RPC

- **Date:** 2026-03-07
- **Observed by:** Codex
- **Context:** Adding `knip` exposed `electron/start-plebbit-rpc.js` importing `@plebbit/plebbit-js/rpc` as an unlisted dependency.
- **What was surprising:** Even though that file imports `@plebbit/plebbit-js` directly, repository policy is to depend only on `@bitsocialnet/bitsocial-react-hooks` and use its transitive copy of `plebbit-js`.
- **Impact:** Agents may “fix” the unlisted import by adding `@plebbit/plebbit-js` to `package.json`, which violates project policy.
- **Mitigation:** Do not add `@plebbit/plebbit-js` to `package.json` for this repo. If `knip` flags `electron/start-plebbit-rpc.js`, handle it with a targeted `ignoreIssues` entry instead.
- **Status:** confirmed
docs: add surprise-handling workflow and known-surprises playbook 2026-02-24 14:01:18 +08:00			`# Known Surprises`

			`This file tracks repository-specific confusion points that caused agent mistakes.`

			`## Entry Criteria`

			`Add an entry only if all are true:`

			`- It is specific to this repository (not generic advice).`
			`- It is likely to recur for future agents.`
			`- It has a concrete mitigation that can be followed.`

			`If uncertain, ask the developer before adding an entry.`

			`## Entry Template`

			```md
			`### [Short title]`

			`- Date: YYYY-MM-DD`
			`- Observed by: agent name or contributor`
			`- Context: where/when it happened`
			`- What was surprising: concrete unexpected behavior`
			`- Impact: what went wrong or could go wrong`
			`- Mitigation: exact step future agents should take`
			`- Status: confirmed \| superseded`
			```

			`## Entries`

fix(ci): make portless optional for windows installs 2026-03-04 17:48:31 +08:00			`### Portless breaks Windows installs`

			`- Date: 2026-03-04`
			`- Observed by: Codex`
			- Context: GitHub Actions `Test Windows` dependency install on `windows-2022`
			- What was surprising: `portless@0.5.2` is a local dev-only tool, but keeping it in `devDependencies` makes `yarn install` fail on Windows because the package declares `win32` unsupported.
			- Impact: Windows CI fails before build steps run, even though the app does not need `portless` there.
			- Mitigation: Keep `portless` in `optionalDependencies` and make `yarn start` fall back to direct `vite` startup when `portless` is unavailable.
			`- Status: confirmed`
chore(tooling): add knip, test:coverage, and agent guidance 2026-03-07 21:31:20 +08:00
			`### Do not add plebbit-js directly for Electron RPC`

			`- Date: 2026-03-07`
			`- Observed by: Codex`
			- Context: Adding `knip` exposed `electron/start-plebbit-rpc.js` importing `@plebbit/plebbit-js/rpc` as an unlisted dependency.
refactor: org name changed from bitsocialhq to bitsocialnet 2026-03-09 17:01:35 +08:00			- What was surprising: Even though that file imports `@plebbit/plebbit-js` directly, repository policy is to depend only on `@bitsocialnet/bitsocial-react-hooks` and use its transitive copy of `plebbit-js`.
chore(tooling): add knip, test:coverage, and agent guidance 2026-03-07 21:31:20 +08:00			- Impact: Agents may “fix” the unlisted import by adding `@plebbit/plebbit-js` to `package.json`, which violates project policy.
			- Mitigation: Do not add `@plebbit/plebbit-js` to `package.json` for this repo. If `knip` flags `electron/start-plebbit-rpc.js`, handle it with a targeted `ignoreIssues` entry instead.
			`- Status: confirmed`