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
* fix: narrow cross-version smoke CI triggers and warn on high skip rate
Remove push-to-main and PR triggers from cross-version smoke test
workflow — 30-45 min runtime is too costly for every push. Keep tag
pushes (releases/RCs) and manual dispatch.
Add a visible warning when >80% of tested versions are skipped, printed
to stderr and GitHub step summary. Prevents silent "all passed" when
nearly nothing actually ran.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: add .buildflags for consistent ICU build configuration
Amp-Thread-ID: https://ampcode.com/threads/T-019d5c3f-42eb-7794-8d59-524bbf77bdf8
Co-authored-by: Amp <amp@ampcode.com>
* Add analysis of getting-started docs: necessity vs. fixable errors
Analyzes ~3,200 lines of getting-started documentation across 9 files.
Finds ~50% of the content compensates for tool-level UX gaps that should
be fixed rather than documented. Categorizes every section as genuinely
necessary, useful reference, workaround for fixable issue, or redundant.
Includes specific recommendations for both tool fixes and doc consolidation.
Requested by @csells.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* Streamline getting-started docs: reduce noise, fix user-facing paths
QUICKSTART.md:
- Change all ./bd to bd (reflects installed binary, not local build)
- Replace go-build install section with brew/npm + link to INSTALLING.md
- Remove Notion sync, database maintenance, and migration sections
(these are advanced topics, not quickstart material)
- Add "Database maintenance" link to Next Steps
README.md:
- Consolidate installation from ~30 lines to ~8 lines
- Remove CGO/build-from-source details (belong in INSTALLING.md)
- Add links to INSTALLING.md sections for all install methods
INSTALLING.md:
- Demote go install/source to "Contributors / Go developers" in matrix
- Move Build Dependencies section after platform installs, retitle to
"Build Dependencies (Contributors Only)" with skip-if-prebuilt note
- Add cross-reference to TROUBLESHOOTING.md in troubleshooting section
Net effect: -91 lines, clearer separation between user and contributor
paths, less noise in the first-time experience.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* fix: detect permission errors in bd init with platform-specific guidance
On Windows, Controlled Folder Access can block bd init from creating
.beads/ with no useful error. Now detects os.IsPermission and prints
specific guidance for Windows (CFA whitelist instructions) and Unix
(ls -la / chmod suggestions) instead of a generic failure message.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* fix: add circuit breaker cleanup to bd doctor --fix
Stale circuit breaker files in /tmp/beads-circuit/ can block all bd
operations. Previously users had to manually rm these files. Now
bd doctor detects stale breaker files as a fixable check, and
bd doctor --fix clears them automatically via CleanStaleCircuitBreakerFiles.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* feat: warn about multiple bd binaries in PATH
bd version now scans PATH for duplicate bd executables and warns when
more than one is found. This catches the common case where go install
and Homebrew binaries coexist, causing version confusion. Symlinks
are resolved to avoid false positives.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* fix: show holding process PID in database lock errors
When the Dolt database is locked, the error message now tries to
identify the holding process by scanning /proc for bd/dolt processes.
On Linux, users see e.g. "Process 12345 (bd/dolt) may be holding
the lock." Gracefully degrades to the previous message on platforms
without /proc (macOS, Windows, FreeBSD).
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* fix: only flag circuit breaker files as stale after TTL expires
CheckCircuitBreaker() was counting any open/half-open breaker as stale
regardless of age. This could reset a legitimately active breaker
during a real outage. Now uses the same 5-minute staleness threshold
as CleanStaleCircuitBreakerFiles() — only breakers older than 5 minutes
(from TrippedAt or LastFailure) are flagged for cleanup.
https://claude.ai/code/session_01Fak22deVmDX3KRBKVptJBL
* fix: correct broken doc anchors in README installation links
The "go install" and "from source" links pointed to nonexistent anchors
in INSTALLING.md. Found during review checklist testing.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: suppress gosec G304 false positive in circuit breaker check
Path comes from filepath.Glob with a controlled pattern, matching
the same nolint pattern used in internal/storage/dolt/circuit.go.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Amp <amp@ampcode.com>
Adds internal/notion/ package with direct REST API client, field mapping,
and tracker adapter. Adds bd notion init/connect/status/sync commands.
Enhances tracker engine: conflict detection before pull, label sync,
no-op skip, batch push interface, RFC3339Nano timestamps. Removed dead
matchesFetchOptions function, added gosec nolint for Notion API client.
Co-Authored-By: Osamu Okano <okano.osamu@gmail.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When running `bd bootstrap` in a fresh clone, probe origin for
refs/dolt/data and automatically clone the existing beads database
instead of creating unrelated state. `bd init` warns if the ref
exists and suggests using `bd bootstrap` instead.
Fixes#2580
Two issues:
1. Epic child creation commands were missing the --parent flag,
making it appear that child tasks are automatically associated
with the most recently created epic. The --parent flag is required.
2. The dependency visibility example (bd list showing "blocked by"
annotations) was placed immediately after issue creation, before
any dependencies were added. Moved it after the "Add Dependencies"
section where it makes sense.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Dolt is now the default (and only) storage backend for bd init. Add a
--backend flag that accepts "dolt" (default) or "sqlite" (prints a
deprecation notice with migration instructions and exits). Unknown
backends produce a clear error.
Update QUICKSTART.md and DOLT-BACKEND.md to reflect that SQLite is no
longer supported and Dolt is the sole backend.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Document the full dependency and gate systems which had no dedicated
guide. Prompted by community discussion #2164 asking how to keep
dependent work in sync when beads updates aren't tied to code merges.
- New docs/DEPENDENCIES.md: dependency types, ready work, visualization,
cross-repo deps, gate types (gh:pr, gh:run, timer, bead, human),
gate automation, and workflow recipes
- Add Gates section to CLI_REFERENCE.md (bd gate commands were missing)
- Cross-reference from QUICKSTART.md and DOLT.md
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>
Delete broken store_nocgo_test.go (references undefined errNoCGO),
remove dead bootstrapEmbeddedDolt/hasDoltSubdir functions, and clean up
stale comments and docs that still referenced embedded mode, CGO
requirements, or in-process Dolt across 20 files.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/crew/emma
Rig: beads
Role: crew
When dolt-auto-commit is unset (no flag, no config), the default now depends on
the connection mode: embedded defaults to ON (each write durably committed),
server defaults to OFF (server manages its own transaction lifecycle). This
prevents 'database is read only' errors under concurrent polecat load while
preserving the auto-commit convenience for single-process embedded usage.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Executed-By: beads/polecats/obsidian
Rig: beads
Role: polecats
When issues have blocking dependencies, bd list now shows them inline:
- "(blocked by: X, Y)" when the issue depends on other issues
- "(blocks: A, B)" when other issues depend on this issue
This makes dependencies unmissable when reviewing epic subtasks, addressing
a recurring agent problem where reviewers miss dependencies because they
don't run bd show on each issue.
Example output:
○ bd-123 [P1] [task] - Design API (blocks: bd-124, bd-125)
○ bd-124 [P1] [task] - Implement (blocked by: bd-123, blocks: bd-125)
○ bd-125 [P1] [task] - Test (blocked by: bd-123, bd-124)
Only blocking dependencies (blocks, parent-child, conditional-blocks,
waits-for) are shown, not soft relationships like related or discovered-from.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds Dolt auto-commit functionality for write commands and sets explicit commit authors.
Includes fix for race condition in commandDidWrite (converted to atomic.Bool).
Original PR: #1267 by @coffeegoddd
Co-authored-by: Dustin Brown <dustin@dolthub.com>
- Prioritize beads.role git configuration in detection logic
- Add validation checks to bd doctor for role setup
- Update documentation with migration guides and setup steps
- Include unit tests for role validation logic
Allows users to explicitly define their development role for more predictable routing and diagnostics.
Move cleanup, compact, and reset commands under `bd admin` namespace.
Creates hidden aliases for backwards compatibility that show deprecation
notice when used.
- Create cmd/bd/admin.go with parent command
- Create cmd/bd/admin_aliases.go for hidden backwards-compat aliases
- Update cleanup.go, compact.go, reset.go to remove rootCmd.AddCommand
- Update all documentation to use `bd admin <cmd>` syntax
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replace beads-metadata with beads-sync throughout docs
(matches code default and internal examples)
- Fix bd daemon start → bd daemon --start (correct flag syntax)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove the external MCP Agent Mail server integration that required
running a separate HTTP server and configuring environment variables.
The native `bd mail` system (stored as git-synced issues) remains
unchanged and is the recommended approach for inter-agent messaging.
Files removed:
- cmd/bd/message.go - Legacy `bd message` command
- integrations/beads-mcp/src/beads_mcp/mail.py, mail_tools.py
- lib/beads_mail_adapter.py - Python adapter library
- examples/go-agent/ - Agent Mail-focused example
- examples/python-agent/agent_with_mail.py, AGENT_MAIL_EXAMPLE.md
- docs/AGENT_MAIL*.md, docs/adr/002-agent-mail-integration.md
- tests/integration/test_agent_race.py, test_mail_failures.py, etc.
- tests/benchmarks/ - Agent Mail benchmarks
Updated documentation to remove Agent Mail references while keeping
native `bd mail` documentation intact.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes 46 broken relative links across 20 documentation files in docs/.
Changes:
- Added ../ prefix for root files (README.md, AGENTS.md)
- Removed ../ prefix for sibling docs files
- Removed dead links to non-existent files
- Fixed subdirectory paths
Based on PR #574 by chrisvaillancourt.
Co-Authored-By: Chris Vaillancourt <chrisvaillancourt@users.noreply.github.com>
- Clarify bd merge help text: git merge driver, not for duplicate issues
- Add Do I Need the Daemon section to DAEMON.md
- Add daemon overview section to QUICKSTART.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- bd-1h8: Add --no-daemon hint to compact error messages
- bd-8ql: Replace non-existent merge command with actionable guidance
- bd-ayw: Add 'When to use daemon mode' decision tree to daemon.md
- bd-keb: Add database maintenance section to QUICKSTART.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>