Complete mybd-pnm docs evidence review.\n\n- Add verified docs disposition inventory and canonical seams.\n- Stage stale duplicate docs under docs/staged-for-removal with a manifest.\n- Refresh generated CLI docs and harden the generator for CRLF/stdin handling.\n\nFollow-up: mybd-xfr for automated docs freshness checks.
The dolt.idle-timeout config key has had no consumer in the tree since
GH#2452 (commit 4df17ca34, in v0.60.0) removed the idle-monitor and
activity-signal daemon infrastructure. There is:
- No SetDefault for it in internal/config/config.go
- No GetString/GetDuration/viper consumer anywhere in cmd/ or internal/
- Only references are docs, the YamlOnlyKeys entry, and a validator case
The validator case (yaml_config.go:521) and YamlOnlyKeys entry served
no purpose since the value was never read. Remove both, plus the
'time' import that becomes unused, and update docs.
Out of scope: docs/DOLT-BACKEND.md:467 has 'idle_timeout: "30s"' under
Dolt server lock-retry settings — that's a different idle_timeout from
the upstream Dolt server config, not the removed beads key. Untouched.
Discovered while reviewing PR #3714 (mybd-b5q).
Amp-Thread-ID: https://ampcode.com/threads/T-019dfe19-17ae-713e-bc3a-d7c9da6a117d
Co-authored-by: Amp <amp@ampcode.com>
Live config has been YAML since v1.0.0 (per mybd-hxq investigation /
PR #3714: `git show v1.0.0:internal/config/config.go` → SetConfigType("yaml")).
The .beads/ tree diagram on line 23 in both the live and v1.0.0
versioned snapshots still showed config.toml. Same wholly-stale pattern
as PR #3714, smaller blast radius.
Other .toml references in website/docs and website/versioned_docs all
refer to .formula.toml (formulas legitimately use TOML) and are correct.
Out of scope (separate issue mybd-ssn): website/static/llms-full.txt
also has stale config.toml references at lines 11074-11075 and 11196.
That file is generated and is being brought under a freshness gate.
Amp-Thread-ID: https://ampcode.com/threads/T-019dfe19-17ae-713e-bc3a-d7c9da6a117d
Co-authored-by: Amp <amp@ampcode.com>
* docs: generate CLI reference from live help
* docs(cli): move bd version stamp from per-command pages to index only
Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on
every per-command CLI reference page (writeSingleCommandDoc) and the
docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now
lives only on the index page emitted by scripts/generate-cli-docs.sh:
- Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md):
labelled "Latest"
- Versioned snapshots (website/versioned_docs/version-X.Y.Z/...):
labelled with the explicit semver tag parsed from the directory name
This eliminates the 100+-file no-signal diff a release version bump
otherwise produces, restoring the "regen as a separate small commit"
workflow PR #3704 enables. After this change a version bump alone
yields zero diff on the dev tree; only the new versioned snapshot
created at release-cut time carries the new tag. No datestamps are
introduced anywhere — scripts/generate-cli-docs.sh --check remains
deterministic across CI runs.
Refs: mybd-afb, PR #3704
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The published reference page documented `.beads/config.toml` and `BEADS_*`
env vars, but the live implementation has used YAML config (`config.yaml`)
and the `BD_*` env prefix for some time — the site has been misleading
newcomers ever since. Rewritten against `internal/config/config.go` and
`internal/config/yaml_config.go` to match live behavior.
Updates both `website/docs/reference/configuration.md` and the
`version-1.0.0` versioned snapshot, since v1.0.0 itself shipped with
the YAML/BD_* implementation (`SetConfigType("yaml")` and
`SetEnvPrefix("BD")` are present in the v1.0.0 source).
Tracks: mybd-hxq
Refs: GH#3683 (newcomer trust-gap pattern), PR #3706
(mybd-p71 doc inventory that surfaced this).
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: fix broken xref to docs/EXTENDING.md in extension example
The extension example README referenced docs/EXTENDING.md in three
places, but that file was deliberately deleted in the SQLite -> Dolt
migration (see CHANGELOG entry "Deleted deprecated docs - removed
EXTENDING.md and MULTI_REPO_HYDRATION.md (SQLite-era, no longer
applicable)"). Anyone following the example hits a broken link.
Removed all three references. The example README is itself the
canonical reference for the extension pattern, so no redirect target
is needed.
Note: other docs in the repo still reference the deleted EXTENDING.md
(docs/ADVANCED.md, docs/CONFIG.md, examples/library-usage/README.md,
website/docs/reference/advanced.md). Those are out of scope for this
fix and should be addressed in follow-up issues.
Tracking bead: mybd-q71
GH: #3683
PR: builds on follow-up audit from PR #3706
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: fix remaining broken xrefs to deleted EXTENDING.md across repo
Round 1 (commit ddeff314c) only fixed the extension example README
because the original prompt scoped that PR narrowly. The bead
(mybd-q71) acceptance is repo-wide ("no broken xrefs anywhere"), so
this follow-up sweeps the rest in the same PR per the project's
"one issue per PR" rule.
Per-file treatment (EXTENDING.md was deleted in commit 508387377
before v1.0.0 was tagged, so even the v1.0.0 versioned snapshot has
been broken since release):
- docs/ADVANCED.md (3 refs):
* Note in Extensible Database section: drop trailing "See
EXTENDING.md for details" — the surrounding sentence about
Dolt-era alternatives stands on its own.
* Bold "See EXTENDING.md for complete documentation" line:
redirect to the canonical working example
(examples/bd-example-extension-go).
* Next Steps bullet: same redirect.
- docs/CONFIG.md (2 refs):
* Namespace doc for compact_*: replace "(see EXTENDING.md)" with
"(used by `bd admin compact`)" — the doc itself describes the
keys, no external reference needed.
* See Also bullet: replace with link to docs/ADVANCED.md
(Extensible Database section).
- examples/library-usage/README.md (1 ref):
* See Also bullet: replace EXTENDING.md link with link to the
sibling bd-example-extension-go example.
- website/docs/reference/advanced.md (1 ref):
* Custom Tables section: replace EXTENDING.md link with link to
the bd-example-extension-go README on GitHub.
- website/versioned_docs/version-1.0.0/reference/advanced.md (1 ref):
* Same fix as the live docs. EXTENDING.md was deleted before
v1.0.0 release (commit 508387377 is an ancestor of tag v1.0.0),
so this versioned snapshot has been broken since cut and a fix
here doesn't violate frozen-in-time correctness — the link was
never valid in the v1.0.0 release.
- website/static/llms-full.txt (1 ref, auto-generated artifact):
* Updated to match the corrected source so the on-disk artifact
isn't broken until next regeneration.
- beads.go and internal/beads/beads.go (package doc comments):
* Replaced "see docs/EXTENDING.md" / "see EXTENDING.md" with a
pointer to examples/bd-example-extension-go. These were real
broken pointers in published Go source comments.
CHANGELOG.md historical entries left untouched (intentional history).
cmd/bd/info.go:747 left untouched (it's a programmatic CHANGELOG
entry rendered by `bd info`, equivalent to a CHANGELOG line).
Verification:
grep -rn 'EXTENDING\.md' --include='*.md' .
returns only CHANGELOG.md hits.
Tracking bead: mybd-q71
GH: #3683
PR: #3713 (round 2)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
website docs, plugin/npm docs, examples, and doctor hints.
- Standardized on:
- CGO_ENABLED=0 go install ... for server-mode only
- CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
capable
- Added scripts/check-go-install-guidance.sh and wired it into CI.
- Updated default.nix to use gms_pure_go instead of ICU flags.
Validation passed locally:
- make test
- golangci-lint run --build-tags=gms_pure_go ./...
- ./scripts/check-go-install-guidance.sh
- ./scripts/check-build-tags.sh
- go test -tags gms_pure_go ./cmd/bd/doctor
- doc flag check
Add documentation for features implemented in Go source but missing
from the website docs:
formulas.md:
- Convoy formula type (multi-agent coordination)
- Formula inheritance (extends field)
- Conditional steps (condition field with truthy/negated/equality)
- Loop/iteration (count, range, until with max)
- Runtime expansion (on_complete with for_each)
- bd cook command (compile-time vs runtime modes)
- Expanded gate types and aspect composition
wisps.md:
- Squash lifecycle (bd mol squash - promote to persistent)
- Burn lifecycle (bd mol burn - delete without trace)
- Garbage collection (bd mol wisp gc)
- Corrected storage model (Ephemeral=true in main DB)
- Updated commands to match actual CLI surface
index.md:
- Added swarm commands (validate, create, status, list)
- Added cook command
- Added wisp lifecycle commands (squash, burn, gc)
- Added bond and formula list commands
Regenerated website/static/llms-full.txt via scripts/generate-llms-full.sh.
Before: 0 hits for swarm, convoy, cook, extends, condition, loop,
squash, burn, promote, for_each in llms-full.txt.
After: all terms present with substantive documentation.
Closes#3244
* feat(docs): version Docusaurus site and align llms-full with snapshots
Add docs version 1.0.0, version dropdown, lastVersion defaulting to stable,
merged markdown config, and RELEASING steps for future doc snapshots.
generate-llms-full.sh reads the latest entry in versions.json.
README links the published documentation site.
Closes#2644
Made-with: Cursor
* fix(docs): update org URLs to gastownhall and refresh 1.0.0 snapshot
- Update default orgName in docusaurus.config.ts from steveyegge to
gastownhall to match the repo's new home
- Update hardcoded steveyegge URLs in generate-llms-full.sh
- Refresh versioned_docs 1.0.0 snapshot to include quickstart changes
from #3032 which merged after the original snapshot was taken
- Regenerate llms-full.txt with corrected URLs and updated content
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Single full tutorial on website/docs/getting-started/quickstart.md; docs/QUICKSTART.md
is a short pointer with stable anchors. Update npm and Claude plugin links.
Closes#3014
Made-with: Cursor
Beads' storage backend is Dolt, not git. Git integration (hooks, repo
discovery, identity) is optional — `BEADS_DIR` + `--stealth` provides
fully functional git-free operation with zero git calls.
Changes across 15 files:
- Replace all "git-backed" references with "Dolt-powered" or "Dolt-backed"
- Add "Git-Free Usage" section to README.md documenting BEADS_DIR + --stealth
- Fix stale "JSONL" storage reference in llms-full.txt
- Update SKILL.md to mark git as optional prerequisite
Complements GH#2522 (stale command cleanup) — that PR fixed removed
commands, this one fixes misleading storage backend framing.
Fix#2084: Architecture page said 'Never Use bd doctor --fix' while
recovery pages recommended it as a standard step. Reconciled by:
- Architecture: Downgrade from 'danger/never' to 'warning/use with care',
add backup + dry-run precautions, explain the actual risk (circular dep
false positives)
- Recovery pages: Add backup and --dry-run steps before --fix, creating a
consistent decision tree across all docs
- Also fix stale references in recovery pages: SQLite → Dolt terminology,
bd sync → bd dolt push/pull, bd dolt start → dolt sql-server
Amp-Thread-ID: https://ampcode.com/threads/T-019ca749-d4f2-7289-b085-52e17436e950
Co-authored-by: Amp <amp@ampcode.com>
Standardize start-work semantics to `bd update <id> --claim` across docs,
examples, templates, and website static LLM artifacts. Replaces
`--status in_progress` with `--claim` where the meaning is start-work.
Also fixes stale comment in llms.txt ("Update status" → "Start work").
Co-Authored-By: Valeriy Pavlovich <iqdoctor@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: support issue_id_mode=counter for sequential IDs (GH#2002)
When `issue_id_mode=counter` is set via `bd config set issue_id_mode counter`,
`bd create` now assigns monotonically increasing integer IDs instead of
hash-based IDs. The counter is stored in a new `issue_counter` table (one row
per prefix) and incremented atomically within the same transaction as the issue
insert.
- Add `issue_counter` table to schema (version bumped to 5)
- Add migration 006 to create `issue_counter` table on existing databases
- Add `GetNextIssueCounter()` to queries.go (standalone transaction, for
callers outside CreateIssue)
- Modify `generateIssueID()` to check `issue_id_mode` config and use counter
path when set to "counter"; hash mode remains the default when unset
- Explicit `--id` flag continues to take precedence over counter mode
- Tests: TestGetNextIssueCounter_Sequential, TestGetNextIssueCounter_MultiplePrefixes,
TestCreateIssue_CounterMode, TestCreateIssue_ExplicitIDOverridesCounter,
TestCreateIssue_HashModeDefault, TestMigrateIssueCounterTable
* docs: document issue_id_mode=counter feature (GH#2002)
Add documentation for the sequential counter ID mode across all relevant docs:
- docs/CONFIG.md: new issue_id_mode namespace entry and full example section
with tradeoff table, migration guidance, and per-prefix counter isolation
- .beads/BD_GUIDE.md: counter mode section with when-to-use, migration
considerations, and explicit --id override behavior
- docs/ADAPTIVE_IDS.md: alternative counter mode section with cross-reference
to CONFIG.md
- website/docs/reference/configuration.md: issue_id_mode under ID Generation
with comparison table
* fix: seed counter from existing issues when enabling counter mode (GH#2002)
When issue_id_mode=counter is enabled on a repo that already has manually-created
sequential IDs (e.g., plug-1 through plug-50), the counter used to start at 1,
causing immediate collisions.
Add seedCounterFromExistingIssuesTx() which scans existing issue IDs, finds the
highest numeric suffix for the given prefix, and seeds the issue_counter table
from there. The function is idempotent (skips if a counter row already exists)
and only counts purely-numeric suffixes (ignoring hash-based IDs like test-a3f2).
The seeding is called at first counter use: in generateIssueID() (issues.go) and
GetNextIssueCounter() (queries.go) when sql.ErrNoRows is returned for the prefix.
Add four tests covering: seeding from existing numeric IDs, mixed hash+numeric
IDs, fresh repos (counter starts at 1), and already-seeded counters (no regress).
* feat: add bd config schema and describe commands for agent discoverability (GH#2002)
Adds machine-readable config schema so agents can programmatically discover
all available configuration keys without reading source code.
- internal/config/schema.go: new ConfigKeyDef struct and Schema slice with
43 entries covering core, sync, routing, jira, linear, gitlab, team, mail,
and YAML-only keys; includes type, default, valid values, description, and
storage location per key
- cmd/bd/config.go: adds 'bd config schema' (table + --json) and
'bd config describe <key>' (single-key detail + --json) subcommands
Usage:
bd config schema
bd config schema --json | jq '.[] | select(.key == "issue_id_mode")'
bd config describe issue_id_mode
bd config describe jira.url --json
* refactor: remove overengineered config schema (keep docs only)
Remove the configSchemaCmd and configDescribeCmd subcommands added in
the previous commit, along with internal/config/schema.go (390 lines of
config key definitions). These are out of scope for GH#2002.
The daemon was removed in v0.50. Remove remaining references from
NEWSLETTER.md, docs/LINTING.md, website sidebar, and llms.txt files.
Regenerated llms-full.txt from clean source docs. CHANGELOG.md
historical entries preserved.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The comparison table listed `brew upgrade bd` but the correct formula
name is `beads`. The standalone Homebrew section below already had the
correct command.
Fixes#1561
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The Homebrew formula is named "beads" (not "bd"), so all brew commands
must use `brew install beads` / `brew upgrade beads`. Also removes the
dead update-homebrew job from release.yml — homebrew-core handles
formula updates automatically.
Follows up on #1557 which fixed the Go code in bd doctor.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(export): populate export_hashes after successful export (GH#1278)
Child issues created with --parent were missing from export_hashes table,
which affects integrity tracking and future incremental export features.
This fix ensures SetExportHash() is called for all exported issues:
- Updated ExportResult to include IssueContentHashes map
- Updated finalizeExport() to call SetExportHash() for each exported issue
- Updated exportToJSONLDeferred() to collect content hashes during export
- Updated performIncrementalExport() to collect content hashes for dirty issues
- Updated exportToJSONLWithStore() to call SetExportHash() after export
- Updated daemon's handleExport() to call SetExportHash() after export
Added test TestExportPopulatesExportHashes to verify the fix works for
both regular and hierarchical (child) issue IDs.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: add GitHub Copilot integration guide
Add comprehensive documentation for using beads with GitHub Copilot in VS Code via the MCP server.
New files:
- docs/COPILOT_INTEGRATION.md - Complete setup guide with prerequisites, MCP tools reference, example workflows, troubleshooting, and FAQ
- website/docs/integrations/github-copilot.md - Shorter website version
Updated files:
- docs/INSTALLING.md - Added GitHub Copilot row to setup matrix and new "GitHub Copilot (VS Code)" section with quick setup steps
- website/docs/getting-started/ide-setup.md - Added GitHub Copilot section
- website/docs/integrations/mcp-server.md - Added VS Code / GitHub Copilot configuration examples for both .vscode/mcp.json and settings.json
Key clarifications:
- Beads is a system-wide CLI tool installed once, not cloned into projects
- The .beads/ directory only contains the issue database
- Added FAQ addressing "Do I need to clone beads?" explicitly
Fixes#148
* docs: add cross-platform paths for user-level VS Code MCP config
Add Linux and Windows paths alongside macOS for the VS Code
user-level MCP configuration. Users can now find the correct
path for their platform in a simple table format.
Paths by platform:
- macOS: ~/Library/Application Support/Code/User/mcp.json
- Linux: ~/.config/Code/User/mcp.json
- Windows: %APPDATA%\Code\User\mcp.json
Fixes#148
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* feat: update to use core tap for beads installation
Signed-off-by: Rui Chen <rui@chenrui.dev>
* remove custom tap related code and refs
Signed-off-by: Rui Chen <rui@chenrui.dev>
---------
Signed-off-by: Rui Chen <rui@chenrui.dev>