AGENTS.md — The documentation standard

This file defines document structure, Markdown tiers, writing rules, and verify-doc-budgets ceilings. Use dsh-doc for placement and validation, and dsh-prose-standard for required coverage and editorial judgment; the archived doc-tiers Agent Note records the historical rationale.

Document structure

These rules apply to human-facing documentation; Agent Notes remain outside their scope. A postmortem is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.

Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.

Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.

Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.

The tier taxonomy: one home per fact

Each fact has one home: the tier whose job it is; elsewhere, link there.

Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root AGENTS.md with a rationale link.

Writing rules

• Document current state. Keep history in commits, PRs, Agent Notes, postmortems, or scoped persistence records. Other prose names live mechanisms, not changes or stack positions. General Session-format prose links version/status authority; retain numbers for version-specific contracts, examples, or evidence.
• Apply the Agent Note creation criteria. Mechanical/local edits are exempt, including local UI changes; keep existing owning notes accurate (scope).
• One physical line per paragraph (verify-md-wrap): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
• Fenced ts blocks must compile (doc-typecheck); a pasted type declaration and its original JSDoc use ```ts type-equiv, while a body-stripped public class declaration uses ```ts public-api; register either in the manifest so neither can drift (mechanics).
• The owning subsystems page updates in the same change that reshapes a documented type. verify-type-equiv catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page (page scoping).
• Pairs update together: Terminology-guided, single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records; dsh-translate-docs remains user-invoked (contract).
• Comments and JSDoc state complete contracts, not reasoning transcripts. Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use dsh-prose-standard for details.
• Write directly: name actors and facts (reference). Reserve seam for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".

Wordcount Budgets

scripts/doc-budgets.manifest.json sets standing-doc ceilings; pnpm run verify-doc-budgets rejects excess or missing files.

When the gate goes red:

1. Relocate content that belongs in another tier; leave a one-line link if needed.
2. Condense content that belongs here but can be shorter.
3. Raise the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.

Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root AGENTS.md ≤ 1,960; architecture.md ≤ 2,400; subtree AGENTS.md ≤ 600, except packages/AGENTS.md ≤ 750 and this file ≤ 1,320; packages/README.md ≤ 994; plus cordis-primer.md 600, defensive-patterns.md 550, testing.md 1,300, examples/AGENTS.md 310. Review governs unbudgeted tiers.

The slop checklist

Hunt these in any doc; dsh-doc runs this list as an audit:

• Duplicated rules: search a distinctive phrase; keep one home and link the rest.
• History outside its permitted tier: state current facts and link the historical owner.
• Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
• Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
• Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
• Rationale repeated beside sibling methods instead of once at the owning capability or helper.
• Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
• Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
• Spec-speak in implemented/ Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the implemented-note instructions.

Repository references

Use relative Markdown links for current files and tags or PR numbers for historical references. verify-md-links checks local targets. Reference validation rejects actual commit identifiers and disallowed organization URLs in maintained files.