* fix(init): wire git origin as Dolt remote
Default bd init now treats a git origin as the Dolt remote, persists sync.remote, and still skips synthesis in --stealth. JSONL auto-export/import paths now warn or skip based on sync.remote so exports do not masquerade as cross-machine sync.
Docs and generated agent/CLI references now state that Dolt is canonical, refs/dolt/data is the sync channel, and .beads/issues.jsonl is export/interchange/backup only.
_codex-gpt-5-xhigh on behalf of maphew_
* test: keep embedded command stderr out of parsed stdout
Embedded command tests parse IDs and JSON from command output. The new auto-export warnings correctly go to stderr, but several tests used CombinedOutput and treated warnings as stdout, which broke CI shards that parse issue IDs or JSON lists. Capture stdout separately on success while preserving combined output for error diagnostics.\n\n_codex-gpt-5-medium on behalf of CI Bot_
---------
Co-authored-by: CI Bot <ci@beads.test>
Remove gastown-specific language. Replace the formula command's Rig/Cook/Run lifecycle wording with existing beads verbs: define formulas, cook them into protos, then pour or wisp them into work. Describe GT_ROOT formulas as a shared workspace root instead of an orchestrator path. Update generated CLI references and add a regression check for the help text.
_codex-gpt-5-medium on behalf of matt wilkie_
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
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 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>
Add support for JetBrains Junie AI agent:
- Create .junie/guidelines.md with workflow instructions
- Create .junie/mcp/mcp.json for MCP server configuration
- Add 'junie' to BuiltinRecipes in recipes.go
- Add runJunieRecipe() handler in setup.go
- Add website documentation
- Add integrations/junie/README.md
Usage: bd setup junie