Complete mybd-pnm docs evidence review.\n\n- Add verified docs disposition inventory and canonical seams.\n- Stage stale duplicate docs under docs/staged-for-removal with a manifest.\n- Refresh generated CLI docs and harden the generator for CRLF/stdin handling.\n\nFollow-up: mybd-xfr for automated docs freshness checks.
Phase 1 of mybd-p71. PR #3704 made docs/CLI_REFERENCE.md and the website
CLI reference pages generated-from-live-help with a --check freshness
gate. The same drift shape exists in many other reference-style docs
across the repo; without a maintenance prompt the same trust gap that
caused GH#3683 will recur.
This commit adds docs/DOC_INVENTORY.md, which:
- Enumerates every hand-written .md file in the repo (246 files; 12
excluded as already covered by PR #3704).
- Classifies each as (a) intentionally hand-written / (b) reference-style
drift candidate / (c) other (snapshots, historical, stubs).
- Identifies the (b) files with a clean machine-readable data source
(config struct, cobra tree, OTel attributes, exit-code constants) and
estimates generator size for each.
- Identifies the (b) files with no clean source as freshness-check only.
- Compares five plausible freshness mechanisms (cron, bd preflight,
CONTRIBUTING checklist, per-doc --check validators, hybrid) and
recommends a hybrid: per-doc --check generators (modelled on PR #3704)
for docs with a clean source, plus an explicit `Last reviewed:` field
(already in production use in docs/SECURITY-DEPENDENCY-EXCEPTIONS.md)
for the rest.
Surprises documented in the inventory include
website/docs/reference/configuration.md being wholly stale (TOML +
BEADS_* env vars vs. the live YAML + BD_* implementation), docs/FAQ.md
opening with "git-based issue tracker", docs/EXTENDING.md being missing
but referenced by an example, a second hand-written CLI reference
inside the plugin skill bundle, and several duplication candidates
(docs/DOLT.md vs docs/DOLT-BACKEND.md; root vs docs/ RELEASING.md).
This is **Phase 1 only**: inventory + classification + recommendation.
Phase 2 (apply hand-written-status markers per doc, file follow-up
beads per category, implement freshness-check code) is scoped after
maintainer review of this inventory.
Tracking bead: mybd-p71.
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>