docs(#260): rewrite CLAUDE.md against the app that actually exists

[kevinthelago]

Closes #260.

CLAUDE.md calls itself "the authoritative project reference for the AI agent — read it at the start of any new session before touching code." It was describing a shell that has not existed for months.

That is not cosmetic. Several #234 children were written from its picture of the app and target files no route reaches — see #236, and the plan half of #245, both invalidated by 54c13fb (2026-07-25).

What changed

1. "There are no automated tests" — the most damaging line. There are ~51 test files and 500+ tests behind npm test, and CI runs them (install → typecheck · test · export). An agent trusting that sentence skips the gate guarding the entire payload contract. The new text also records the RN-free constraint: tests run under tsx --test, so a tested module must not import react-native — the reason pure logic belongs in src/lib/**.

2. Folder structure rewritten from the real tree. The old one invented eight files — find/edit/git/run/files/settings tabs, (live), (fleet), ChatScreen — and omitted everything that now carries the app: tunnel/, mirror/, pages/, kit/, graph/, sessions/, alerts/.

3. "What This App Is" reframed as a read-only desktop mirror plus session chat, a local planner, and a surviving repo-client half — not the AI-first IDE the old text promised. Adds the demo-data note (#250) so first-run behaviour is not a mystery.

4. Key Data Flows now documents:

• the mirror path — store_state → MirrorContext → page selector → component, including chunk reassembly;
• the separate plan_state/plan_event live-plan path, explicitly flagged so nobody confuses it with the plan store domain again;
• the two-layer contract parity harness, including the rule that moving a domain from PENDING_DOMAINS into DECODERS is the definition of done for its issue.

5. Known Issues replaced. Every previous entry was already fixed — duplicate IconBtn/Surface, ChatScreen, ThemeContext, llm.ts, gitClient.ts, the duplicated underscore workflows. A section that is 100% noise trains the reader to skip the section that should hold the real traps.

It now leads with the 24 orphaned source files and the grep that finds them, then the live traps: RN-free tests, designPage.ts not being plain ASCII (grep reports it binary), CSS colour values RN cannot parse, and syncing against base-studio-code develop rather than main.

6. Agent tool list corrected — ten tools, not the five listed.

Verification

Every src/, app/, and .github/ path referenced in the new file was checked to exist. The orphan list comes from an import-graph walk rooted at every app/ route.

Docs-only change; no source touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RAPZC6xEyCrH9qSKUKLQdy

[github-actions]

📦 Preview build ready

Artifact: preview-pr-261-bda2bb4267c7996702107caeefd68ae513cfcb03

⬇️ Download from Actions run

Built from commit bda2bb4