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>
36 KiB
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.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.
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
.mdfiles 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) andwebsite/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 ofwebsite/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/underdocs/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 internalconfigKeyDefaultsmap. 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 ascmd/bd/help_all.gofrom PR #3704). Narrative around the table stays hand-written.
- Source: Viper key registrations + cobra flag definitions (
-
docs/SETUP.md—bd setuprecipes & flags.- Source: the recipe registry in
internal/setup/+ cobra flag tree forbd setup. - Size: small–medium.
- Suggested approach: generate the recipe table; keep narrative.
- Source: the recipe registry in
-
docs/ADO_CONFIG.md— everybd adoconfig 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/Notessections 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.mdif that file's generated form ships with the skill bundle.
- Source: identical to PR #3704's source for
-
docs/JSON_SCHEMA.md— schema version + envelope contract.- Source: the
BD_JSON_ENVELOPEconstants + schema-version literal. - Size: small.
- Suggested approach: generation may be overkill (one number); a freshness-check that runs
grepfor the schema-version constant against the doc would catch divergence cheaply.
- Source: the
-
docs/RECOVERY.md— error-name anchors tied to exit-code constants.- Source: the
Exit*constants ininternal/errors/(or whereverExitRemoteDivergenceRefusedlives). - Size: small (table only).
- Suggested approach: generate the "name → exit code" cross-reference table; keep the recovery prose hand-written.
- Source: the
-
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.
- Source: OTel attribute constants in
2.2 Freshness-check only (no clean machine-readable source)
docs/ERROR_HANDLING.md— file/line citations intocmd/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 fromgolangci-lint runoutput, 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 ofdocs/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.mdalready uses aLast reviewed: 2026-04-28line 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-DDexemplar already present indocs/SECURITY-DEPENDENCY-EXCEPTIONS.md. Each (b) doc gains a frontmatterlast-reviewedfield. - A
bd doctor/bd preflightsubcommand 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.mdlisting 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.mdhappened.
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
--checkmode 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.
Option E — Hybrid (recommended)
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:
- For (b) docs in section 2.1 (clean source): add a generator and a
--checkCI 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. - For (b) docs in section 2.2 (no clean source): add a
last-reviewed:frontmatter field, and either (a) run abd preflightwalker that prints stale entries, or — if the maintainer prefers zero new bd code — (b) use a single GitHub Actions cron that lists files whoselast-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). - Adopt the
Last reviewed:line pattern that already exists indocs/SECURITY-DEPENDENCY-EXCEPTIONS.mdas 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 +
--checkper doc. - File a follow-up bead for the "freshness-check only" set (section 2.2) — implement either the
bd preflightwalker 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.mdis wholly stale — documents TOML config andBEADS_*env vars; the actual implementation is YAML andBD_*. The published documentation site has been wrong about how to configure beads for some time.docs/FAQ.mdopens with "git-based issue tracker" — contradicts the Dolt-native architecture used everywhere else.docs/CLI_REFERENCE.mdVersion: 0.21.0+header — this is exactly the GH#3683 issue PR #3704 fixes; included here for completeness.docs/DOLT.mdanddocs/DOLT-BACKEND.md— two Dolt-backend overview docs at different lengths. Possible duplication or scope-bleed.docs/RELEASING.mdand rootRELEASING.md— same content, different files. Possible duplication.examples/bd-example-extension-go/README.mdreferencesdocs/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 fromdocs/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.mdis 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.