Commit graph

4 commits

Author SHA1 Message Date
matt wilkie
7044802d65
Document project scope boundaries (mybd-1fn) (#3842) 2026-05-13 06:49:11 -07:00
matt wilkie
ec116c46f5
Consolidate docs evidence review inventory
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.
2026-05-09 07:21:46 -07:00
matt wilkie
92f539d0ef
docs: resolve legacy extension guide reference (#3810) 2026-05-08 08:24:31 -07:00
matt wilkie
5385cb86a6
docs: add hand-written doc inventory and freshness recommendation (#3706)
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>
2026-05-05 19:36:54 -07:00