docs/README.md
This directory contains user documentation, maintainer runbooks, architecture guidance, active plans, and research. These have different authority: a plan or research note does not override the current code, tests, or an accepted decision.
Update these alongside the behavior or workflow they describe:
User-facing documentation lives in wiki/. Sync and operation-log
architecture lives in sync-and-op-log/.
Accepted decisions describe constraints that remain true even after the implementation work is complete:
A decision must state its status and date, the chosen outcome, why it was chosen, and what would justify revisiting it. Superseded decisions remain as history but must link to their replacement.
plans/ and long-term-plans/ contain proposals,
not current behavior. Every active plan should start with:
Proposed, Planned, In progress, or Deferred);When implementation lands, move enduring contracts or limitations into a maintained guide, package README, code comment, or decision record, then delete the completed plan. Do not leave handover notes or “next steps” documents as permanent documentation.
research/ records evidence gathered at a point in time. It is
non-normative unless a maintained guide or accepted decision adopts its result.
Research should state its snapshot date and tracking issue. Large audit outputs
may remain while findings are being triaged, but verified work should move to
issues and durable safety constraints should move to maintained documentation.
Delete a research note once its conclusions have moved into a maintained guide, a decision record, or tracked issues. Git history keeps it retrievable.
A finding frozen against a past commit decays silently, so state what would make
it wrong: any claim about which releases carry a change must be re-derived with
git tag --contains, never recalled, because the next tag can invert it without
any code changing.
When changing behavior or operations:
npm run docs:check-links.