yatm/docs/development/documentation.md

Documentation Rules

How repository documentation is owned, decided and updated. Contributors follow these rules for every change to a document.

Documentation Ownership

Every maintained fact has one owner. Other documents link to that owner instead of restating it.

Location	Owns	Does not own
Root README.md	Released product introduction, quick start and documentation entry points	Development status, architecture detail or repeated runbooks
Root CONTEXT.md	Domain vocabulary and core domain invariants	Schemas, algorithms, task notes or UI layout
Root AGENTS.md	Contributor rules, safety gates, repository layout and required verification	Product or architecture contracts
Root TODO.md	Concise confirmed pending work with source Issue links	Detailed designs, implemented behavior or completed-work history
docs/README.md	Developer entry, complete documentation index and the pre-stable compatibility policy	Daily-use instructions or documentation rules
docs/operations/index.md	User entry for installation, configuration and operation	Architecture, contributor rules or test procedures
docs/architecture/	Current implemented behavior, module interfaces, invariants and durable constraints	Proposals, implementation plans, acceptance transcripts or superseded behavior
docs/operations/	Packaged user guides: current setup, migration, configuration, use and maintenance	Domain definitions, architecture specifications, test procedures or measurement results
docs/development/	Contributor procedures: documentation rules, code layout, checks, E2E, performance and the Demo	Release gates, user procedures or product contracts
docs/release/	Maintainer release procedures: SOP, builds, package acceptance, the physical Tape gate and physical measurements	Contributor checks, user procedures or measurement research
docs/research/	Public technical studies, evidence, limitations and evaluation of possible approaches	Product guarantees, implementation backlogs, private incident reports or raw acceptance logs
.agents/skills/yatm/	Installed agent operating and safety instructions	Human-facing architecture or change history
Component README.md files	Commands and usage local to that component, such as frontend/ conventions	Product behavior owned by docs/

Decision Authority

Within overlapping scope, broader accepted constraints bound narrower descriptions: the repository engineering rules, the domain invariants and compatibility policy, the architecture overview, area architecture, operations guides, and finally implementation and tests. A lower level may provide evidence and implementation detail, but its existence cannot justify complexity or override a broader decision. When they conflict, update the lower-level documents, code and tests together.

The repository intentionally has no documentation archive, ADR archive or redirect stubs. Git already retains deleted text and rationale. Root TODO.md records concise confirmed pending work; detailed implementation plans belong in an Issue or pull request. Remove completed TODO items instead of retaining a work history. Public research follows the scope above. Published change notes belong to GitHub Releases. Raw acceptance logs, checksums, measurements, screenshots and host-specific reports belong in CI artifacts rather than Markdown.

Update Workflow

1. Establish the intended behavior from the decision authority above, then inspect CONTEXT.md, the owning document and the implementation. A mismatch is something to resolve, not a reason to promote the current implementation into a requirement.
2. Update the implementation, semantic tests, owning architecture document and affected operating guide together. Describe the final behavior in present tense; remove the replaced text instead of marking it historical, implemented or superseded.
3. Keep unsettled implementation designs in a PR or Issue. Public studies may evaluate alternatives in docs/research/, with evidence, assumptions and remaining proof clearly identified. After implementation, update the current architecture and link to research for supporting evidence. Update or remove invalidated research conclusions instead of accumulating superseded studies.
4. Keep implementation detail only when callers or maintainers must know it to use the module correctly. Function names, CSS placement, one measurement, one candidate checksum and step-by-step development history belong in code, tests or verification output.
5. Keep repository documentation self-contained. Every repository-relative link or file reference must resolve to a tracked file, or to a new file committed in the same change; external references use stable public URLs. Private notes, ignored artifacts and machine-local paths are never sources for repository documentation.
6. Before delivery, run make check or at minimum node dev/check-documents.mjs and git diff --check. The document check enforces the allowed tree, complete index, valid relative links and the absence of private/history references.

For research, use official specifications and source code together with relevant original community reports and maintainer responses. Record what was observed, what was actually resolved and which explanations remain hypotheses; a forum's resolved label alone is not evidence of a verified fix. Use stable public citations and concise summaries. Keep credentials, local paths, device identifiers, private host details and raw logs out of public studies; include only the technical context needed to assess the evidence. Hardware measurements establish the tested configuration's behavior, while general guarantees require an applicable specification or other evidence with a defined scope.

Use English Markdown, short topic-based kebab-case filenames and repository-relative links. Current architecture filenames are version-independent. Adding a new documentation file requires a distinct current owner that cannot be expressed clearly in an existing file; update this index in the same change.