docs/DOC_INVENTORY.md
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.mdandwebsite/docs/cli-reference/generated from live--helpoutput, with a--checkfreshness 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.mdfile in the repo and classifies it so we can decide which ones need the same treatment.
docs/CLI_REFERENCE.md. Candidate for full or partial generation, OR a freshness-check prompt if no machine-readable data source exists.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).
.md files inventoried: 246 (out of 258 in the repo; 12 already covered by PR #3704 are excluded — see below).website/docs/cli-reference/*.md (6 files) and website/versioned_docs/version-1.0.0/cli-reference/*.md (6 files).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.llms.txt, llms-full.txt (generated), .git/, .beads/, vendor/, node_modules/, website/build/, .docusaurus/.| 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. |
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) |
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. |
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. |
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/underdocs/archive/or pruning resolved entries — they've already drifted past relevance.
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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.
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).
docs/CONFIG.md — the master Viper-key/env-var/flag/default table.
PersistentFlags, Flags) + an internal configKeyDefaults map. A small reflection-driven generator over the existing config struct can emit the rows.<!-- 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.
internal/setup/ + cobra flag tree for bd setup.docs/ADO_CONFIG.md — every bd ado config option.
plugins/beads/skills/beads/commands/*.md (29 files) — slash-command specs enumerating flags.
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.
docs/CLI_REFERENCE.md.docs/CLI_REFERENCE.md if that file's generated form ships with the skill bundle.docs/JSON_SCHEMA.md — schema version + envelope contract.
BD_JSON_ENVELOPE constants + schema-version literal.grep for the schema-version constant against the doc would catch divergence cheaply.docs/RECOVERY.md — error-name anchors tied to exit-code constants.
Exit* constants in internal/errors/ (or wherever ExitRemoteDivergenceRefused lives).docs/design/otel/otel-data-model.md — schema of OTel events.
internal/observability/ and span emission sites.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.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.bd preflight / bd stale extension that flags hand-written reference docs with a last-reviewed: frontmatter field older than N monthsLast reviewed: YYYY-MM-DD exemplar already present in docs/SECURITY-DEPENDENCY-EXCEPTIONS.md. Each (b) doc gains a frontmatter last-reviewed field.bd doctor / bd preflight subcommand walks the marked docs and prints any whose review date is older than N months.CONTRIBUTING.mdCONTRIBUTING.md listing every (b) doc and asking maintainers to review them once a quarter.docs/CLI_REFERENCE.md happened.--check doc-validators per-doc, run in CI (the PR #3704 model)--check mode that fails CI when the doc and the source disagree.Combine D for docs with a clean source and B for the rest.
Adopt Option E (hybrid): Option D where a generator is feasible, Option B for everything else.
Concretely:
--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.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).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.
After maintainer reviews this inventory, Phase 2 candidates:
--check per doc.bd preflight walker or the cron-driven explicit-field workflow.<!-- 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.)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.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.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.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.