Documentation Audits
This directory holds drift reports produced by the doc-keeper agent (#151). The reports tell readers which docs are current, which are stale, and which need archiving.
Canonical paths
latest.md— the most recent drift report (markdown). The docs site (#153) reads this for its landing-page badge.latest.json— same report in machine-readable form (#156). Downstream tooling reads this.
History
Date-stamped reports are kept here so the docs-vs-code drift can be seen over time:
| File | Generated by | Notes |
|---|---|---|
doc-audit-YYYY-MM-DD.md | /doc-audit | Human-facing report for a specific run |
doc-audit-YYYY-MM-DD.json | /doc-audit | Machine-readable counterpart |
Re-running on the same day overwrites both that day’s date-stamped files and latest.{md,json} — deterministic by date.
How a report gets here
/doc-audit
├── runs scripts/doc-keeper/audit.js across docs/, README.md, CLAUDE.md
├── writes doc-audit-YYYY-MM-DD.{md,json}
└── copies them to latest.{md,json}
Rendering on the site (#156)
The docs site reads docs/audits/latest.md and surfaces:
- A “Docs last verified” date on the landing page (from the report’s
generated_at). - An “Audits” entry in the site nav linking to this directory.
- Per-doc verified/needs-update/archive badges (consumed from
latest.json). - A history page indexing every date-stamped report in this directory.
The Quartz emitter and theme component live at templates/docs-site/quartz.config.ts (managed defaults block) — see #156 for the exact wiring.
See also
- doc-keeper agent — the auditor’s identity and rules
- /doc-audit skill — read-only audit invocation
- /doc-sync skill — mechanical drift fixes
- doc-drift schema — JSON shape of
latest.json - issue #151 — doc-keeper feature
- issue #156 — drift report on the docs site