beads/docs/DOC_INVENTORY.md
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

36 KiB
Raw Blame History

Documentation Inventory

Status: Phase 1 audit (mybd-p71). Inventory + classification + freshness-mechanism recommendation. Phase 2 (apply hand-written-status markers, file follow-up beads, implement freshness check) is scoped after maintainer review.

Background: PR #3704 made docs/CLI_REFERENCE.md and website/docs/cli-reference/ generated from live --help output, with a --check freshness gate. The original drift problem (GH#3683) was that hand-written CLI reference content silently fell out of date for releases. That same drift shape exists in many other reference-style docs; without a maintenance prompt, the trust-gap recurs. This inventory enumerates every hand-written .md file in the repo and classifies it so we can decide which ones need the same treatment.

Classification key

  • (a) Intentionally hand-written — narrative, tutorial, ADR, design doc, onboarding, philosophy, architecture overview. Should never be auto-generated. Drift risk is mostly stylistic.
  • (b) Reference-style — enumerates flags / config keys / env vars / error codes / commands / supported platforms / integration hooks. Same drift shape as the original docs/CLI_REFERENCE.md. Candidate for full or partial generation, OR a freshness-check prompt if no machine-readable data source exists.
  • (c) Other — doesn't fit cleanly. Usually pointer/stub files, time-stamped audit reports, version snapshots, or scope-bleed candidates.

Drift risk: subjective judgement based on (1) how reference-y the content is, (2) how concretely tied to the current code it is, (3) whether the doc has already drifted (sampled spot-checks).

