Commit graph

34 commits

Author SHA1 Message Date
Ben Madore
3b39ce577a
docs: update user-facing URLs from steveyegge/beads to gastownhall/beads
Co-authored-by: Ben Madore <823868+madorb@users.noreply.github.com>
2026-04-24 08:17:42 -07:00
Isaac Karrer
104932d7f0
docs: unify quick start (site + stub) (#3032)
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
2026-04-05 22:16:00 -07:00
matt wilkie
4fe05a3bec
Use getting started docs as bugs to fix (#3034)
* 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>
2026-04-05 16:09:58 -07:00
Harry
917c5f6f40 Improve quickstart docs with Why Beads section and --explain examples
- Add 'Why Beads?' section contrasting flat trackers vs dependency-aware ready queue
- Add bd ready --explain example showing full graph reasoning output
- Document bd ready vs bd list --status open distinction
- Add graph check and explain commands to Next Steps section

Fixes: bd-47m

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-03-30 09:13:16 -07:00
coffeegoddd☕️✨
33eed5d14f /{docs,website}: wip, updating docs 2026-03-28 13:47:20 -07:00
emma
083181e1ea feat: reimplement Notion sync on REST data sources (fix-merge PR #2759)
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>
2026-03-27 19:20:40 -07:00
Matt Wilkie
b61fe903b1 docs: add sync setup guide for new computers (GH#2707)
Amp-Thread-ID: https://ampcode.com/threads/T-019d1b5c-9a3b-763f-9ad3-6e9fd53a47ae
Co-authored-by: Amp <amp@ampcode.com>
2026-03-23 08:50:19 -07:00
cwalv
4d14fb8ce1 feat: auto-detect beads database on git origin during bootstrap
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
2026-03-14 00:18:13 -07:00
matt wilkie
f7061f9782
fix(docs): remove stale --branch flag and SQLite refs from QUICKSTART (GH#2522) (#2525)
- Remove bd init --branch beads-sync (flag no longer exists)
- Replace stale ~/.beads/default.db with correct .beads/dolt/ location
- Add outdated-content disclaimer to Community Articles in ARTICLES.md


Amp-Thread-ID: https://ampcode.com/threads/T-019cde55-544a-701a-a0e2-c06dee329d6a

Co-authored-by: Amp <amp@example.com>
Co-authored-by: Amp <amp@ampcode.com>
2026-03-11 12:54:30 -07:00
matt wilkie
cd2f5003f7 fix: replace stale bd migrate --to-dolt with bd init --from-jsonl (GH#2333)
Amp-Thread-ID: https://ampcode.com/threads/T-019cce5b-39df-740f-a8e1-5c6b3e389519
Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-019cce5b-39df-740f-a8e1-5c6b3e389519
Co-authored-by: Amp <amp@ampcode.com>
2026-03-08 10:01:32 -07:00
Ohad Basan
2d9ad516ef fix(docs): correct misleading examples in QUICKSTART.md
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>
2026-03-04 00:24:31 +02:00
obsidian
89569b914e feat: add --backend flag to bd init with SQLite deprecation notice (bd-7xj5)
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>
2026-03-02 18:33:12 -08:00
Peter Chanthamynavong
b59486cc59
docs(deps): add DEPENDENCIES.md covering dependency system and gates
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
2026-02-27 10:09:05 -08:00
darcy
f9b306f152 docs(claim): standardize start-work semantics to --claim (#2070)
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>
2026-02-24 22:11:39 -08:00
topaz
062aedbed7 docs: remove stale daemon references from all documentation (GH#1982)
Sweep 65 markdown files across docs/, website/, claude-plugin/, examples/,
integrations/, and root to replace removed `bd daemon` references with
current Dolt server mode equivalents. CHANGELOG.md preserved per policy.

Key replacements:
- `bd daemon start/stop/status` → `bd dolt start/stop` / `bd doctor`
- `bd daemons killall/health/logs` → `bd dolt stop` / `bd doctor`
- `--no-daemon` flag → removed (embedded mode is default)
- `BEADS_NO_DAEMON` / `BEADS_DAEMON_MODE` env vars → removed
- `.beads/bd.sock` → removed
- "daemon mode" / "direct mode" → "server mode" / "embedded mode"
- daemon.pid/daemon.log → .beads/dolt/sql-server.pid/.log

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Executed-By: beads/polecats/topaz
Rig: beads
Role: polecats
2026-02-22 17:57:53 -08:00
beads/crew/emma
bd68c87b00 fix: remove stale embedded Dolt references after server-only migration
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
2026-02-21 16:59:44 -08:00
beads/crew/emma
5fb306db7b docs: Remove stale daemon/SQLite/JSONL/tombstone documentation for Dolt-native
Phase 9 of dolt-1s40 epic. Remove documentation for features that were
removed in the Dolt-Native Beads v2 migration (Phases 1-8).

Removed files:
- docs/DAEMON.md, docs/daemon-summary.md - daemon architecture docs
- docs/DELETIONS.md - tombstone deletion tracking docs
- docs/SYNC.md - JSONL 3-way merge sync docs
- cmd/bd/doctor/fix/docs.md - tombstone/SQLite doctor docs
- claude-plugin/commands/daemon.md, daemons.md - daemon command refs
- integrations/beads-mcp/SETUP_DAEMON.md - daemon MCP setup
- website/docs/core-concepts/daemon.md - website daemon docs
- website/docs/core-concepts/jsonl-sync.md - website JSONL sync docs
- examples/git-hooks/ - JSONL sync git hooks

Updated files:
- docs/DOLT.md - rewritten for Dolt-only world
- docs/GIT_INTEGRATION.md - rewritten, removed daemon/JSONL/merge driver
- docs/CLI_REFERENCE.md - removed daemon management section
- Fixed broken cross-references to deleted files across 7 docs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Executed-By: beads/crew/emma
Rig: beads
Role: crew
2026-02-16 19:19:00 -08:00
obsidian
28d6486193 fix(dolt): default auto-commit to OFF in server mode, ON in embedded mode (dolt-test-aso8k)
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
2026-02-08 17:42:33 -08:00
beads/crew/emma
761d2e7637 Merge pull request #1186 from peterkc/feature/contributor-prompt-recovery
feat(init): add contributor prompt and push-fail recovery

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Executed-By: beads/crew/emma
Rig: beads
Role: crew
2026-01-29 20:05:53 -08:00
Joe Delfino
c6bb265460 Show blocking dependencies inline in bd list output
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>
2026-01-26 19:11:51 +00:00
Steve Yegge
ab61b0956b
feat(dolt): auto-commit write commands and set explicit commit authors (#1270)
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>
2026-01-22 20:52:20 -08:00
Peter Chanthamynavong
9e16f34733
feat(role): implement explicit role configuration via git
- 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.
2026-01-20 20:53:01 -08:00
beads/crew/jane
1676f0de45 Merge origin/main into db/fix-2 (resolve conflicts) 2026-01-20 19:49:12 -08:00
Dustin Brown
d3ccd5cfba
Fix Dolt backend init/daemon/doctor; prevent accidental SQLite artifacts; add integration tests; clean up lint (#1218)
* /{cmd,internal}: get dolt backend init working and allow issue creation

* /{website,internal,docs,cmd}: integration tests and more split backend fixes

* /{cmd,internal}: fix lint issues

* /cmd/bd/doctor/integrity.go: fix unable to query issues bug with dolt backend

* /cmd/bd/daemon.go: remove debug logging
2026-01-20 17:34:00 -08:00
Test
7ed6849d19 /{cmd,docs,internal,website}: make dolt backend explicitly single process 2026-01-20 16:51:14 -08:00
coffeegoddd☕️✨
422bc838ed /{website,internal,docs,cmd}: integration tests and more split backend fixes 2026-01-20 13:39:04 -08:00
Steve Yegge
d77a697cee feat: add bd admin parent command for cleanup/compact/reset (bd-3u8m)
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>
2025-12-27 16:21:08 -08:00
Steve Yegge
47cc84de3a fix(docs): standardize sync branch name and daemon syntax (GH#376)
- 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>
2025-12-25 16:22:09 -08:00
Steve Yegge
83ae110508 refactor: Remove legacy MCP Agent Mail integration (bd-6gd)
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>
2025-12-17 23:14:23 -08:00
Steve Yegge
25ea1e7de3 docs: fix broken relative links across documentation
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>
2025-12-16 00:46:08 -08:00
Steve Yegge
9abe99e05a docs(UX): improve daemon and merge documentation (bd-bt6y)
- 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>
2025-11-28 23:11:24 -08:00
Steve Yegge
27c0c331ac Fix #349: Improve compact error messages, remove bogus merge suggestion, add daemon/maintenance docs
- 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>
2025-11-20 20:58:57 -05:00
Steve Yegge
c3856bb140 Add Agent Mail documentation and bash-agent integration
- Added Agent Mail section to QUICKSTART.md with benefits and setup
- Integrated Agent Mail into bash-agent example with reservation/notification
- Added multi-agent usage instructions to bash-agent README
- Closed bd-eimz (QUICKSTART), bd-fkdw (bash-agent), bd-sc57 (production)
- Completed bd-nl8z documentation epic

Amp-Thread-ID: https://ampcode.com/threads/T-5b0d67ff-5eb2-41b3-bc9b-7f33719e0c85
Co-authored-by: Amp <amp@ampcode.com>
2025-11-08 01:10:20 -08:00
Steve Yegge
584c266684 Reorganize project structure: move Go files to internal/beads, docs to docs/
Amp-Thread-ID: https://ampcode.com/threads/T-7a71671d-dd5c-4c7c-b557-fa427fceb04f
Co-authored-by: Amp <amp@ampcode.com>
2025-11-05 21:04:00 -08:00
Renamed from QUICKSTART.md (Browse further)