Improve documentation: write evergreen design docs in docs/design/ for complex subsystems (ghost-system.md as the template) #100

Use case

`docs/design/ghost-system.md` is excellent — 29 KB of evergreen source-of-truth design for the provisional-record bridge between the proxy semantic stream and durable JSONL transcript. It's the standard the rest of the architecture's hard parts should be documented to. Today it's the only such doc. Other complex subsystems rely entirely on inline WHY comments (good) and on the original author's memory (bad). When the original author isn't around to ask, the next person spends hours re-deriving rules that were obvious to whoever wrote them.

The policy is already documented at `docs/design/README.md`: these are evergreen sources of truth, touched only when subsystem shape changes (not for bug fixes, refactors, or tuning). The template, voice, and rigour are already set by `ghost-system.md`. The gap is breadth.

Example

A new agent picks up issue #94 (commands miss dispatch agents) and needs to understand the grid + Dispatch + buried + detached + pinned model end-to-end. Today they have to read `workspaceStore.ts`, every selector under `workspace/dispatch/`, every action under `hook/actions/`, and reconstruct the invariants. With a `docs/design/workspace-model.md` written to the ghost-system.md standard, they'd read one doc, understand the five-bucket model (grid / detached / buried / pinned / focused), the placement invariants, the cross-cutting rules (a session is in exactly one of grid/detached, never both; pinning is a display concern not a scoping concern), and start their work informed.

(Optional) Sketch

The shape is straightforward — work piece-by-piece, one PR per subsystem doc.

Suggested initial set (ranked by how often the absence has bitten us):

1. `docs/design/workspace-model.md` — grid / detached / buried / pinned / focused. The five-bucket session-placement model, the invariants between them, why we have all five (each one represents a different lifecycle phase). PR Include detached Dispatch agents in active-tab transcripts template #83 + issue Commands target grid-only sessions — dispatch agents recurringly fall through every command path #94 are both consequences of this not being written down.

2. `docs/design/conditions-system.md` — the per-provider conditions architecture (`ProviderConditionOutlet` shared switchboard, per-provider outlets, the discriminated-union snapshot type, the semantic-first / screen-fallback evaluator pattern). Lines up with the work in issue Extend conditions system to consume semantic events (proxy channel) alongside screen parsing — unlocks broad coverage (/model, /add-dir, many more) #99.

3. `docs/design/three-channel-model.md` — semantic / screen / committed. Partially covered in `ghost-system.md` already, but worth extracting because every other doc references it. Defines which channel is authoritative for what, what the three flavours of "truth" mean, why we don't collapse to one channel.

4. `docs/design/session-lifecycle.md` — spawn → resume → bury → detach → kill → revive. The state machine, the cleanup invariants per transition, why workspace state + main-process registry + tmux + on-disk transcript all have to stay coherent. Issue Commands target grid-only sessions — dispatch agents recurringly fall through every command path #94 (dispatch resolution) and the heap-spike investigation (52 metadata rows / 11 panes) both touched this.

5. `docs/design/perf-and-watchdog.md` — system-perf header, popover, heap watchdog, AGENT_CODE_PERF env gate, OTEL pipeline, debug retention. The thresholds, the trip conditions, the file layout under `~/.config/agent-code/`. Just shipped (PR feat(perf): always-visible main-process heap + rss badge in header #76 + feat(system-perf): expand popover with heap-space + stress signals + on-demand snapshot #86 + perf(worktree-activity): stream JSONL transcripts instead of readFile #87) so this is fresh in the codebase but still entirely undocumented as a system.

6. `docs/design/tmux-persistence.md` — TmuxRegistry, naming, recovery, reconciliation against workspace.json on boot. The invariants that let terminals survive across restarts.

7. `docs/design/proxy-pipeline.md` — mitmproxy / SSE / Responses adapter. How the proxy server is spawned, what state lives where, CA bootstrap, the per-flow lifecycle, the contract with the headless packages. PR Update Claude proxy CA bootstrap #81 + the proxy-events retention investigation both happened against an implicit version of this.

8. `docs/design/transcript-translation.md` — Claude↔Codex via `agent-transcript-parser`, ghost-vs-real sidecars, round-trip fidelity, why a sidecar exists, when conversions can short-circuit. `ghost-system.md` references this but doesn't replace it.

(Not every subsystem needs one. `ghost-system.md` lists itself as needing a doc because the alternative was "future-you re-derives this from scratch". The bar for a new doc here is "would a fresh agent need this to operate safely on the subsystem?" — if a careful read of code + comments is enough, no doc needed.)

Writing rules (from existing `docs/design/README.md`, restated for emphasis):

• Source-of-truth, evergreen. Touched only when subsystem shape changes.
• Reference from inline code comments where load-bearing (`// See docs/design/.md`).
• Not a changelog. Not a running note. Not a recap of fixes.
• Voice: explain why each piece is shaped the way it is, what would make it wrong, what we tried first that didn't work. `ghost-system.md` is the gold standard — match its rigour.

Process:

• One PR per doc. Each PR is text-only (no code changes) so review is easy.
• Author the doc, then audit a handful of inline comments in the relevant subsystem and replace any duplicated WHY content with `// See docs/design/.md` references. The doc carries the long explanation; comments stay focused on the local invariant.
• Order: start with refactor: reshape tree, break up god-files, go all-absolute imports #1 (`workspace-model.md`) since it unblocks the most active issue traffic (Commands target grid-only sessions — dispatch agents recurringly fall through every command path #94 et al.).