| name | archdoc |
| description | Generate or refresh an architecture walkthrough doc (lambda/scripts/archdocs/*.md) for a subsystem or feature branch — top-down text walkthrough with verified clickable file:line links, mechanically extracted public API, invariants, and a debugging map. Use when asked to map/document/explain the architecture of a subsystem, feature, or branch, or to refresh an existing archdoc after changes. |
archdoc — architecture walkthrough docs
Produce a markdown doc the user reviews instead of reading the implementation: data structures, interfaces, fn signatures, and how data flows through them — entry point down to details. The user reviews diffs of this doc to track architecture changes, and asks questions about it inline via aireviewer; answers get folded back into the text.
Canonical example: lambda/scripts/archdocs/liftoeditor.md. Match its structure and tone.
Ground rules
- Location:
lambda/scripts/archdocs/<subsystem>.md. Never docs/ (served publicly via webpack /docs/*). Never a claude.ai artifact — the deliverable is the repo file. Don't commit; the user commits.
- Text-first: plain language ("we load X, pass these props; under the hood it calls Y to get Z"), verbatim signatures in code blocks, simple ASCII sketches only. No mermaid, no SVG, no flow diagrams — the user explicitly doesn't want them.
- Every file:line is a clickable relative link:
[thunks.ts:1263](../../../src/ducks/thunks.ts#L1263) (VSCode preview + Ctrl+click and GitHub both jump to the line). Relative from lambda/scripts/archdocs/, so repo root is ../../... Links don't work inside code blocks — there, use // :N line-number comments and link the section/file heading instead.
- Implementation details of individual fn bodies are NOT the content. What matters: types, signatures, who-calls-whom, where decisions/state live, what must stay true.