Scope

  • Total .md files inventoried: 246 (out of 258 in the repo; 12 already covered by PR #3704 are excluded — see below).
  • Excluded as generated by PR #3704: website/docs/cli-reference/*.md (6 files) and website/versioned_docs/version-1.0.0/cli-reference/*.md (6 files).
  • Excluded as Docusaurus version snapshots: website/versioned_docs/version-1.0.0/** non-cli-reference files are inventoried as a single block — they are point-in-time copies of website/docs/** and rotate via the Docusaurus versioning workflow rather than free-form editing. They inherit the classification of their live counterpart and are listed once for the directory.
  • Excluded entirely: llms.txt, llms-full.txt (generated), .git/, .beads/, vendor/, node_modules/, website/build/, .docusaurus/.

1. Inventory

1.1 Repository root

File Class Purpose Drift risk
README.md a Public-facing project introduction, install pointers, feature highlights. med — version numbers and feature lists drift.
CONTRIBUTING.md a Contributor onboarding, dev setup, PR workflow. low–med — go.mod version reference, build commands.
CHANGELOG.md c Release log; updated per release. Not "hand-written" in the drift sense. low — append-only by convention.
CODE_OF_CONDUCT.md not present in repo — —
SECURITY.md a Security disclosure policy. low.
AGENTS.md a Agent quick-reference (workflow, bd commands). high — embeds command lists & flag examples. See note below.
AGENT_INSTRUCTIONS.md a Long-form agent operational instructions. med — quotes specific commands and flags.
CLAUDE.md a Claude Code agent instructions; embeds bd command examples. high — same drift surface as AGENTS.md.
PR_MAINTAINER_GUIDELINES.md a Maintainer policy on PR triage. low.
RELEASING.md a Release process narrative. med — script names, version-bump steps.
FEDERATION-SETUP.md a Federation user guide. med — config keys, command names.
NEWSLETTER.md c One-off release-cycle newsletter (v0.62.0). Time-stamped. n/a — historical.
ARTICLES.md c Curated external links list. low — additive.
BENCHMARKS.md a Benchmark guide. low.
build-docs.md a Build/version infrastructure overview. Lives at root, oddly placed. med.

1.2 docs/ (top level)

File Class Purpose Drift risk
docs/CLI_REFERENCE.md b → about-to-be-generated Big CLI command reference. Version: 0.21.0+ header is already stale (tip is much higher). PR #3704 will replace this with generated content. high today; resolved by #3704 once merged.
docs/CONFIG.md b Big table of every Viper key, env var, flag, default. Classic drift shape. high — must match Go config struct + flag definitions.
docs/LABELS.md a (mostly) / b (partly) Mostly narrative philosophy + workflow, but contains tables of suggested labels and command flag enumerations. med.
docs/DEPENDENCIES.md a Narrative on dependency types & gates. low–med.
docs/JSON_SCHEMA.md b Documents the --json envelope contract and migration. Tied directly to a runtime version constant. high.
docs/ERROR_HANDLING.md b Pattern guidelines + concrete file/line citations into cmd/bd/*.go. Line numbers will drift the moment any file is edited. high — line numbers in source citations.
docs/INSTALLING.md a (narrative) / b (partly) Install matrix + per-platform commands. med — install URLs, package names, supported platforms.
docs/UNINSTALLING.md a Uninstall walkthrough. low.
docs/QUICKSTART.md c Short pointer file linking to website Quick Start. Designed to be thin. low.
docs/SETUP.md b bd setup recipe-based reference. Version: 0.30.0+ header pinned. high — recipe list and flags.
docs/SYNC_SETUP.md a Narrative sync setup walkthrough. med.
docs/FAQ.md a FAQ. First sentence currently says "git-based issue tracker", which contradicts the Dolt-native architecture — already drifting. high.
docs/TROUBLESHOOTING.md a (narrative) / b (partly) Long doc; opens with a debug-env-var table that is exactly the drift shape. high.
docs/ARCHITECTURE.md a Overall architecture overview. med.
docs/INTERNALS.md a Internal implementation deep-dive (auto-flush, etc.). med.
docs/ROUTING.md a Multi-repo auto-routing design. med.
docs/MULTI_REPO_AGENTS.md a Agent-facing multi-repo guide. med.
docs/MULTI_REPO_MIGRATION.md a Human-facing multi-repo migration. med.
docs/REPO_CONTEXT.md a How bd resolves repo context across cwds. low–med.
docs/PROTECTED_BRANCHES.md a Protected-branch workflow. med.
docs/MOLECULES.md a Molecules concept doc. low–med.
docs/METADATA.md a Issue metadata field semantics. low–med.
docs/DOLT.md a Dolt backend overview. Overlaps docs/DOLT-BACKEND.md substantially — possible duplication / scope-bleed. med.
docs/DOLT-BACKEND.md a Dolt backend overview (longer, with feature table). Overlaps DOLT.md. med.
docs/ATTRIBUTION.md a Credit notes for removed merge engine. low.
docs/COLLISION_MATH.md a Math behind hash-ID collision thresholds. low.
docs/COMMUNITY_TOOLS.md c Curated list of community UIs/extensions. Additive list, near-zero internal drift but external maintenance burden. low (internal) / med (external links).
docs/CONTRIBUTOR_NAMESPACE_ISOLATION.md a Design doc for namespace isolation. low (status-stamped).
docs/COPILOT_INTEGRATION.md a Copilot integration walkthrough. med.
docs/CLAUDE_INTEGRATION.md a Claude Code integration design. med.
docs/CLAUDE.md a Claude Code architecture pointer (mirrors root CLAUDE.md partially). med — duplicates content from root.
docs/AIDER_INTEGRATION.md a Aider integration walkthrough. med.
docs/GIT_INTEGRATION.md a Git integration overview. med.
docs/ICU-POLICY.md a Build-tag policy doc. low.
docs/LINTING.md b Enumerates current lint warnings ("22 issues as of Nov 6, 2025"). Hard-pinned snapshot. high — date-stamped count.
docs/ADAPTIVE_IDS.md a Adaptive hash ID feature doc. low.
docs/ADVANCED.md a / b Advanced features (rename, merge, compaction). Mixes narrative with command refs. med.
docs/EXCLUSIVE_LOCK.md a Exclusive lock protocol doc. low–med.
docs/ANTIVIRUS.md a Antivirus false positives narrative. med — vendor names, version numbers.
docs/RECOVERY.md b Named-error recovery playbooks. Each anchor matches an exit-code constant in code (init-force-refused, exit code 10, etc.). high — error codes & names tied to source.
docs/RELEASE-STABILITY-GATE.md a Release stability gate policy. low.
docs/RELEASING.md a Release process. Duplicates root RELEASING.md. med — possible duplication.
docs/SECURITY-DEPENDENCY-EXCEPTIONS.md c Already has a "Last reviewed: 2026-04-28" line — this file IS the freshness-marker pattern in production. n/a — exemplar.
docs/PLUGIN.md a Beads Claude Code plugin user guide. med.
docs/PERFORMANCE_TESTING.md a Performance testing guide. low.
docs/OBSERVABILITY.md a (mostly) / b (partly) OTel guide; opens with port/service table. med.
docs/RULES_AUDIT_DESIGN.md a Design doc for bd rules audit (status: ready, target: upstream PR). low — design-stamped.
docs/UI_PHILOSOPHY.md a Tufte-inspired UI philosophy. low.
docs/INTEGRATION_CHARTER.md a Scope-boundary policy for tracker integrations. low.
docs/TESTING.md a Testing guide. Cites "~41,000 lines of code across 205 files". med — size stats drift.
docs/TESTING_PHILOSOPHY.md a Testing philosophy. low.
docs/README_TESTING.md a Two-tier testing strategy (overlaps TESTING.md). low — possible duplication.
docs/TODO.md a bd todo command philosophy + usage. med.
docs/WORKTREES.md a Worktree compatibility guide. med.
docs/ADO_CONFIG.md b All config options for bd ado sync. Reference-shaped. high.
docs/GETTING_STARTED_ANALYSIS.md c Time-stamped 2026-04-05 analysis report (audit one-shot). n/a — historical.
docs/audit-sync-mode-complexity.md c Time-stamped 2026-03-04 audit. n/a — historical.
docs/graph-links.md a Graph-links between issues (replies_to, etc.). low–med.
docs/messaging.md a Messaging-as-issue-type architecture. low–med.
docs/pr-752-chaos-testing-review.md c PR-specific review notes. n/a — historical.
docs/ADO_CONFIG.md (see above)

1.3 docs/adr/

File Class Purpose Drift risk
docs/adr/0001-multi-remote-approach.md a ADR. Should never be regenerated. low — ADRs are immutable by convention.
docs/adr/0002-init-safety-invariants.md a ADR. low.

1.4 docs/design/

File Class Purpose Drift risk
docs/design/dolt-concurrency.md a Design doc, status-stamped. low.
docs/design/kv-store.md a Design doc, draft. low.
docs/design/otel/otel-architecture.md a (mostly) / b (partly) OTel architecture; includes attribute/span tables that mirror code constants. med.
docs/design/otel/otel-data-model.md b "Complete schema of all telemetry events emitted by Beads." Pure reference table content. high.

1.5 docs/dev-notes/

All five files are time-stamped audit reports / refactor plans. Classification is uniformly (c) other — historical.

File Class Purpose Drift risk
docs/dev-notes/ERROR_HANDLING_AUDIT.md c Audit report dated 2025-11-24, scope cmd/bd/*.go. n/a — historical.
docs/dev-notes/MAIN_TEST_CLEANUP_PLAN.md c Cleanup plan; resolved. n/a.
docs/dev-notes/MAIN_TEST_REFACTOR_NOTES.md c Notes for bd-1rh follow-up; status RESOLVED. n/a.
docs/dev-notes/MANUAL_GITHUB_GIT_REMOTE_TEST.md c Manual test plan, time-bounded. n/a.
docs/dev-notes/TEST_SUITE_AUDIT.md c Test suite audit (bd-c49). n/a.

Suggestion (out of phase-1 scope): consider archiving docs/dev-notes/ under docs/archive/ or pruning resolved entries — they've already drifted past relevance.

1.6 cmd/bd/

File Class Purpose Drift risk
cmd/bd/AGENTS.md a Subdirectory agents file (mirrors root AGENTS.md content partially). med — duplication.
cmd/bd/docs.md a "Noridoc" overview of cmd/bd/. low–med.

1.7 scripts/

File Class Purpose Drift risk
scripts/README.md a / b Lists utility scripts and what each does. Auto-discoverable from the directory. med.
scripts/docs.md a "Noridoc" overview. low.
scripts/generate-newsletter_README.md a Newsletter generator instructions. low.
scripts/repro-dolt-hang/INCIDENT-REPORT.md c One-off 2026-02-23 incident. n/a — historical.

1.8 examples/

All examples/*/README.md files are narrative tutorials. Classification: uniformly (a). Drift risk is med-low; main risk is example commands or referenced doc paths going stale.

File Class Purpose Drift risk
examples/README.md a Examples index. low.
examples/bash-agent/README.md a Bash agent walkthrough. med.
examples/bd-example-extension-go/README.md a / broken link References docs/EXTENDING.md which does not exist in this tree — already drifted. high (because of the dead link).
examples/claude-desktop-mcp/README.md a Claude Desktop MCP example. med.
examples/compaction/README.md a Compaction examples. low.
examples/contributor-workflow/README.md a OSS contributor workflow. med.
examples/formulas/README.md a Starter formulas. low.
examples/library-usage/README.md a Beads-as-library example. med.
examples/linear-workflow/README.md a Linear integration walkthrough. med.
examples/multi-phase-development/README.md a Multi-phase workflow. low.
examples/multiple-personas/README.md a Multi-persona workflow. low.
examples/protected-branch/README.md a Protected-branch example. med.
examples/python-agent/README.md a Python agent walkthrough. med.
examples/startup-hooks/README.md a Startup hook scripts. low.
examples/team-workflow/README.md a Team workflow example. low.

1.9 integrations/

File Class Purpose Drift risk
integrations/beads-mcp/README.md a / b MCP server user guide; lists MCP tools. high — tool list mirrors code.
integrations/beads-mcp/CHANGELOG.md c MCP changelog. low — append-only.
integrations/beads-mcp/CONTEXT_ENGINEERING.md a Context-engineering design narrative. low.
integrations/beads-mcp/CONTEXT_MANAGEMENT.md a Multi-repo context handling. low–med.
integrations/beads-mcp/PYPI.md a PyPI publishing guide. low.
integrations/claude-code/README.md a Claude Code integration overview. med.
integrations/claude-code/commands/plan-to-beads.md a Slash-command spec. low.
integrations/junie/README.md a Junie integration overview. med.

1.10 npm-package/

File Class Purpose Drift risk
npm-package/README.md a / b npm-package user-facing README. med.
npm-package/PUBLISHING.md a Publishing process. low.
npm-package/TESTING.md a npm test strategy. low.
npm-package/INTEGRATION_GUIDE.md a Claude Code Web integration guide. med.
npm-package/CLAUDE_CODE_WEB.md a Claude Code for Web setup narrative. med.
npm-package/LAUNCH.md c One-off "Published v0.21.5!" launch note. n/a — historical.
npm-package/SUMMARY.md c Implementation summary, time-bounded. n/a — historical.

1.11 plugins/beads/

The plugins/beads/skills/beads/commands/*.md files are slash-command specs in YAML-frontmatter form. They enumerate flags & subcommands, just like cobra command help — exactly the drift shape PR #3704 targeted. The plugins/beads/skills/beads/resources/CLI_REFERENCE.md is a second hand-written CLI reference (independent from docs/CLI_REFERENCE.md).

File Class Purpose Drift risk
plugins/beads/README.md a Plugin layout overview. low.
plugins/beads/skills/beads/README.md a Skill description. low.
plugins/beads/skills/beads/SKILL.md a Skill manifest + content. med.
plugins/beads/skills/beads/CLAUDE.md a Maintenance guide for the skill. low.
plugins/beads/skills/beads/agents/task-agent.md a Task-agent prompt. med.
plugins/beads/skills/beads/adr/0001-bd-prime-as-source-of-truth.md a ADR for the skill. low.
plugins/beads/skills/beads/commands/*.md (29 files) b Slash-command specs; each enumerates flags / subcommands. Same drift shape as docs/CLI_REFERENCE.md. high for the larger ones (list.md, create.md, dep.md, template.md, update.md, search.md, workflow.md); med for the small ones (show, stats, sync, version, blocked, restore, reopen, etc.) which mostly point at bd help.
plugins/beads/skills/beads/resources/CLI_REFERENCE.md b Standalone CLI reference (not the same file as docs/CLI_REFERENCE.md). Version: 0.60.0+ header. high — duplicate of the original drift case in a different directory.
plugins/beads/skills/beads/resources/AGENTS.md a Agent-beads reference. med.
plugins/beads/skills/beads/resources/ASYNC_GATES.md a Async gate workflow guide. low–med.
plugins/beads/skills/beads/resources/BOUNDARIES.md a bd vs TodoWrite decision matrix. low.
plugins/beads/skills/beads/resources/CHEMISTRY_PATTERNS.md a Chemistry metaphor patterns. low.
plugins/beads/skills/beads/resources/DEPENDENCIES.md a Dependency types deep-dive. low–med.
plugins/beads/skills/beads/resources/INTEGRATION_PATTERNS.md a Skill-integration patterns. low.
plugins/beads/skills/beads/resources/ISSUE_CREATION.md a Issue creation guidance. low.
plugins/beads/skills/beads/resources/MOLECULES.md a Molecules+wisps reference. low–med.
plugins/beads/skills/beads/resources/PATTERNS.md a Common usage patterns. low.
plugins/beads/skills/beads/resources/RESUMABILITY.md a Resumability guidance. low.
plugins/beads/skills/beads/resources/STATIC_DATA.md a Using bd for static data. low.
plugins/beads/skills/beads/resources/TROUBLESHOOTING.md a Skill troubleshooting. med.
plugins/beads/skills/beads/resources/WORKFLOWS.md a Workflow checklists. low–med.
plugins/beads/skills/beads/resources/WORKTREES.md a Worktree usage in the skill. low–med.

1.12 internal/templates/agents/defaults/

File Class Purpose Drift risk
internal/templates/agents/defaults/beads-section.md a Template injected into project agent files by bd setup. med.
internal/templates/agents/defaults/beads-section-minimal.md a Minimal template. low.

1.13 release-gates/, tests/, top-level misc

File Class Purpose Drift risk
release-gates/be-eqw-gate.md c One-off release-gate evaluation, dated 2026-04-23. n/a — historical.
tests/integration/README.md a Integration test harness overview. low.
tests/regression/DISCOVERY.md c Exploratory log; explicitly "not all findings here are actionable". n/a — exploratory.
.agent/workflows/resolve-beads-conflict.md a Conflict-resolution workflow. low–med.
.claude/test-strategy.md a Test-running rules for Claude Code. low.
.devcontainer/README.md a Devcontainer setup. low.
.github/copilot-instructions.md a Copilot instructions for the repo. med — duplicates parts of CLAUDE.md/AGENTS.md.
winget/README.md a Winget manifest README. low.
website/README.md a (one line) Single-line "Beads Documentation Site" stub. low.

1.14 website/docs/ (live published site, excluding cli-reference/)

All website docs use Docusaurus YAML frontmatter (id, title, sidebar_position). They are hand-written.

File Class Purpose Drift risk
website/docs/intro.md a Site landing page. med — feature list & install commands.
website/docs/architecture/index.md a Architecture overview (mirrors docs/ARCHITECTURE.md). med — duplication.
website/docs/core-concepts/index.md a Core-concepts hub. low.
website/docs/core-concepts/issues.md a Issues & dependencies. med.
website/docs/core-concepts/hash-ids.md a Hash-IDs. low.
website/docs/getting-started/installation.md a / b Install matrix. med — install URLs / package names.
website/docs/getting-started/quickstart.md a Quick Start tutorial (canonical). med.
website/docs/getting-started/ide-setup.md a IDE setup guide. med.
website/docs/getting-started/upgrading.md a Upgrade guide. med.
website/docs/integrations/aider.md a Aider site page. med — duplication of docs/AIDER_INTEGRATION.md.
website/docs/integrations/claude-code.md a Claude Code site page. med.
website/docs/integrations/github-copilot.md a Copilot site page. med.
website/docs/integrations/junie.md a Junie site page. med.
website/docs/integrations/mcp-server.md a MCP-server site page. med.
website/docs/multi-agent/index.md a Multi-agent hub. low.
website/docs/multi-agent/coordination.md a Coordination patterns. low.
website/docs/multi-agent/routing.md a Routing site page. low–med.
website/docs/recovery/index.md a Recovery hub. low.
website/docs/recovery/database-corruption.md a Recovery playbook. med.
website/docs/recovery/merge-conflicts.md a Recovery playbook. med.
website/docs/recovery/circular-dependencies.md a Recovery playbook. med.
website/docs/recovery/sync-failures.md a Recovery playbook. med.
website/docs/reference/configuration.md b Already drifted: documents .beads/config.toml and BEADS_* env vars; the actual implementation uses .beads/config.yaml and BD_* env vars. Schema, sections, and example are wholly stale relative to docs/CONFIG.md. highest in repo.
website/docs/reference/git-integration.md a Git integration site page. med.
website/docs/reference/advanced.md a Advanced features site page. med.
website/docs/reference/troubleshooting.md a Troubleshooting site page (different content from docs/TROUBLESHOOTING.md). med — partial duplication.
website/docs/reference/faq.md a FAQ site page. med — duplicates docs/FAQ.md.
website/docs/workflows/index.md a Workflows hub. low.
website/docs/workflows/molecules.md a Molecules workflows. low–med.
website/docs/workflows/formulas.md a Formulas workflows. med — formula syntax.
website/docs/workflows/gates.md a Gates workflows. low–med.
website/docs/workflows/wisps.md a Wisps workflows. low–med.

1.15 website/versioned_docs/version-1.0.0/ (excluding cli-reference/)

These 28 files are point-in-time copies of website/docs/** produced by Docusaurus' versioning command. They are not free-form-edited; they freeze when a docs version is cut. Classification inherits from the live counterpart. Treat them as (c) version snapshots — they don't need a freshness mechanism (a stale snapshot for v1.0.0 is correct behaviour) but they should be kept in sync the next time a version is cut.

Listed once collectively because the per-file classification is a duplicate of section 1.14.


2. Generation candidates

For each (b) doc with a plausible machine-readable data source. Files marked "freshness-check only" stay hand-written but get a periodic-review prompt because the source is informal (incident reports, design rationale, narrative-with-tables).

2.1 High-priority generation candidates

  • docs/CONFIG.md — the master Viper-key/env-var/flag/default table.

    • Source: Viper key registrations + cobra flag definitions (PersistentFlags, Flags) + an internal configKeyDefaults map. A small reflection-driven generator over the existing config struct can emit the rows.
    • Size: medium (~150 LOC of generator code; doc is ~1,000 lines but ~half is narrative that should stay hand-written; the table is the regenerable surface).
    • Suggested approach: make the table an inserted block between <!-- BEGIN GENERATED --> / <!-- END GENERATED --> markers (same pattern as cmd/bd/help_all.go from PR #3704). Narrative around the table stays hand-written.
  • docs/SETUP.md — bd setup recipes & flags.

    • Source: the recipe registry in internal/setup/ + cobra flag tree for bd setup.
    • Size: small–medium.
    • Suggested approach: generate the recipe table; keep narrative.
  • docs/ADO_CONFIG.md — every bd ado config option.

    • Source: ADO integration's config struct + flag definitions.
    • Size: small.
    • Suggested approach: generate the options table from the struct field tags.
  • plugins/beads/skills/beads/commands/*.md (29 files) — slash-command specs enumerating flags.

    • Source: cobra command tree (same source PR #3704 used).
    • Size: medium — 29 files, but most are tiny.
    • Suggested approach: generate the flag-enumeration block from cobra; keep the YAML frontmatter and the Examples / Notes sections hand-written. Coordinate with the upstream skill maintainers — these files are part of the published Claude Code skill and a regeneration script must respect their packaging conventions.
  • plugins/beads/skills/beads/resources/CLI_REFERENCE.md — second hand-written CLI reference.

    • Source: identical to PR #3704's source for docs/CLI_REFERENCE.md.
    • Size: small (it's just a second consumer of an existing generator).
    • Suggested approach: reuse the PR #3704 generator and emit a second target. Or replace with a thin pointer to docs/CLI_REFERENCE.md if that file's generated form ships with the skill bundle.
  • docs/JSON_SCHEMA.md — schema version + envelope contract.

    • Source: the BD_JSON_ENVELOPE constants + schema-version literal.
    • Size: small.
    • Suggested approach: generation may be overkill (one number); a freshness-check that runs grep for the schema-version constant against the doc would catch divergence cheaply.
  • docs/RECOVERY.md — error-name anchors tied to exit-code constants.

    • Source: the Exit* constants in internal/errors/ (or wherever ExitRemoteDivergenceRefused lives).
    • Size: small (table only).
    • Suggested approach: generate the "name → exit code" cross-reference table; keep the recovery prose hand-written.
  • docs/design/otel/otel-data-model.md — schema of OTel events.

    • Source: OTel attribute constants in internal/observability/ and span emission sites.
    • Size: medium.
    • Suggested approach: introspect attribute constants & emission sites, generate the schema table.

2.2 Freshness-check only (no clean machine-readable source)

  • docs/ERROR_HANDLING.md — file/line citations into cmd/bd/*.go. Generator would need full pattern-matching of source — not worth it. Keep hand-written; freshness check should warn if any cited filename in a code-block doesn't exist or if the cited line range is now empty.
  • docs/LINTING.md — "22 issues as of Nov 6 2025". Could in principle be regenerated from golangci-lint run output, but the doc's value is the narrative explanation of why each warning is acceptable. Freshness check (rerun lint, compare count) is sufficient.
  • docs/TROUBLESHOOTING.md — debug env vars table. The env-var name list could be generated, but the recommendations beside each are narrative. Freshness-check only.
  • docs/FAQ.md — already drifted on the very first sentence. No machine source. Freshness-check only.
  • website/docs/reference/configuration.md — drifted to wholly wrong file format. Right answer is to delete and replace with a Docusaurus-rendered version of docs/CONFIG.md's generated table, not to maintain a parallel doc.
  • docs/INSTALLING.md / website/docs/getting-started/installation.md — install matrix. Per-platform install commands cannot be sensibly auto-generated, but a freshness check that the install URLs actually 200 (and that documented binary names exist in the latest release) would catch most drift.

2.3 Existing exemplar

  • docs/SECURITY-DEPENDENCY-EXCEPTIONS.md already uses a Last reviewed: 2026-04-28 line at the top. This is the simplest possible freshness-marker pattern and is already in production use in this repo. Adopt the same pattern (front-matter or a top-of-file line) for any (b) doc kept hand-written.

3. Freshness mechanism — comparison and recommendation

Option A — GitHub Actions cron that opens an issue when any (b)-tagged doc has not been touched in N months

  • Requires every (b) doc to carry a marker (frontmatter or HTML comment) so the workflow can find them.
  • Detection signal is "git log mtime older than N months". Easy to implement; standard cron pattern.
  • Pros: zero dependencies on bd; works for non-beads contributors; surfaces in maintainer's normal triage UI.
  • Cons: false positives — a doc can be perfectly current and simply not need editing. Maintainers will start ignoring the auto-issues.
  • Cons: does not catch the actual drift case (doc and code disagree but doc was edited recently for unrelated reasons).
  • Cons: requires CI minutes / GH issue noise.

Option B — bd preflight / bd stale extension that flags hand-written reference docs with a last-reviewed: frontmatter field older than N months

  • Re-uses the Last reviewed: YYYY-MM-DD exemplar already present in docs/SECURITY-DEPENDENCY-EXCEPTIONS.md. Each (b) doc gains a frontmatter last-reviewed field.
  • A bd doctor / bd preflight subcommand walks the marked docs and prints any whose review date is older than N months.
  • Pros: lives where maintainers already look (bd output during release prep); drift signal is explicit (someone has to update the date as part of the review), not implicit (mtime).
  • Pros: integrates with the release-stability-gate doc — could be wired into the gate itself.
  • Pros: portable across forks (no GitHub-specific machinery).
  • Cons: requires Go code in the bd binary; new test surface; adds doc-walking responsibilities that are not core to bd.
  • Cons: opt-in by humans — if nobody touches the date, the marker becomes a lie of omission.

Option C — Manual quarterly review checklist in CONTRIBUTING.md

  • A section in CONTRIBUTING.md listing every (b) doc and asking maintainers to review them once a quarter.
  • Pros: zero infrastructure. Trivial to land.
  • Cons: depends entirely on humans remembering to do the review. This is exactly how the original drift in docs/CLI_REFERENCE.md happened.

Option D — --check doc-validators per-doc, run in CI (the PR #3704 model)

  • For each (b) doc with a clean source, write a generator and a --check mode that fails CI when the doc and the source disagree.
  • Pros: catches drift at PR time, before it ships. No false positives — the signal is "doc and code are objectively out of sync".
  • Pros: scales naturally — each new (b) doc that gets a generator gets a CI gate "for free".
  • Cons: needs a generator per doc. Some (b) docs (FAQ, ERROR_HANDLING citations, INSTALLING URLs) have no clean source.
  • Cons: doesn't help the freshness-check-only docs at all.

Combine D for docs with a clean source and B for the rest.


Recommendation

Adopt Option E (hybrid): Option D where a generator is feasible, Option B for everything else.

Concretely:

  1. For (b) docs in section 2.1 (clean source): add a generator and a --check CI gate, modelled on PR #3704 (scripts/generate-cli-docs.sh, cmd/bd/help_all.go). Drift is caught at PR time, no human intervention required.
  2. For (b) docs in section 2.2 (no clean source): add a last-reviewed: frontmatter field, and either (a) run a bd preflight walker that prints stale entries, or — if the maintainer prefers zero new bd code — (b) use a single GitHub Actions cron that lists files whose last-reviewed: is older than 6 months and posts to a single tracker issue once per quarter (Option A but driven by the explicit field rather than mtime).
  3. Adopt the Last reviewed: line pattern that already exists in docs/SECURITY-DEPENDENCY-EXCEPTIONS.md as the canonical marker. No new format required.

Why: D is the only option proven to actually prevent drift (PR #3704 is the exemplar). It's the right answer wherever it's tractable. B/A-with-explicit-field is a graceful fallback for docs without a clean source — using an explicit last-reviewed date avoids the false-positive problem of mtime-based detection. C alone does not work; that's how we got into this problem.


Phase 2 follow-up scope (not in this PR)

After maintainer reviews this inventory, Phase 2 candidates:

  • File a follow-up bead per (b) doc with a clean source (section 2.1) — one generator + --check per doc.
  • File a follow-up bead for the "freshness-check only" set (section 2.2) — implement either the bd preflight walker or the cron-driven explicit-field workflow.
  • Add <!-- hand-written-status: intentional --> headers (or a frontmatter field) to (a) docs to make the inventory self-describing in the source tree. (Phase 1 only classified them; Phase 2 applies the markers.)
  • Address scope-bleed cases surfaced during this audit (see "Surprises" below).

Surprises uncovered during this audit

  • website/docs/reference/configuration.md is wholly stale — documents TOML config and BEADS_* env vars; the actual implementation is YAML and BD_*. The published documentation site has been wrong about how to configure beads for some time.
  • docs/FAQ.md opens with "git-based issue tracker" — contradicts the Dolt-native architecture used everywhere else.
  • docs/CLI_REFERENCE.md Version: 0.21.0+ header — this is exactly the GH#3683 issue PR #3704 fixes; included here for completeness.
  • docs/DOLT.md and docs/DOLT-BACKEND.md — two Dolt-backend overview docs at different lengths. Possible duplication or scope-bleed.
  • docs/RELEASING.md and root RELEASING.md — same content, different files. Possible duplication.
  • examples/bd-example-extension-go/README.md references docs/EXTENDING.md — that file does not exist in upstream/main. Dead cross-reference.
  • A second hand-written CLI reference lives at plugins/beads/skills/beads/resources/CLI_REFERENCE.md — separate from docs/CLI_REFERENCE.md. PR #3704 only fixes one of them.
  • docs/dev-notes/ contains five resolved/historical audit reports. They're (c) historical, but it's worth deciding whether to archive them or leave them where they are.
  • docs/LINTING.md's "22 issues as of Nov 6 2025" — date-stamped snapshot inside narrative prose; likely already wrong.

Judgment calls flagged for sanity check

  • Versioned docs: treated as "snapshots that should not have a freshness mechanism" — a stale snapshot for v1.0.0 is correct behaviour, not drift. Confirm this matches Docusaurus norm.
  • Plugin command files (plugins/beads/skills/beads/commands/*.md) classified as (b). They're part of a published Claude Code skill bundle; regenerating them upstream may collide with downstream skill packaging. The recommendation is to coordinate with the skill maintainers before adding a generator.
  • docs/EXTENDING.md is missing. Either it should be written (and the example link unbroken) or the example reference should be removed. Out of scope for Phase 1.
  • Boundary between (a) and (b) for docs with mixed content (e.g., docs/LABELS.md, docs/ADVANCED.md, docs/TROUBLESHOOTING.md) — classified as primarily (a) when narrative dominates but flagged as having (b)-style sections. Phase 2 may want to split these or use partial-generation block markers.