Living Documentation

In one line: Document at build time, not retroactively — docs are a deliverable on the same tier as code and tests, and they double as AI context.

What: Every architectural decision and capability is documented in a structured Docusaurus site as it is built. A feature is not complete until its documentation exists.

Why: Documentation debt compounds faster than technical debt. Code can still be read; the reasons behind it — why this approach over alternatives, what constraint shaped this API — are invisible in the code and gone once they leave working memory.

Documentation can also supply AI context. Verify which instructions and references the selected host actually loads; a linked page is not necessarily retrieved. Explain why a decision was made, its authority and its evidence. Whether that context improves proposals must be measured in the adopter's tasks, not assumed from its presence.

The intended feedback loop is:

1. Business and engineering review the proposed intent and design; the accountable owner approves the exact meaning.
2. The execution team receives those approved revisions and produces a candidate.
3. Review compares implementation, tests and documentation against that intent.
4. Audience-appropriate pages publish the checked claims and their evidence limits.
5. Later questions or observations identify discrepancies for review; they do not silently amend approved intent.

Text equivalent: approved intent guides a candidate, evidence checks the candidate, and later feedback returns to the proper owner. Publication is a reviewed projection, not a new authority source.

Stale documentation can mislead. Same-change documentation and scoped gates reduce that risk; they do not establish factual currency. Periodic claim review still matters for external dependencies, changed business rules and runtime observations that a code-diff gate cannot see.

The five audiences for documentation:

Audience	What they need	How the docs serve them
Prospects and partners	Credibility at first glance	Architecture depth and evidence-backed claims demonstrate engineering capability
AI agents	Narrative context beyond code	Specifications, ADRs, and analysis provide the "why" raw code cannot convey
Developers	Architecture truth	API references, data-flow diagrams, and component registries for onboarding and navigation
Regulators	Compliance depth	Traceability, data-processing records, and audit-trail documentation
Team	Alignment as the system grows	ADRs prevent re-litigating decisions; pillar docs prevent scope ambiguity

Evidence: Section 11.4 describes the review obligation; §7.5 identifies executable co-change and generated-freshness checks and their limits. Those mechanisms inspect declared relationships and reproducibility, not the truth of a page. Report the reviewed claims, exact revisions and observed discrepancies. No fixed code-to-doc commit ratio or improvement in delivery speed is established by this procedure.

How: Four mechanisms, detailed in Section 11:

1. The documentation commit pattern — every architecture-changing branch ships code + ADR (if applicable) + doc page update + build verification, enforced at review.
2. Same-repo Docusaurus generation — pin the source and generated projection to the candidate; deployment and runtime evidence retain their own identities. Colocation alone does not prove the site is current.
3. Structured content organization — navbar sections by audience, so no flat undifferentiated wiki.
4. The AI context loop — memory → design specs → ADRs → architecture pages cross-reference into a navigable knowledge graph for humans and AI alike.

Architecture-as-Code (extension). Appendix H separates the optional metadata/index design from the helpers actually shipped:

1. Structured frontmatter — adopt and validate a metadata profile before relying on fields such as components, tests, depends_on, last_verified and status. They are references and claims, not evidence of actual execution or approval.

2. Optional architecture index — a derived component-to-page index can aid navigation. No general architecture-index plugin is supplied by this kit; an adopter must implement and verify its mapping, coverage and audience behavior.

3. Sync surfacing — the supplied age hook checks supported dates in the selected Markdown/MDX corpus, with a default 30-day window. It does not map changed components to claims or assess factual correctness. Its advisory output may be debug-only in the host.

4. Documentation-first development — a planned page can make proposed behavior tangible during design. Its creation and subsequent status changes require actual work; installing a skill does not automatically create or approve it.

5. Test mapping — a tests field suggests relevant tests. The supplied Stop hook does not collect or verify execution receipts. A future executor needs exact candidate/environment identity, expected and executed selections, outcomes and visible omissions.

Evidence: Exercise templates/hooks/check-doc-staleness.sh with current, old, invalid and missing metadata; it reports age/assessment limits without changing the files. Exercise the separate §7.5 gates against their declared committed/generated subjects. An optional index or future execution service needs its own acceptance evidence; neither is implied by the shipped hooks.

---