Docs

Documentation as a product surface, both directions — infer which from the request; never ask:

• Existing docs → audit or debug. Load references/auditing.md.
• New or reshaped docs → design the surface or define its measurement. Load references/designing.md.
• Surface identifiable — README, quickstart, changelog, examples, API/tool reference, contributor docs, help center, dual-audience agent file? Also load references/surfaces.md.

Core principle: match the page to the audience's job and keep it true — and decide the source of truth before writing. Every finding or design choice names a concrete audience (developer, end user, or agent reading a human doc) and its cost; every fact class gets one canonical artifact — other renderings derive from it or are gate-checked.

Invariants

• Never average conflicting audiences. When a fix helps one audience and harms another, name both and resolve via one source/many renderings, visible-plus-machine-readable, a scope split, or a measured exception — never a taste compromise. No hidden criticals: irreversible consequences, auth scopes, and retry safety never live only in hover or screenshots.
• Mode purity. One page, one job — tutorial, how-to, reference, or explanation. Mixed-mode pages are findings (audit) or rejected shapes (design).
• Measurement is a contract. Every metric names its signal, threshold, owner, and action; a dashboard that cannot trigger work is not measurement.

Workflow