Documentation Audit

Last verified: 2026-07-26 against current checkout c09254f.

This audit covers Markdown documentation in the DocGen repo, excluding vendored dependencies, generated dependency folders, generated output, and local audit scratch directories.

Inventory Reviewed

• Root docs: README.md, CLAUDE.md.
• Package docs: docgen/README.md.
• Canonical docs: docs/README.md, tutorials, how-to guides, reference, explanation, design, releases, and solutions.
• Internal planning records under docs/design/.
• Release records under docs/releases/.
• Per-organization solution docs under docs/solutions/.
• Superpowers design/plan records under docgen/docs/superpowers/.
• Evaluation reports under docgen/eval_reports/.
• Fixture/sample Markdown under docgen/src/docgen/fixtures/ and MCP fake data.

Findings Before Standardization

• DocGen already had a real Diataxis documentation home with tutorials, how-to guides, reference, and explanation.
• Release PRDs/TDDs/stories and design records were already separated from product docs.
• Per-organization solution docs were already indexed.
• The missing standard pieces were an explicit product layer, documentation-standard.md, documentation-audit.md, a runbook index, and a few reference/explanation map pages.
• docgen/README.md still referenced old domain-model location text.

Changes Made

• Added this audit record.
• Added Documentation standard.
• Added product context pages under product/.
• Added Runbooks.
• Added reference maps for /v1, configuration, and tenancy.
• Added architecture explanation.
• Added a solution-onboarding how-to.
• Updated docs/README.md so the product layer and runbooks are first-class.
• Updated reference/README.md, explanation/README.md, and how-to/README.md to include the new standard pages.
• Fixed the stale domain-model pointer in docgen/README.md.

Remaining Caveats

• Several release/design records intentionally preserve historical statuses such as draft/stub. Current behavior should be read from the canonical docs and shipped code, not inferred from one historical record alone.
• Some generated/demo Markdown lives under package fixture and evaluation folders. Those files are sample content, not product documentation.

Validation

• Local Markdown link check passed after this standardization pass.
• Whitespace check passed after this standardization pass.