From d2f87d50dee1024485cec02538c76ec38de4fbf4 Mon Sep 17 00:00:00 2001 From: Chris Sells Date: Fri, 17 Jul 2026 18:03:28 -0700 Subject: [PATCH] docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a regeneration from main's source onto the PR branch, so the squash landed a contradictory mix — the release-aligned hand-written docs plus a CLI reference re-documenting unreleased commands and flags, with docs.json referencing four pages (heartbeat, migrate-personal, reclaim, unclaim) whose files do not exist. That broken nav fails the docsync guard on main and on every branch cut from it. This restores the intended end state of #4874 and lands the pin that prevents the race from recurring. - Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's canonical pure-Go build), removing the unreleased commands/flags and fixing the dangling nav entries. - docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh builds and caches a canonical pure-Go bd from that tag, fetching the tag first in shallow CI checkouts. - generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh resolve bd through the pin and ignore a supplied binary while pinned (BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot now enforce docs-match-release instead of docs-match-main. - tools/docsmint detects the pre-overhaul Docusaurus staging layout that bd <= v1.1.0 emits and converts it to the generic form before its normal Mintlify transform (tested); removable once the pin reaches a release whose emitter writes build/cli-docs. - check-doc-flags.sh: run without timeout(1) on macOS instead of failing Check 4. - Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the beads-docs skill §8 updated to match. * lint: annotate gosec G705 false positive in the docsmint legacy bridge Same class as the existing nav-splice annotation: a developer tool writing repo Markdown, not a web-output sink. --- .claude/skills/beads-docs/SKILL.md | 8 + docs/CLI_REFERENCE.md | 649 ++++-------------- docs/cli-docs.pin | 12 + docs/cli-reference/admin.md | 4 +- docs/cli-reference/ado.md | 4 +- docs/cli-reference/assign.md | 2 +- docs/cli-reference/audit.md | 13 +- docs/cli-reference/backup.md | 14 +- docs/cli-reference/batch.md | 2 +- docs/cli-reference/bootstrap.md | 2 +- docs/cli-reference/branch.md | 2 +- docs/cli-reference/children.md | 2 +- docs/cli-reference/close.md | 2 +- docs/cli-reference/comment.md | 2 +- docs/cli-reference/comments.md | 3 +- docs/cli-reference/compact.md | 2 +- docs/cli-reference/completion.md | 12 +- docs/cli-reference/config.md | 21 +- docs/cli-reference/context.md | 2 +- docs/cli-reference/cook.md | 2 +- docs/cli-reference/count.md | 2 +- docs/cli-reference/create-form.md | 2 +- docs/cli-reference/create.md | 3 +- docs/cli-reference/defer.md | 2 +- docs/cli-reference/delete.md | 2 +- docs/cli-reference/dep.md | 3 +- docs/cli-reference/diff.md | 2 +- docs/cli-reference/doctor.md | 2 +- docs/cli-reference/dolt.md | 22 +- docs/cli-reference/duplicate.md | 2 +- docs/cli-reference/duplicates.md | 2 +- docs/cli-reference/edit.md | 2 +- docs/cli-reference/epic.md | 2 +- docs/cli-reference/export.md | 14 +- docs/cli-reference/federation.md | 2 +- docs/cli-reference/find-duplicates.md | 2 +- docs/cli-reference/flatten.md | 2 +- docs/cli-reference/forget.md | 2 +- docs/cli-reference/formula.md | 46 +- docs/cli-reference/gate.md | 18 +- docs/cli-reference/gc.md | 2 +- docs/cli-reference/github.md | 4 +- docs/cli-reference/gitlab.md | 4 +- docs/cli-reference/graph.md | 8 +- docs/cli-reference/history.md | 4 +- docs/cli-reference/hooks.md | 4 +- docs/cli-reference/human.md | 3 +- docs/cli-reference/import.md | 2 +- docs/cli-reference/index.md | 26 +- docs/cli-reference/info.md | 2 +- docs/cli-reference/init-safety.md | 6 +- docs/cli-reference/init.md | 103 ++- docs/cli-reference/jira.md | 4 +- docs/cli-reference/kv.md | 4 +- docs/cli-reference/label.md | 10 +- docs/cli-reference/linear.md | 16 +- docs/cli-reference/link.md | 2 +- docs/cli-reference/lint.md | 6 +- docs/cli-reference/list.md | 2 - docs/cli-reference/mail.md | 2 +- docs/cli-reference/memories.md | 2 +- docs/cli-reference/merge-slot.md | 4 +- docs/cli-reference/metrics.md | 3 +- docs/cli-reference/migrate.md | 112 +-- docs/cli-reference/mol.md | 14 +- docs/cli-reference/note.md | 2 +- docs/cli-reference/notion.md | 4 +- docs/cli-reference/onboard.md | 2 +- docs/cli-reference/orphans.md | 2 +- docs/cli-reference/ping.md | 2 +- docs/cli-reference/preflight.md | 4 +- docs/cli-reference/prime.md | 38 +- docs/cli-reference/priority.md | 2 +- docs/cli-reference/promote.md | 2 +- docs/cli-reference/prune.md | 9 +- docs/cli-reference/purge.md | 2 +- docs/cli-reference/q.md | 4 +- docs/cli-reference/query.md | 2 +- docs/cli-reference/quickstart.md | 2 +- docs/cli-reference/ready.md | 2 +- docs/cli-reference/recall.md | 2 +- docs/cli-reference/recompute-blocked.md | 2 +- docs/cli-reference/remember.md | 2 +- docs/cli-reference/rename-prefix.md | 2 +- docs/cli-reference/rename.md | 2 +- docs/cli-reference/reopen.md | 2 +- docs/cli-reference/repo.md | 4 +- docs/cli-reference/restore.md | 2 +- docs/cli-reference/rules.md | 2 +- docs/cli-reference/search.md | 2 +- docs/cli-reference/set-state.md | 2 +- docs/cli-reference/setup.md | 7 +- docs/cli-reference/ship.md | 2 +- docs/cli-reference/sql.md | 2 +- docs/cli-reference/stale.md | 2 +- docs/cli-reference/state.md | 3 +- docs/cli-reference/status.md | 2 +- docs/cli-reference/statuses.md | 2 +- docs/cli-reference/supersede.md | 2 +- docs/cli-reference/swarm.md | 4 +- docs/cli-reference/tag.md | 2 +- docs/cli-reference/todo.md | 3 +- docs/cli-reference/types.md | 11 +- docs/cli-reference/undefer.md | 2 +- docs/cli-reference/update.md | 4 +- docs/cli-reference/upgrade.md | 4 +- docs/cli-reference/vc.md | 4 +- docs/cli-reference/where.md | 2 +- docs/cli-reference/worktree.md | 4 +- docs/docs.json | 4 - .../decisions/2026-07-17-docs-release-pin.md | 56 ++ scripts/check-cli-docs-drift.sh | 21 +- scripts/check-doc-flags.sh | 24 +- scripts/generate-cli-docs.sh | 32 +- scripts/resolve-docs-bd.sh | 59 ++ tools/docsmint/docsmint.go | 32 +- tools/docsmint/legacy.go | 142 ++++ tools/docsmint/legacy_test.go | 160 +++++ 118 files changed, 882 insertions(+), 1056 deletions(-) create mode 100644 docs/cli-docs.pin create mode 100644 engdocs/decisions/2026-07-17-docs-release-pin.md create mode 100755 scripts/resolve-docs-bd.sh create mode 100644 tools/docsmint/legacy.go create mode 100644 tools/docsmint/legacy_test.go diff --git a/.claude/skills/beads-docs/SKILL.md b/.claude/skills/beads-docs/SKILL.md index 939434ba5..52bab8362 100644 --- a/.claude/skills/beads-docs/SKILL.md +++ b/.claude/skills/beads-docs/SKILL.md @@ -190,6 +190,14 @@ style, nav), edit `tools/docsmint` and its tests. The drift gates (`generate-cli-docs.sh --check`, `scripts/check-cli-docs-drift.sh` in PR CI, and the docs-autofix bot) fail or auto-fix any hand edit. +**The docs describe the pinned release, not main.** `docs/cli-docs.pin` +names the release tag the whole docs corpus targets; the pipeline builds bd +from that tag and validates against it, so a Go-source edit on main shows up +in the committed docs only after the pin is bumped (at release time, +followed by a regeneration). Hand-written pages follow the same policy: +document what the pinned release does, never main-only features. See +`engdocs/decisions/2026-07-17-docs-release-pin.md`. + ## 9. Verify before you call it done Run the gates in [references/verification.md](references/verification.md). diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 649b2be17..1c4ea066d 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -25,13 +25,12 @@ Reference for bd Latest. Generated from `bd help --all`. - [bd gate list](#bd-gate-list) — List gate issues - [bd gate resolve](#bd-gate-resolve) — Manually resolve (close) a gate - [bd gate show](#bd-gate-show) — Show a gate issue -- [bd heartbeat](#bd-heartbeat) — Refresh the lease on an issue you hold in_progress - [bd label](#bd-label) — Manage issue labels - - [bd label add](#bd-label-add) — Add one or more labels to one or more issues + - [bd label add](#bd-label-add) — Add a label to one or more issues - [bd label list](#bd-label-list) — List labels for an issue - [bd label list-all](#bd-label-list-all) — List all unique labels in the database - [bd label propagate](#bd-label-propagate) — Propagate a label from a parent issue to all its children - - [bd label remove](#bd-label-remove) — Remove one or more labels from one or more issues + - [bd label remove](#bd-label-remove) — Remove a label from one or more issues - [bd link](#bd-link) — Link two issues with a dependency - [bd list](#bd-list) — List issues - [bd merge-slot](#bd-merge-slot) — Manage merge-slot gates for serialized conflict resolution @@ -44,7 +43,6 @@ Reference for bd Latest. Generated from `bd help --all`. - [bd promote](#bd-promote) — Promote a wisp to a permanent bead - [bd q](#bd-q) — Quick capture: create issue and output only ID - [bd query](#bd-query) — Query issues using a simple query language -- [bd reclaim](#bd-reclaim) — Revert stale-lease in_progress issues back to ready (dead-worker recovery) - [bd reopen](#bd-reopen) — Reopen one or more closed issues - [bd search](#bd-search) — Search issues by text query - [bd set-state](#bd-set-state) — Set operational state (creates event + updates label) @@ -56,7 +54,6 @@ Reference for bd Latest. Generated from `bd help --all`. - [bd todo add](#bd-todo-add) — Add a new TODO item - [bd todo done](#bd-todo-done) — Mark TODO(s) as done - [bd todo list](#bd-todo-list) — List TODO items -- [bd unclaim](#bd-unclaim) — Release a claimed issue - [bd update](#bd-update) — Update one or more issues ### Views & Reports: @@ -159,7 +156,6 @@ Reference for bd Latest. Generated from `bd help --all`. - [bd kv list](#bd-kv-list) — List all key-value pairs - [bd kv set](#bd-kv-set) — Set a key-value pair - [bd memories](#bd-memories) — List or search persistent memories -- [bd migrate-personal](#bd-migrate-personal) — Move personal planning issues from the project database to your planning repo - [bd onboard](#bd-onboard) — Display minimal snippet for agent instructions file - [bd prime](#bd-prime) — Output AI-optimized workflow context - [bd quickstart](#bd-quickstart) — Quick start guide for bd @@ -176,10 +172,6 @@ Reference for bd Latest. Generated from `bd help --all`. - [bd flatten](#bd-flatten) — Squash all Dolt history into a single commit - [bd gc](#bd-gc) — Garbage collect: decay old issues, compact Dolt commits, run Dolt GC - [bd migrate](#bd-migrate) — Database migration commands - - [bd migrate from-proxied-server-to-server](#bd-migrate-from-proxied-server-to-server) — [EXPERIMENTAL] Switch a proxied-server repo to server mode - - [bd migrate from-proxied-server-to-shared-server](#bd-migrate-from-proxied-server-to-shared-server) — [EXPERIMENTAL] Switch a proxied-server repo back to shared-server mode - - [bd migrate from-server-to-proxied-server](#bd-migrate-from-server-to-proxied-server) — [EXPERIMENTAL] Switch a server-mode repo to proxied-server mode - - [bd migrate from-shared-server-to-proxied-server](#bd-migrate-from-shared-server-to-proxied-server) — [EXPERIMENTAL] Switch a shared-server repo to proxied-server mode - [bd migrate hooks](#bd-migrate-hooks) — Plan or apply git hook migration to marker-managed format - [bd migrate issues](#bd-migrate-issues) — Move issues between repositories - [bd migrate schema](#bd-migrate-schema) — Apply pending schema migrations (idempotent) @@ -249,7 +241,6 @@ Reference for bd Latest. Generated from `bd help --all`. - [bd formula](#bd-formula) — Manage workflow formulas - [bd formula convert](#bd-formula-convert) — Convert formula from JSON to TOML - [bd formula list](#bd-formula-list) — List available formulas - - [bd formula schema](#bd-formula-schema) — Show the formula schema index (every exported struct in types.go) - [bd formula show](#bd-formula-show) — Show formula details - [bd github](#bd-github) — GitHub integration commands - [bd github pull](#bd-github-pull) — Pull specific items from GitHub @@ -312,7 +303,6 @@ These flags apply to all commands: --global Use the global shared-server database (beads_global) --ignore-schema-skew Proceed despite forward schema drift (some queries may fail) --json Output in JSON format - --no-color Disable color output (also: NO_COLOR=1 or CLICOLOR=0) --profile Generate CPU profile for performance analysis -q, --quiet Suppress non-essential output (errors only) --readonly Read-only mode: block write operations (for worker sandboxes) @@ -434,7 +424,6 @@ Examples: ``` bd comments [issue-id] [flags] -bd comments [command] ``` **Flags:** @@ -521,10 +510,9 @@ bd create [title] [flags] --silent Output only the issue ID (for scripting) --skills string Required skills for this issue --spec-id string Link to specification document - -s, --status string Initial status --stdin Read description from stdin (alias for --body-file -) --title string Issue title (alternative to positional argument) - -t, --type string Issue type (bug|feature|task|epic|chore|decision|spike|story|milestone); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task") + -t, --type string Issue type (bug|feature|task|epic|chore|decision); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task") --validate Validate description contains required sections for issue type --waits-for string Spawner issue ID to wait for (creates waits-for dependency for fanout gate) --waits-for-gate string Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children") @@ -639,11 +627,9 @@ Gate types: timer - Expires after timeout (Phase 2) gh:run - Waits for GitHub workflow (Phase 3) gh:pr - Waits for PR merge (Phase 3) - bead - Waits for another bead to close (Phase 4) + bead - Waits for cross-rig bead to close (Phase 4) -For bead gates, await_id is a bead ID in this rig's database (e.g., "bd-abc123"). -The historical cross-rig form <rig>:<bead-id> can no longer be evaluated -(multi-rig routing removed) and stays pending until resolved manually. +For bead gates, await_id format is <rig>:<bead-id> (e.g., "other-project:op-abc123"). Examples: bd gate list # Show all open gates @@ -653,7 +639,7 @@ Examples: bd gate resolve <id> # Close a gate manually ``` -bd gate [command] +bd gate ``` #### bd gate add-waiter @@ -785,16 +771,12 @@ bd gate discover [flags] #### bd gate list -List gate issues. - -With no argument, lists all gate issues in the current beads database. -With an [issue-id] argument, lists ONLY the gates that block that issue -(its own dependency gates) — not every gate in the database. +List all gate issues in the current beads database. By default, shows only open gates. Use --all to include closed gates. ``` -bd gate list [issue-id] [flags] +bd gate list [flags] ``` **Flags:** @@ -831,47 +813,20 @@ This is similar to 'bd show' but validates that the issue is a gate. bd gate show ``` -### bd heartbeat - -Refresh the lease on an issue you currently hold in_progress. - -A claim carries a lease that expires after a TTL. A worker keeps its claim alive -by heartbeating faster than the TTL; once it stops (because it died), the lease -goes stale and 'bd reclaim' reverts the issue to ready so another worker can pick -it up. Heartbeat pushes lease_expires_at forward and stamps heartbeat_at = now. - -Only the current owner may heartbeat. If the lease has already been reclaimed or -the issue closed, heartbeat fails so the worker learns to stop. - -Leases live in an ephemeral, node-local table: heartbeats write no Dolt commit -and no history, so any cadence comfortably below the TTL is fine. Leases are -only enforceable on the node that granted them; cross-machine claim visibility -rides the issue's status and assignee, which do commit. - -Examples: - bd heartbeat bd-123 - bd hb bd-123 - -``` -bd heartbeat -``` - -**Aliases:** hb - ### bd label Manage issue labels ``` -bd label [command] +bd label ``` #### bd label add -Add labels to issues. Issue IDs come first; the final argument is the label. Pass multiple labels comma-separated: bd label add bd-123 label1,label2 +Add a label to one or more issues ``` -bd label add [issue-id...] [label[,label...]] +bd label add [issue-id...] [label] ``` #### bd label list @@ -900,10 +855,10 @@ bd label propagate [parent-id] [label] #### bd label remove -Remove labels from issues. Issue IDs come first; the final argument is the label. Pass multiple labels comma-separated: bd label remove bd-123 label1,label2 +Remove a label from one or more issues ``` -bd label remove [issue-id...] [label[,label...]] +bd label remove [issue-id...] [label] ``` ### bd link @@ -954,8 +909,6 @@ bd list [flags] --empty-description Filter issues with empty or missing description --exclude-label strings Exclude issues that have ANY of these labels --exclude-type strings Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic) - --external-contains string Filter by external ref substring (case-insensitive) - --external-ref string Filter by exact external_ref value --flat Disable tree format and use legacy flat list output --format string Output format: 'digraph' (for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or Go template --has-metadata-key string Filter issues that have this metadata key set @@ -1023,7 +976,7 @@ Examples: bd merge-slot release # Release the slot ``` -bd merge-slot [command] +bd merge-slot ``` #### bd merge-slot acquire @@ -1168,7 +1121,6 @@ Example: bd q "Fix login bug" # Outputs: bd-a1b2 ISSUE=$(bd q "New feature") # Capture ID in variable bd q "Task" | xargs bd show # Pipe to other commands - bd q "Subtask" --parent=bd-a1b2 # Hierarchical child (outputs: bd-a1b2.1) ``` bd q [title] [flags] @@ -1178,7 +1130,6 @@ bd q [title] [flags] ``` -l, --labels strings Labels - --parent string Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9') -p, --priority string Priority (0-4 or P0-P4) (default "2") -t, --type string Issue type (default "task") ``` @@ -1259,37 +1210,6 @@ bd query [expression] [flags] --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee ``` -### bd reclaim - -Revert in_progress issues whose lease has gone stale back to ready. - -When a worker claims an issue it takes a lease that expires after a TTL, kept -alive by 'bd heartbeat'. A worker that dies stops heartbeating, so its lease -expires and its issue would otherwise stay in_progress forever. reclaim is the -reaper: it finds in_progress issues whose lease expired more than --older-than -ago, clears the assignee, and sets them back to open so another worker can -claim them. The previous owner's stale lease is recorded as a recovery event. - ---older-than is a grace window past lease expiry: only leases that expired at -least this long ago are reclaimed, so a worker briefly paused (GC, clock skew) -is not robbed of live work. Run it from a supervisor on a timer with a window -of roughly 2× the claim TTL. - -Examples: - bd reclaim # default grace window (2× the lease TTL) - bd reclaim --older-than 10m # reclaim leases expired >10m ago - bd reclaim --older-than 0s # reclaim every currently-expired lease - -``` -bd reclaim [flags] -``` - -**Flags:** - -``` - --older-than duration Only reclaim leases that expired at least this long ago (grace window) (default 10m0s) -``` - ### bd reopen Reopen closed issues by setting status to 'open' and clearing the closed_at timestamp. @@ -1438,7 +1358,6 @@ Examples: ``` bd state -bd state [command] ``` #### bd state list @@ -1486,7 +1405,6 @@ TODOs can be promoted to full issues by changing type or priority: ``` bd todo -bd todo [command] ``` #### bd todo add @@ -1532,34 +1450,6 @@ bd todo list [flags] --all Show all TODOs including completed ``` -### bd unclaim - -Release a claimed issue by clearing the assignee and resetting status to 'open'. - -Use this when an agent crashes mid-work or you need to abandon a claimed task. -The issue becomes available for re-claiming by other agents. - -Only the current assignee can release its own claim. Releasing another -actor's claim requires --force and should be coordinated with the holder -first — their claim may be live even if the issue looks idle. Prefer -letting lease expiry reclaim genuinely abandoned work. - -Examples: - bd unclaim bd-123 - bd unclaim bd-123 --reason "Agent crashed" - bd unclaim bd-123 bd-456 - -``` -bd unclaim [id...] [flags] -``` - -**Flags:** - -``` - --force Release the claim even if held by a different actor (admin/reaper use) - -r, --reason string Reason for unclaiming -``` - ### bd update Update one or more issues. @@ -1581,7 +1471,7 @@ bd update [id...] [flags] -a, --assignee string Assignee --await-id string Set gate await_id (e.g., GitHub run ID for gh:run gates) --body-file string Read description from file (use - for stdin) - --claim Atomically claim the issue (sets assignee to you, status to in_progress; idempotent if already claimed by you; issues assigned to a pool alias listed in the claim.pools config are claimable too) + --claim Atomically claim the issue (sets assignee to you, status to in_progress; idempotent if already claimed by you) --defer string Defer until date (empty to clear). Issue hidden from bd ready until then -d, --description string Issue description --design string Design notes @@ -1737,7 +1627,6 @@ where the issue was modified. Examples: bd history bd-123 # Show all history for issue bd-123 bd history bd-123 --limit 5 # Show last 5 changes - bd history bd-123 --events # Show database audit events ``` bd history [flags] @@ -1746,7 +1635,6 @@ bd history [flags] **Flags:** ``` - --events Show database audit events instead of commit snapshots --limit int Limit number of history entries (0 = all) ``` @@ -1760,7 +1648,7 @@ Section requirements by type: bug: Steps to Reproduce, Acceptance Criteria task: Acceptance Criteria feature: Acceptance Criteria - epic: Success Criteria (or Acceptance Criteria) + epic: Success Criteria chore: (none) Examples: @@ -1779,7 +1667,7 @@ bd lint [issue-id...] [flags] ``` -s, --status string Filter by status (default: open, use 'all' for all) - -t, --type string Filter by issue type (bug, task, feature, epic, decision, spike, story, chore, milestone) + -t, --type string Filter by issue type (bug, task, feature, epic) ``` ### bd stale @@ -1870,23 +1758,16 @@ bd statuses List all valid issue types that can be used with bd create --type. -Core work types (bug, task, feature, chore, epic, decision, spike, story, milestone) are always valid. +Core work types (bug, task, feature, chore, epic, decision) are always valid. Additional types require configuration via types.custom in .beads/config.yaml. Examples: bd types # List all types with descriptions - bd types --sections # List required sections for each type bd types --json # Output as JSON ``` -bd types [flags] -``` - -**Flags:** - -``` - --sections Show required sections for each issue type +bd types ``` ## Dependencies & Structure: @@ -1907,7 +1788,6 @@ Examples: ``` bd dep [issue-id] [flags] -bd dep [command] ``` **Flags:** @@ -2118,7 +1998,7 @@ bd duplicates [flags] Epic management commands ``` -bd epic [command] +bd epic ``` #### bd epic close-eligible @@ -2157,7 +2037,6 @@ For epics, shows all children and their dependencies. For regular issues, shows the issue and its direct dependencies. With --all, shows all open issues grouped by connected component. -With --open, filters to only open/actionable issues (compact layer format). Display formats: (default) DAG with columns and box-drawing edges (terminal-native) @@ -2165,7 +2044,6 @@ Display formats: --compact Tree format, one line per issue, more scannable --dot Graphviz DOT format (pipe to dot -Tsvg > graph.svg) --html Self-contained interactive HTML with D3.js visualization - --open Open issues only, compact layers (LLM-friendly) The graph shows execution order: - Layer 0 / leftmost = no dependencies (can start immediately) @@ -2181,12 +2059,9 @@ Examples: bd graph --dot issue-id | dot -Tpng > graph.png # PNG via Graphviz bd graph --html issue-id > graph.html # Interactive browser view bd graph --all --html > all.html # All issues, interactive - bd graph --open issue-id # Open issues only, layered by blocking order - bd graph --all --open # All open issues, compact layers ``` bd graph [issue-id] [flags] -bd graph [command] ``` **Flags:** @@ -2197,7 +2072,6 @@ bd graph [command] --compact Tree format, one line per issue, more scannable --dot Output Graphviz DOT format (pipe to: dot -Tsvg > graph.svg) --html Output self-contained interactive HTML (redirect to file) - --open Show only open issues (filters out closed/deferred), forces compact layer format ``` #### bd graph check @@ -2238,7 +2112,7 @@ A swarm is a structured body of work defined by an epic and its children, with dependencies forming a DAG (directed acyclic graph) of work. ``` -bd swarm [command] +bd swarm ``` #### bd swarm create @@ -2367,18 +2241,8 @@ DoltHub is recommended for cloud backup: bd backup init https://doltremoteapi.dolthub.com/<user>/<repo> Set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD for authentication. -Auto-backup default: - When backup.enabled is unset, auto-backup turns ON in embedded mode if a - git remote exists, and stays OFF in sql-server / shared-server mode. In - server mode many bd clients share one Dolt server, and each would register - a server-side backup remote under the same name pointing at its own local - dir and full-sync the whole database — a self-amplifying storm. To back up - a shared server, run 'bd backup' explicitly (or set backup.enabled=true and - coordinate destinations). 'bd config get backup.enabled' shows the effective - value and its source. - ``` -bd backup [command] +bd backup ``` #### bd backup init @@ -2515,13 +2379,11 @@ bd export [flags] **Flags:** ``` - --all Include all records (infra, templates, gates, memories) - --exclude-owner stringArray Exclude issues created by this identity (repeatable; also reads export.exclude_owners config) - --include-infra Include infrastructure beads (agents, roles, messages) - --include-memories Include persistent memories (from 'bd remember') in the export - -o, --output string Output file path (default: stdout) - --scrub Exclude test/pollution records - --verbose Print filtered issue count when owners are excluded + --all Include all records (infra, templates, gates, memories) + --include-infra Include infrastructure beads (agents, roles, messages) + --include-memories Include persistent memories (from 'bd remember') in the export + -o, --output string Output file path (default: stdout) + --scrub Exclude test/pollution records ``` ### bd federation @@ -2655,7 +2517,7 @@ Note: 'bd history', 'bd diff', and 'bd branch' also work for quick access. This subcommand provides additional operations like merge and commit. ``` -bd vc [command] +bd vc ``` #### bd vc commit @@ -2766,12 +2628,8 @@ Common namespaces: - jira.* Jira integration settings - linear.* Linear integration settings - github.* GitHub integration settings - - gitlab.* GitLab integration settings - - ado.* Azure DevOps integration settings - - notion.* Notion integration settings - custom.* Custom integration settings - status.* Issue status configuration - - claim.* Claim arbitration settings (pool-aware claiming) - doctor.suppress.* Suppress specific bd doctor warnings (GH#1095) Auto-Export (config.yaml): @@ -2805,18 +2663,6 @@ Custom Status States: This enables issues to use statuses like 'awaiting_review' in addition to the built-in statuses (open, in_progress, blocked, deferred, closed). -Claim Pools: - A dispatcher can pre-assign issues to a pool pseudo-assignee (e.g. - "fable-crew") and let any actor take them with --claim. List the pool - aliases in the claim.pools config key, comma-separated: - - bd config set claim.pools "fable-crew,night-crew" - - Issues assigned to a real actor (or to an alias not in the list) keep - their anti-steal protection. Pool takes carry the normal lease; note - that if a taker's lease expires, bd reclaim returns the issue to the - unassigned pool, not to the pool alias it was dispatched to. - Suppressing Doctor Warnings: Suppress specific bd doctor warnings by check name slug: bd config set doctor.suppress.pending-migrations true @@ -2833,7 +2679,6 @@ Examples: bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set status.custom "awaiting_review,awaiting_testing" - bd config set claim.pools "fable-crew,night-crew" # Pool aliases claimable by any actor bd config set doctor.suppress.pending-migrations true bd config set dolt.debug true # Enable Dolt sql-server debug mode (loglevel=debug, --prof cpu) bd config set dolt.local-only true # Skip wiring a Dolt sync remote during bd init @@ -2842,7 +2687,7 @@ Examples: bd config unset jira.url ``` -bd config [command] +bd config ``` #### bd config apply @@ -3067,7 +2912,7 @@ Examples: bd dolt test ``` -bd dolt [command] +bd dolt ``` #### bd dolt clean-databases @@ -3075,7 +2920,7 @@ bd dolt [command] Identify and drop leftover test and agent databases that accumulate on the shared Dolt server from interrupted test runs and terminated agents. -Stale database prefixes: testdb_*, beads_test*, beads_pt*, beads_vr*, doctest_*, doctortest_*, benchdb_* +Stale database prefixes: testdb_*, doctest_*, doctortest_*, beads_pt*, beads_vr*, beads_t* These waste server memory and can degrade performance under concurrent load. Use --dry-run to see what would be dropped without actually dropping. @@ -3186,7 +3031,7 @@ Subcommands: remove <name> Remove a remote ``` -bd dolt remote [command] +bd dolt remote ``` ##### bd dolt remote add @@ -3194,13 +3039,7 @@ bd dolt remote [command] Add a Dolt remote ``` -bd dolt remote add [flags] -``` - -**Flags:** - -``` - --allow-git-origin Allow adding a Dolt remote whose URL matches the git origin (proceed with a warning instead of aborting) +bd dolt remote add ``` ##### bd dolt remote list @@ -3277,10 +3116,10 @@ Show the status of the Dolt engine for the current project. In embedded mode, reports that the Dolt engine runs in-process and shows the on-disk data directory. For beads-managed (local) servers, displays PID, port, and data directory from the local PID file. For externally- -managed servers — a shared server (dolt.shared-server: true), a remote -dolt_server_host, or a local server managed outside bd (dolt.auto-start: -false, e.g. an orchestrator-shared sql-server) — pings the configured -endpoint via SQL and reports reachability, server version, and database. +managed servers — either a remote dolt_server_host or a local server +managed outside bd (dolt.auto-start: false, e.g. an orchestrator-shared +sql-server) — pings the configured endpoint via SQL and reports +reachability, server version, and database. ``` bd dolt status @@ -3343,7 +3182,7 @@ The hooks provide: - prepare-commit-msg: Add agent identity trailers for forensics ``` -bd hooks [command] +bd hooks ``` #### bd hooks install @@ -3430,7 +3269,6 @@ SUBCOMMANDS: ``` bd human -bd human [command] ``` #### bd human dismiss @@ -3542,11 +3380,10 @@ bd info [flags] ### bd init Initialize bd in the current directory by creating a .beads/ directory -and its storage (a Dolt database by default). Optionally specify a custom issue prefix. +and Dolt database. Optionally specify a custom issue prefix. -Dolt is the default backend and the only one with version control (history, -branching, sync). Select an alternative with --backend=<postgres|mysql|sqlite>; -see docs/architecture/storage-backends.md for the trade-offs and setup. +Dolt is the default (and only supported) storage backend. The legacy SQLite +backend has been removed. Use --backend=sqlite to see migration instructions. Use --database to specify an existing server database name, overriding the default prefix-based naming. This is useful when an external tool (e.g. an orchestrator) @@ -3583,58 +3420,48 @@ bd init [flags] **Flags:** ``` - --agents-file string Custom filename for agent instructions (default: AGENTS.md) - --agents-profile string AGENTS.md profile: 'minimal' (default, pointer to bd prime) or 'full' (complete command reference) - --agents-template string Path to custom AGENTS.md template (overrides embedded default) - --backend string Storage backend: dolt (default), postgres, mysql, or sqlite. See docs/architecture/storage-backends.md. - --contributor Run OSS contributor setup wizard - --database string Use existing server database name (overrides prefix-based naming) - --debug Run the managed Dolt sql-server with --loglevel=debug and CPU profiling (--prof cpu). Persisted to config.yaml as dolt.debug. No effect on externally-managed servers. - --destroy-token string Explicit confirmation token for destructive re-init in non-interactive mode (format: 'DESTROY-') - --discard-remote Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'. - --external Server is externally managed (skip server startup); use with --shared-server or --server - --force Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety'). - --from-jsonl Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement - --init-if-missing If the workspace is already initialized, skip init and exit 0 instead of failing (idempotent init for scaffolds) - --mysql-database string MySQL database for this workspace (with --backend=mysql; MySQL's isolation unit) - --mysql-url string MySQL server DSN (with --backend=mysql), e.g. user:pass@tcp(host:3306)/ . A password may be included for init but is never persisted; set BEADS_MYSQL_PASSWORD for later commands. Falls back to BEADS_MYSQL_URL. - --non-interactive Skip all interactive prompts (auto-detected in CI or non-TTY environments) - --pg-schema string Postgres schema for this workspace's tables (with --backend=postgres; provides search_path isolation) - --pg-url string Postgres connection URL (with --backend=postgres). A password may be included for init but is never persisted; set BEADS_PG_PASSWORD for later commands. Falls back to BEADS_POSTGRES_URL. - -p, --prefix string Issue prefix (default: current directory name) - --proxied-server [EXPERIMENTAL] Use a per-workspace proxied dolt sql-server (proxy + child dolt) rooted at .beads/dolt - --proxied-server-config-path string [EXPERIMENTAL] Absolute path to an existing dolt sql-server YAML config (proxied-server mode only). When set, bd uses this file instead of auto-generating one. Relative paths are rejected. - --proxied-server-external-host string [EXPERIMENTAL] Hostname or IP of an externally-managed dolt sql-server the proxy should front (proxied-server mode only). Mutually exclusive with --proxied-server-external-socket-path. - --proxied-server-external-keep-alive duration [EXPERIMENTAL] TCP keepalive period for the proxy→external connection. Zero uses the package default (30s). - --proxied-server-external-port int [EXPERIMENTAL] TCP port of the externally-managed dolt sql-server (proxied-server mode only). Required when --proxied-server-external-host is set. - --proxied-server-external-socket-path string [EXPERIMENTAL] Absolute unix socket path of the externally-managed dolt sql-server (proxied-server mode only). Mutually exclusive with --proxied-server-external-host. Relative paths are rejected. - --proxied-server-external-tls [EXPERIMENTAL] Require TLS when connecting to the externally-managed dolt sql-server (proxied-server mode only). - --proxied-server-external-tls-ca-cert-path string [EXPERIMENTAL] Absolute path to a CA certificate (PEM) used to verify the externally-managed dolt sql-server. Empty uses the system trust store. Relative paths are rejected. - --proxied-server-external-tls-cert-path string [EXPERIMENTAL] Absolute path to a client TLS certificate (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-key-path. Relative paths are rejected. - --proxied-server-external-tls-key-path string [EXPERIMENTAL] Absolute path to the client TLS private key (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-cert-path. Relative paths are rejected. - --proxied-server-external-tls-server-name string [EXPERIMENTAL] Server name to verify in the external dolt sql-server's TLS certificate. Defaults to the external host. Required with a unix socket unless --proxied-server-external-tls-skip-verify is set. - --proxied-server-external-tls-skip-verify [EXPERIMENTAL] Skip TLS certificate verification for the external dolt sql-server. Insecure; testing only. - --proxied-server-external-user string [EXPERIMENTAL] MySQL user for the externally-managed dolt sql-server (proxied-server mode only). Defaults to "root" when empty. Password is read at runtime from $BEADS_PROXIED_SERVER_EXTERNAL_PASSWORD and is never persisted to disk. - --proxied-server-idle-timeout duration [EXPERIMENTAL] Idle duration after which the proxy shuts down its loopback listener and backend (proxied-server mode only). Omit for the built-in default (30s); 0 keeps the proxy and backend alive indefinitely; a positive value sets the window. - --proxied-server-log-path string [EXPERIMENTAL] Absolute path to the proxied dolt sql-server log file (proxied-server mode only). Default: /dolt/server.log. Relative paths are rejected. - --proxied-server-port int [EXPERIMENTAL] Fixed TCP port for the proxy's loopback listener (proxied-server mode only). Default 0 = an OS-assigned free port. Startup fails if the port is already in use. - --proxied-server-root-path string [EXPERIMENTAL] Absolute directory holding the proxied dolt sql-server's lockfiles, pidfiles, and child .dolt repository (proxied-server mode only). Default: /dolt. May not exist yet — bd will create it. Relative paths are rejected. - -q, --quiet Suppress output (quiet mode) - --reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote. - --remote string Dolt remote URL to clone from and persist as sync.remote - --role string Set beads role without prompting: "maintainer" or "contributor" - --server Use external dolt sql-server instead of embedded engine - --server-host string Dolt server host (default: 127.0.0.1) - --server-port int Dolt server port (default: 3307) - --server-socket string Unix domain socket path (overrides host/port) - --server-user string Dolt server MySQL user (default: root) - --setup-exclude Configure .git/info/exclude to keep beads files local (for forks) - --shared-server Enable shared Dolt server mode (all projects share one server at ~/.beads/shared-server/) - --skip-agents Skip AGENTS.md and Claude/Codex/Cursor setup generation - --skip-hooks Skip git hooks installation - --sqlite-path string SQLite database file (with --backend=sqlite; relative to the beads dir, default beads.db) - --stealth Enable stealth mode: global gitattributes and gitignore, no local repo tracking - --team Run team workflow setup wizard + --agents-file string Custom filename for agent instructions (default: AGENTS.md) + --agents-profile string AGENTS.md profile: 'minimal' (default, pointer to bd prime) or 'full' (complete command reference) + --agents-template string Path to custom AGENTS.md template (overrides embedded default) + --backend string Storage backend (default: dolt). --backend=sqlite prints deprecation notice. + --contributor Run OSS contributor setup wizard + --database string Use existing server database name (overrides prefix-based naming) + --debug Run the managed Dolt sql-server with --loglevel=debug and CPU profiling (--prof cpu). Persisted to config.yaml as dolt.debug. No effect on externally-managed servers. + --destroy-token string Explicit confirmation token for destructive re-init in non-interactive mode (format: 'DESTROY-') + --discard-remote Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'. + --external Server is externally managed (skip server startup); use with --shared-server or --server + --force Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety'). + --from-jsonl Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement + --init-if-missing If the workspace is already initialized, skip init and exit 0 instead of failing (idempotent init for scaffolds) + --non-interactive Skip all interactive prompts (auto-detected in CI or non-TTY environments) + -p, --prefix string Issue prefix (default: current directory name) + --proxied-server [EXPERIMENTAL] Use a per-workspace proxied dolt sql-server (proxy + child dolt) rooted at .beads/proxieddb + --proxied-server-config-path string [EXPERIMENTAL] Absolute path to an existing dolt sql-server YAML config (proxied-server mode only). When set, bd uses this file instead of auto-generating one. Relative paths are rejected. + --proxied-server-external-host string [EXPERIMENTAL] Hostname or IP of an externally-managed dolt sql-server the proxy should front (proxied-server mode only). Mutually exclusive with --proxied-server-external-socket-path. + --proxied-server-external-keep-alive duration [EXPERIMENTAL] TCP keepalive period for the proxy→external connection. Zero uses the package default (30s). + --proxied-server-external-port int [EXPERIMENTAL] TCP port of the externally-managed dolt sql-server (proxied-server mode only). Required when --proxied-server-external-host is set. + --proxied-server-external-socket-path string [EXPERIMENTAL] Absolute unix socket path of the externally-managed dolt sql-server (proxied-server mode only). Mutually exclusive with --proxied-server-external-host. Relative paths are rejected. + --proxied-server-external-tls [EXPERIMENTAL] Require TLS when connecting to the externally-managed dolt sql-server (proxied-server mode only). + --proxied-server-external-tls-cert-path string [EXPERIMENTAL] Absolute path to a client TLS certificate (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-key-path. Relative paths are rejected. + --proxied-server-external-tls-key-path string [EXPERIMENTAL] Absolute path to the client TLS private key (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-cert-path. Relative paths are rejected. + --proxied-server-external-user string [EXPERIMENTAL] MySQL user for the externally-managed dolt sql-server (proxied-server mode only). Defaults to "root" when empty. Password is read at runtime from $BEADS_PROXIED_SERVER_EXTERNAL_PASSWORD and is never persisted to disk. + --proxied-server-log-path string [EXPERIMENTAL] Absolute path to the proxied dolt sql-server log file (proxied-server mode only). Default: /proxieddb/server.log. Relative paths are rejected. + --proxied-server-root-path string [EXPERIMENTAL] Absolute directory holding the proxied dolt sql-server's lockfiles, pidfiles, and child .dolt repository (proxied-server mode only). Default: /proxieddb. May not exist yet — bd will create it. Relative paths are rejected. + -q, --quiet Suppress output (quiet mode) + --reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote. + --remote string Dolt remote URL to clone from and persist as sync.remote + --role string Set beads role without prompting: "maintainer" or "contributor" + --server Use external dolt sql-server instead of embedded engine + --server-host string Dolt server host (default: 127.0.0.1) + --server-port int Dolt server port (default: 3307) + --server-socket string Unix domain socket path (overrides host/port) + --server-user string Dolt server MySQL user (default: root) + --setup-exclude Configure .git/info/exclude to keep beads files local (for forks) + --shared-server Enable shared Dolt server mode (all projects share one server at ~/.beads/shared-server/) + --skip-agents Skip AGENTS.md and Claude/Codex setup generation + --skip-hooks Skip git hooks installation + --stealth Enable stealth mode: global gitattributes and gitignore, no local repo tracking + --team Run team workflow setup wizard ``` ### bd kv @@ -3651,7 +3478,7 @@ Examples: bd kv list # List all key-value pairs ``` -bd kv [command] +bd kv ``` #### bd kv clear @@ -3719,33 +3546,6 @@ Examples: bd memories [search] ``` -### bd migrate-personal - -Identify issues you created in the project database and move them to your -personal planning repository (~/.beads-planning by default). - -This is a one-time migration for contributors who created personal planning -issues before contributor routing was configured. - -The command: - 1. Finds all issues in the project database created by your git identity - 2. Shows you the list and asks for confirmation - 3. Moves them to the planning repo configured in routing.contributor - -EXAMPLES: - bd migrate-personal # Interactive: show list and prompt - bd migrate-personal -y # Non-interactive: skip confirmation - -``` -bd migrate-personal [flags] -``` - -**Flags:** - -``` - -y, --yes Skip confirmation prompt -``` - ### bd onboard Display a minimal snippet to add to your agent instructions file for bd integration. @@ -3783,28 +3583,11 @@ Config options: - no-git-ops: When true, outputs stealth mode (no git commands in session close protocol). Set via: bd config set no-git-ops true Useful when you want to control when commits happen manually. -- agent.profile: Explicit policy profile for git/commit authority wording - (conservative | minimal | team-maintainer; default conservative). - Set via: bd config set agent.profile team-maintainer - Or per-session: BD_AGENT_PROFILE=team-maintainer (env var takes precedence). - See docs/getting-started/ide-setup.md#policy-profiles for what each profile means. Workflow customization: - - Place a .beads/PRIME.md file in the local clone or resolved workspace to override the default workflow text. Persistent memories (from bd remember) are still appended so memory injection keeps working under a custom template. + - Place a .beads/PRIME.md file in the local clone or resolved workspace to override the default output entirely. - Use --export to dump the default content for customization. - - Use --memories-only for hook contexts that should inject only persistent memories; this returns only the memories section even when a custom PRIME.md is present. - - Use --no-memories to omit the persistent memories section (useful when the memories section is large and would dominate a context budget). --memories-only takes precedence if both are set. - -Memory injection caps: - Large memory sets can exceed what a session-start hook host will ingest, - and hosts truncate silently. Cap what prime injects with --max-memories N - and/or --max-memory-chars N (or the prime.max-memories / - prime.max-memory-chars config keys; an explicit flag wins, and an explicit - 0 forces unlimited). Caps apply at whole-memory boundaries, at least one - memory is always emitted, and a banner ahead of the entries reports how - many were elided and how to browse the rest with bd memories. - --max-memory-chars caps the total bytes of the injected memory entries; - the section header and elision banner are excluded from the budget. + - Use --memories-only for hook contexts that should inject only persistent memories. ``` bd prime [flags] @@ -3813,15 +3596,12 @@ bd prime [flags] **Flags:** ``` - --export Output default content (ignores PRIME.md override) - --full Force full CLI output (ignore MCP detection) - --hook-json Wrap output in the SessionStart hook JSON envelope (Claude Code, Gemini CLI, Codex) - --max-memories int Cap injected persistent memories to N entries (0 = unlimited; falls back to the prime.max-memories config key) - --max-memory-chars int Cap the total bytes of injected memory entries, at whole-memory boundaries; section header and banner are not counted (0 = unlimited; falls back to the prime.max-memory-chars config key) - --mcp Force MCP mode (minimal output) - --memories-only Output only persistent memories for compact hook contexts - --no-memories Omit the persistent memories section (ignored when --memories-only is set, which wins) - --stealth Stealth mode (no git operations, flush only) + --export Output default content (ignores PRIME.md override) + --full Force full CLI output (ignore MCP detection) + --hook-json Wrap output in the SessionStart hook JSON envelope (Claude Code, Gemini CLI, Codex) + --mcp Force MCP mode (minimal output) + --memories-only Output only persistent memories for compact hook contexts + --stealth Stealth mode (no git operations, flush only) ``` ### bd quickstart @@ -3880,8 +3660,7 @@ Recipes define where beads workflow instructions are written. Built-in recipes include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode. Examples: - bd setup cursor # Install Cursor IDE integration (rules + agent hooks) - bd setup cursor --global # Install global Cursor hooks (~/.cursor/hooks.json) + bd setup cursor # Install Cursor IDE integration bd setup codex # Install Codex skill + AGENTS.md guidance + native hooks bd setup codex --global # Install global Codex skill + guidance + native hooks bd setup copilot # Install Copilot CLI plugin + repository instructions @@ -3905,7 +3684,7 @@ bd setup [recipe] [flags] ``` --add string Add a custom recipe with given name --check Check if integration is installed - --global Install globally (claude/codex/cursor/mux; writes to ~/.claude/settings.json, $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md, ~/.cursor/hooks.json, or ~/.mux/AGENTS.md) + --global Install globally (claude/codex/mux; writes to ~/.claude/settings.json, $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md, or ~/.mux/AGENTS.md) --list List all available recipes -o, --output string Write template to custom path --print Print the template to stdout @@ -4244,125 +4023,26 @@ Database migration and data transformation commands. Without subcommand, checks and updates database metadata to current version. Subcommands: - hooks Plan git hook migration to marker-managed format - issues Move issues between repositories - schema Apply pending schema migrations (idempotent) - sync Set up sync.branch workflow for multi-clone setups - from-server-to-proxied-server [EXPERIMENTAL] Switch server mode to proxied-server mode - from-proxied-server-to-server [EXPERIMENTAL] Switch proxied-server mode to server mode - from-shared-server-to-proxied-server [EXPERIMENTAL] Switch shared-server mode to proxied-server mode - from-proxied-server-to-shared-server [EXPERIMENTAL] Switch proxied-server mode to shared-server mode - -On a remote-backed database with pending schema migrations bd refuses to -migrate in place (#4259): migrating two clones independently forks the schema -so bd dolt pull can no longer merge — the break is silent and unrecoverable. -Use --force to confirm you are the single designated migrator, after which you -should publish the migrated schema with 'bd dolt push'. The env-var equivalent -BD_ALLOW_REMOTE_MIGRATE=1 remains supported for scripted/CI use. + hooks Plan git hook migration to marker-managed format + issues Move issues between repositories + schema Apply pending schema migrations (idempotent) + sync Set up sync.branch workflow for multi-clone setups ``` bd migrate [flags] -bd migrate [command] ``` **Flags:** ``` --dry-run Show what would be done without making changes - --force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1) --inspect Show migration plan and database state for AI agent analysis --json Output migration statistics in JSON format --update-repo-id Update repository ID (use after changing git remote) --yes Auto-confirm prompts ``` -#### bd migrate from-proxied-server-to-server - -Switch a repo from proxied-server mode to server mode (bd init --server). - -Both modes root their dolt sql-server at the same .beads/dolt directory, so this -only rewrites .beads/metadata.json (dolt_mode) and removes the proxied-server -sidecar — no Dolt data is copied or moved. Stop the running proxy first with -'bd dolt stop'. - -Note: dolt_mode lives in the committed metadata.json, so this change propagates -to clones on the next push. - -``` -bd migrate from-proxied-server-to-server [flags] -``` - -**Flags:** - -``` - --dry-run Show what would be done without making changes -``` - -#### bd migrate from-proxied-server-to-shared-server - -Switch a repo from proxied-server mode back to shared-server mode. - -Only applies to a proxied-server repo rooted at the shared dolt directory -(~/.beads/shared-server/dolt) — the reverse of from-shared-server-to-proxied-server. -This rewrites .beads/metadata.json (dolt_mode), re-enables dolt.shared-server, and -removes the proxied-server sidecar; no Dolt data is copied or moved. Stop the -running proxy first with 'bd dolt stop'. - -``` -bd migrate from-proxied-server-to-shared-server [flags] -``` - -**Flags:** - -``` - --dry-run Show what would be done without making changes -``` - -#### bd migrate from-server-to-proxied-server - -Switch a repo from server mode (bd init --server) to proxied-server mode. - -Both modes root their dolt sql-server at the same .beads/dolt directory, so this -only rewrites .beads/metadata.json (dolt_mode) and writes the proxied-server -sidecar — no Dolt data is copied or moved. Stop the running server first with -'bd dolt stop'. - -Note: dolt_mode lives in the committed metadata.json, so this change propagates -to clones on the next push. - -``` -bd migrate from-server-to-proxied-server [flags] -``` - -**Flags:** - -``` - --dry-run Show what would be done without making changes - --idle-timeout duration Proxy idle timeout; omit for the 30s default, 0 for indefinite uptime -``` - -#### bd migrate from-shared-server-to-proxied-server - -Switch a repo from shared-server mode to proxied-server mode. - -The proxied server is rooted at the shared dolt directory -(~/.beads/shared-server/dolt), so no Dolt data is copied or moved; this rewrites -.beads/metadata.json (dolt_mode), turns off dolt.shared-server for this repo, and -writes the proxied-server sidecar. Stop the running shared server first with -'bd dolt stop' — note that stops it for every project sharing it. - -``` -bd migrate from-shared-server-to-proxied-server [flags] -``` - -**Flags:** - -``` - --dry-run Show what would be done without making changes - --idle-timeout duration Proxy idle timeout; omit for the 30s default, 0 for indefinite uptime -``` - #### bd migrate hooks Analyze git hook files and sidecar artifacts for migration to marker-managed format. @@ -4453,8 +4133,7 @@ bd migrate schema [flags] **Flags:** ``` - --force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1) - --json Output in JSON format + --json Output in JSON format ``` #### bd migrate sync @@ -4525,7 +4204,7 @@ bd preflight [flags] ``` --check Run checks automatically - --fix Auto-fix issues where possible (vendorHash, version sync) + --fix Auto-fix issues where possible (not yet implemented) --json Output results as JSON --skip-lint Skip lint check explicitly ``` @@ -4545,12 +4224,6 @@ Use `--pattern '*'` if you really do want to sweep everything closed. Deletes: issues, dependencies, labels, events, and comments for matching beads. Skips: pinned beads (protected), open/in-progress beads, and ephemeral beads. -Also skips closed beads whose ID appears in the description, notes, or -comments of any open / in-progress bead. This protects ADR / decision / -verification trails that downstream beads still cite. Use ---ignore-references to override (e.g., when bulk-decommissioning a -retired label across the rig). - To delete closed ephemeral beads (wisps, transient molecules) use `bd purge` instead. @@ -4573,7 +4246,6 @@ bd prune [flags] ``` --dry-run Preview what would be pruned with stats -f, --force Actually prune (without this, shows preview) - --ignore-references Delete closed beads even when referenced by open beads (use with care; see --help for details) --older-than string Only prune beads closed more than N ago (e.g., 30d, 2w, 60) --pattern string Only prune beads matching ID glob pattern (e.g., 'gm-old-*') ``` @@ -4684,7 +4356,7 @@ bd rename-prefix [flags] Audit and compact Claude rules ``` -bd rules [command] +bd rules ``` #### bd rules audit @@ -4759,7 +4431,7 @@ The upgrade command helps you stay aware of bd version changes: Version tracking is automatic - bd updates metadata.json on every run. ``` -bd upgrade [command] +bd upgrade ``` #### bd upgrade ack @@ -4832,7 +4504,7 @@ Examples: bd worktree info # Show info about current worktree ``` -bd worktree [command] +bd worktree ``` #### bd worktree create @@ -4937,7 +4609,7 @@ For routine maintenance, prefer 'bd doctor --fix' which handles common repairs automatically. Use these admin commands for targeted database operations. ``` -bd admin [command] +bd admin ``` #### bd admin cleanup @@ -5102,7 +4774,7 @@ Examples: bd jira status # Show sync status ``` -bd jira [command] +bd jira ``` #### bd jira pull @@ -5255,7 +4927,7 @@ Examples: bd linear status # Show sync status ``` -bd linear [command] +bd linear ``` #### bd linear pull @@ -5336,18 +5008,6 @@ Type Filtering (--push only): --parent TICKET Only push this ticket and its descendants --relations Import Linear relations as bd dependencies on pull -Persistent push-direction ID filters (workflow artifacts, sandbox beads, etc.): - bd config set linear.exclude_id_prefix "hw-mol-" - bd config set linear.exclude_id_patterns "-wisp-,sandbox-,scratch-" - - exclude_id_prefix is a single case-sensitive prefix on the bead ID. - exclude_id_patterns is a comma-separated list of case-sensitive substrings - (matched anywhere in the ID). Both are combined as a union: a bead - matching either rule is skipped from push (no create, no update). Beads - with an existing external_ref that NOW match are silently skipped on - future syncs; the Linear-side issue persists — archive/delete it manually - if desired. - Conflict Resolution: By default, newer timestamp wins. Override with: --prefer-local Always prefer local beads version @@ -5430,7 +5090,7 @@ Examples: bd repo sync # Sync from all configured repos ``` -bd repo [command] +bd repo ``` #### bd repo add @@ -5525,7 +5185,7 @@ Configuration can be set via 'bd config' or environment variables: ado.url / AZURE_DEVOPS_URL - Custom base URL (on-prem) ``` -bd ado [command] +bd ado ``` #### bd ado projects @@ -5624,21 +5284,16 @@ bd ado sync [flags] ### bd audit -Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl. +Audit log entries are appended to .beads/interactions.jsonl. -This optional JSONL sidecar is disabled by default. Enable it with: - - bd config set audit.enabled true - -Issue history is always recorded in the database and is visible with -bd history <id> --events. The JSONL sidecar is for explicit interaction capture: +Each line is one event. This file is intended to be versioned in git and used for: - auditing ("why did the agent do that?") - dataset generation (SFT/RL fine-tuning) Entries are append-only. Labeling creates a new "label" entry that references a parent entry. ``` -bd audit [command] +bd audit ``` #### bd audit label @@ -5699,7 +5354,7 @@ See each sub-command's help for details on how to use the generated script. ``` -bd completion [command] +bd completion ``` #### bd completion bash @@ -5927,19 +5582,11 @@ Search paths (in order): 4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set) Commands: - list List available formulas from all search paths - show Show formula details, steps, and composition rules - schema Show the formula schema index (alias: primitives) - -Discovering primitives: - bd formula schema # list every declared formula struct - bd formula schema loop # show LoopSpec fields, types, and tags - bd formula primitives gate # alias; same handler as 'schema' - examples/formulas/primitives/ # curated, smoke-tested wired fixtures - docs/workflows/formulas.md # narrative reference + list List available formulas from all search paths + show Show formula details, steps, and composition rules ``` -bd formula [command] +bd formula ``` #### bd formula convert @@ -5985,9 +5632,6 @@ Search paths (in order of priority): Formulas in earlier paths shadow those with the same name in later paths. -To list the declared formula schema structs an agent can write inside a .formula.toml, -use 'bd formula schema' (alias: 'bd formula primitives'). - Examples: bd formula list bd formula list --json @@ -6004,30 +5648,6 @@ bd formula list [flags] --type string Filter by type (workflow, expansion, aspect, convoy) ``` -#### bd formula schema - -Show the formula schema index: every exported struct declared -in a .formula.toml/.formula.json, with field names, types, and tags. - -The index is generated from internal/formula/types.go via go:generate; the -struct definitions are the source of truth, so this list cannot drift. It is -structural reference, not proof that every declared runtime behavior is wired. - -Examples: - bd formula schema # list every declared schema struct - bd formula schema loop # show LoopSpec fields - bd formula primitives gate # alias; shows Gate fields - bd formula schema --json # machine-readable index - -Curated smoke-tested fixtures for wired primitives live in -examples/formulas/primitives/ (with a smoke harness that proves they work). - -``` -bd formula schema [primitive] -``` - -**Aliases:** primitives - #### bd formula show Show detailed information about a formula. @@ -6039,9 +5659,6 @@ Displays: - Composition rules (extends, aspects, expansions) - Bond points for external composition -To inspect the structure of an individual primitive (e.g. LoopSpec, Gate) -rather than a user-authored formula, use 'bd formula schema <primitive>'. - Examples: bd formula show shiny bd formula show rule-of-five @@ -6063,7 +5680,7 @@ Configuration can be set via 'bd config' or environment variables: github.url / GITHUB_API_URL - Custom API URL (GitHub Enterprise) ``` -bd github [command] +bd github ``` #### bd github pull @@ -6155,7 +5772,7 @@ Configuration can be set via 'bd config' or environment variables: gitlab.default_project_id / GITLAB_DEFAULT_PROJECT_ID - Project for creating issues in group mode ``` -bd gitlab [command] +bd gitlab ``` #### bd gitlab projects @@ -6254,11 +5871,12 @@ bd help [command] [flags] **Flags:** ``` - --all Show help for all commands in a single document - --doc string Generate markdown docs for a single command - --docs-root string Generate repository CLI docs under this root - -h, --help help for help - --list List all available commands + --all Show help for all commands in a single document + --doc string Generate markdown docs for a single command + --docs-root string Generate repository CLI docs under this root + --docs-version string Also refresh one versioned website CLI reference, e.g. 1.0.5 + -h, --help help for help + --list List all available commands ``` ### bd init-safety @@ -6315,7 +5933,7 @@ DESTROY-TOKEN (non-interactive only) In interactive (TTY) mode you confirm via a typed prompt instead. The token is not echoed by bd's runtime error messages — this is a deliberate guard against pattern-matched one-liners (see - engdocs/adr/0002-init-safety-invariants.md). + docs/adr/0002-init-safety-invariants.md). EXIT CODES @@ -6327,7 +5945,7 @@ EXIT CODES RECOVERY - If you hit a refusal, see docs/recovery/init-safety.md for step-by-step recovery + If you hit a refusal, see docs/RECOVERY.md for step-by-step recovery playbooks for each exit code. @@ -6379,7 +5997,6 @@ any user-supplied text. ``` bd metrics -bd metrics [command] ``` #### bd metrics example @@ -6432,7 +6049,7 @@ Commands: Use "bd formula list" to list available formulas. ``` -bd mol [command] +bd mol ``` **Aliases:** protomolecule @@ -6639,8 +6256,7 @@ bd mol last-activity Pour a proto into a persistent mol - like pouring molten metal into a mold. This is the chemistry-inspired command for creating PERSISTENT work from templates. -The resulting mol is stored as persistent beads in the issue database and -syncs like any other bead (bd dolt push / pull). +The resulting mol lives in .beads/ (permanent storage) and is synced with git. Phase transition: Proto (solid) -> pour -> Mol (liquid) @@ -6717,13 +6333,7 @@ Examples: bd mol ready --gated --json # JSON output for automation ``` -bd mol ready --gated [flags] -``` - -**Flags:** - -``` - --gated Find molecules ready for gate-resume dispatch (always on for this subcommand) +bd mol ready --gated ``` #### bd mol seed @@ -6893,7 +6503,6 @@ Subcommands: ``` bd mol wisp [proto-id] [flags] -bd mol wisp [command] ``` **Flags:** @@ -7023,7 +6632,7 @@ bd mol wisp list [flags] Commands for syncing issues between beads and Notion. ``` -bd notion [command] +bd notion ``` #### bd notion connect diff --git a/docs/cli-docs.pin b/docs/cli-docs.pin new file mode 100644 index 000000000..3f0c45895 --- /dev/null +++ b/docs/cli-docs.pin @@ -0,0 +1,12 @@ +# Pins the bd version that the generated CLI docs are produced from and +# validated against: docs/CLI_REFERENCE.md, docs/cli-reference/, and the +# CLI Reference pages array in docs/docs.json. +# +# The published docs site describes the latest *release*, not main's source, +# so the docs pipeline builds bd from this tag (CGO_ENABLED=0, pure Go — +# CI's canonical build) instead of the current checkout. Bump this tag as +# part of each release, then run ./scripts/generate-cli-docs.sh. +# +# Set to HEAD to track the current checkout's source instead (the pre-pin +# behavior). +v1.1.0 diff --git a/docs/cli-reference/admin.md b/docs/cli-reference/admin.md index 4ae453c44..a5bd92298 100644 --- a/docs/cli-reference/admin.md +++ b/docs/cli-reference/admin.md @@ -1,6 +1,6 @@ --- title: "bd admin" -description: "Administrative commands for database maintenance" +description: "Administrative commands for beads database maintenance." --- {/* AUTO-GENERATED: do not edit manually */} @@ -18,7 +18,7 @@ For routine maintenance, prefer 'bd doctor --fix' which handles common repairs automatically. Use these admin commands for targeted database operations. ``` -bd admin [command] +bd admin [flags] ``` ## bd admin cleanup diff --git a/docs/cli-reference/ado.md b/docs/cli-reference/ado.md index f70320b24..b2b494f14 100644 --- a/docs/cli-reference/ado.md +++ b/docs/cli-reference/ado.md @@ -1,6 +1,6 @@ --- title: "bd ado" -description: "Azure DevOps integration commands" +description: "Commands for syncing issues between beads and Azure DevOps." --- {/* AUTO-GENERATED: do not edit manually */} @@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables: ado.url / AZURE_DEVOPS_URL - Custom base URL (on-prem) ``` -bd ado [command] +bd ado [flags] ``` ## bd ado projects diff --git a/docs/cli-reference/assign.md b/docs/cli-reference/assign.md index 9d04f158e..c75eccc86 100644 --- a/docs/cli-reference/assign.md +++ b/docs/cli-reference/assign.md @@ -1,6 +1,6 @@ --- title: "bd assign" -description: "Assign an issue to someone" +description: "Assign an issue to someone." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/audit.md b/docs/cli-reference/audit.md index 4c8cb757a..8d4bc65b1 100644 --- a/docs/cli-reference/audit.md +++ b/docs/cli-reference/audit.md @@ -1,27 +1,22 @@ --- title: "bd audit" -description: "Record and label agent interactions (append-only JSONL)" +description: "Audit log entries are appended to .beads/interactions.jsonl." --- {/* AUTO-GENERATED: do not edit manually */} Generated from `bd help --doc audit`. -Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl. +Audit log entries are appended to .beads/interactions.jsonl. -This optional JSONL sidecar is disabled by default. Enable it with: - - bd config set audit.enabled true - -Issue history is always recorded in the database and is visible with -bd history <id> --events. The JSONL sidecar is for explicit interaction capture: +Each line is one event. This file is intended to be versioned in git and used for: - auditing ("why did the agent do that?") - dataset generation (SFT/RL fine-tuning) Entries are append-only. Labeling creates a new "label" entry that references a parent entry. ``` -bd audit [command] +bd audit [flags] ``` ## bd audit label diff --git a/docs/cli-reference/backup.md b/docs/cli-reference/backup.md index 022f3a300..6c3ab6068 100644 --- a/docs/cli-reference/backup.md +++ b/docs/cli-reference/backup.md @@ -1,6 +1,6 @@ --- title: "bd backup" -description: "Back up your beads database" +description: "Back up your beads database for off-machine recovery." --- {/* AUTO-GENERATED: do not edit manually */} @@ -25,18 +25,8 @@ DoltHub is recommended for cloud backup: bd backup init https://doltremoteapi.dolthub.com/<user>/<repo> Set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD for authentication. -Auto-backup default: - When backup.enabled is unset, auto-backup turns ON in embedded mode if a - git remote exists, and stays OFF in sql-server / shared-server mode. In - server mode many bd clients share one Dolt server, and each would register - a server-side backup remote under the same name pointing at its own local - dir and full-sync the whole database — a self-amplifying storm. To back up - a shared server, run 'bd backup' explicitly (or set backup.enabled=true and - coordinate destinations). 'bd config get backup.enabled' shows the effective - value and its source. - ``` -bd backup [command] +bd backup [flags] ``` ## bd backup init diff --git a/docs/cli-reference/batch.md b/docs/cli-reference/batch.md index 85a5f5bc0..a6ce02171 100644 --- a/docs/cli-reference/batch.md +++ b/docs/cli-reference/batch.md @@ -1,6 +1,6 @@ --- title: "bd batch" -description: "Run multiple write operations in a single database transaction" +description: "Run multiple write operations in a single database transaction." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/bootstrap.md b/docs/cli-reference/bootstrap.md index 5a4eca470..13dfa24a8 100644 --- a/docs/cli-reference/bootstrap.md +++ b/docs/cli-reference/bootstrap.md @@ -1,6 +1,6 @@ --- title: "bd bootstrap" -description: "Non-destructive database setup for fresh clones and recovery" +description: "Bootstrap sets up the beads database without destroying existing data." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/branch.md b/docs/cli-reference/branch.md index 29b395434..24d1e3afe 100644 --- a/docs/cli-reference/branch.md +++ b/docs/cli-reference/branch.md @@ -1,6 +1,6 @@ --- title: "bd branch" -description: "List or create branches" +description: "List all branches or create a new branch." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/children.md b/docs/cli-reference/children.md index e66de73cd..d85e0f15d 100644 --- a/docs/cli-reference/children.md +++ b/docs/cli-reference/children.md @@ -1,6 +1,6 @@ --- title: "bd children" -description: "List child beads of a parent" +description: "List all beads that are children of the specified parent bead." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/close.md b/docs/cli-reference/close.md index 44b9c01e6..435214110 100644 --- a/docs/cli-reference/close.md +++ b/docs/cli-reference/close.md @@ -1,6 +1,6 @@ --- title: "bd close" -description: "Close one or more issues" +description: "Close one or more issues." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/comment.md b/docs/cli-reference/comment.md index ece11fa4d..312584afc 100644 --- a/docs/cli-reference/comment.md +++ b/docs/cli-reference/comment.md @@ -1,6 +1,6 @@ --- title: "bd comment" -description: "Add a comment to an issue" +description: "Add a comment to an issue." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/comments.md b/docs/cli-reference/comments.md index 1ec06f612..2b8c6b397 100644 --- a/docs/cli-reference/comments.md +++ b/docs/cli-reference/comments.md @@ -1,6 +1,6 @@ --- title: "bd comments" -description: "View or manage comments on an issue" +description: "View or manage comments on an issue." --- {/* AUTO-GENERATED: do not edit manually */} @@ -24,7 +24,6 @@ Examples: ``` bd comments [issue-id] [flags] -bd comments [command] ``` **Flags:** diff --git a/docs/cli-reference/compact.md b/docs/cli-reference/compact.md index 82548daad..59f66a122 100644 --- a/docs/cli-reference/compact.md +++ b/docs/cli-reference/compact.md @@ -1,6 +1,6 @@ --- title: "bd compact" -description: "Squash old Dolt commits to reduce history size" +description: "Squash Dolt commits older than N days into a single commit." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/completion.md b/docs/cli-reference/completion.md index 53cc05b50..44f7e794d 100644 --- a/docs/cli-reference/completion.md +++ b/docs/cli-reference/completion.md @@ -1,6 +1,6 @@ --- title: "bd completion" -description: "Generate the autocompletion script for the specified shell" +description: "Generate the autocompletion script for bd for the specified shell." --- {/* AUTO-GENERATED: do not edit manually */} @@ -12,7 +12,7 @@ See each sub-command's help for details on how to use the generated script. ``` -bd completion [command] +bd completion [flags] ``` ## bd completion bash @@ -28,11 +28,11 @@ To load completions in your current shell session: To load completions for every new session, execute once: -#### Linux: +### Linux: bd completion bash > /etc/bash_completion.d/bd -#### macOS: +### macOS: bd completion bash > $(brew --prefix)/etc/bash_completion.d/bd @@ -111,11 +111,11 @@ To load completions in your current shell session: To load completions for every new session, execute once: -#### Linux: +### Linux: bd completion zsh > "${fpath[1]}/_bd" -#### macOS: +### macOS: bd completion zsh > $(brew --prefix)/share/zsh/site-functions/_bd diff --git a/docs/cli-reference/config.md b/docs/cli-reference/config.md index 616c56b95..4156ce6e2 100644 --- a/docs/cli-reference/config.md +++ b/docs/cli-reference/config.md @@ -1,6 +1,6 @@ --- title: "bd config" -description: "Manage configuration settings" +description: "Manage configuration settings for external integrations and preferences." --- {/* AUTO-GENERATED: do not edit manually */} @@ -17,12 +17,8 @@ Common namespaces: - jira.* Jira integration settings - linear.* Linear integration settings - github.* GitHub integration settings - - gitlab.* GitLab integration settings - - ado.* Azure DevOps integration settings - - notion.* Notion integration settings - custom.* Custom integration settings - status.* Issue status configuration - - claim.* Claim arbitration settings (pool-aware claiming) - doctor.suppress.* Suppress specific bd doctor warnings (GH#1095) Auto-Export (config.yaml): @@ -56,18 +52,6 @@ Custom Status States: This enables issues to use statuses like 'awaiting_review' in addition to the built-in statuses (open, in_progress, blocked, deferred, closed). -Claim Pools: - A dispatcher can pre-assign issues to a pool pseudo-assignee (e.g. - "fable-crew") and let any actor take them with --claim. List the pool - aliases in the claim.pools config key, comma-separated: - - bd config set claim.pools "fable-crew,night-crew" - - Issues assigned to a real actor (or to an alias not in the list) keep - their anti-steal protection. Pool takes carry the normal lease; note - that if a taker's lease expires, bd reclaim returns the issue to the - unassigned pool, not to the pool alias it was dispatched to. - Suppressing Doctor Warnings: Suppress specific bd doctor warnings by check name slug: bd config set doctor.suppress.pending-migrations true @@ -84,7 +68,6 @@ Examples: bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set status.custom "awaiting_review,awaiting_testing" - bd config set claim.pools "fable-crew,night-crew" # Pool aliases claimable by any actor bd config set doctor.suppress.pending-migrations true bd config set dolt.debug true # Enable Dolt sql-server debug mode (loglevel=debug, --prof cpu) bd config set dolt.local-only true # Skip wiring a Dolt sync remote during bd init @@ -93,7 +76,7 @@ Examples: bd config unset jira.url ``` -bd config [command] +bd config [flags] ``` ## bd config apply diff --git a/docs/cli-reference/context.md b/docs/cli-reference/context.md index b1bd9317a..21a2b3a82 100644 --- a/docs/cli-reference/context.md +++ b/docs/cli-reference/context.md @@ -1,6 +1,6 @@ --- title: "bd context" -description: "Show effective backend identity and repository context" +description: "Show the effective backend identity information including repository paths," --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/cook.md b/docs/cli-reference/cook.md index ddf8567fa..a7ae0efa3 100644 --- a/docs/cli-reference/cook.md +++ b/docs/cli-reference/cook.md @@ -1,6 +1,6 @@ --- title: "bd cook" -description: "Compile a formula into a proto (ephemeral by default)" +description: "Cook transforms a .formula.json file into a proto." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/count.md b/docs/cli-reference/count.md index c2e367b56..ce7927c86 100644 --- a/docs/cli-reference/count.md +++ b/docs/cli-reference/count.md @@ -1,6 +1,6 @@ --- title: "bd count" -description: "Count issues matching filters" +description: "Count issues matching the specified filters." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/create-form.md b/docs/cli-reference/create-form.md index 8e63d7f18..9486042d8 100644 --- a/docs/cli-reference/create-form.md +++ b/docs/cli-reference/create-form.md @@ -1,6 +1,6 @@ --- title: "bd create-form" -description: "Create a new issue using an interactive form" +description: "Create a new issue using an interactive terminal form." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/create.md b/docs/cli-reference/create.md index 6b0b6b5f3..2e9341cb8 100644 --- a/docs/cli-reference/create.md +++ b/docs/cli-reference/create.md @@ -53,10 +53,9 @@ bd create [title] [flags] --silent Output only the issue ID (for scripting) --skills string Required skills for this issue --spec-id string Link to specification document - -s, --status string Initial status --stdin Read description from stdin (alias for --body-file -) --title string Issue title (alternative to positional argument) - -t, --type string Issue type (bug|feature|task|epic|chore|decision|spike|story|milestone); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task") + -t, --type string Issue type (bug|feature|task|epic|chore|decision); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task") --validate Validate description contains required sections for issue type --waits-for string Spawner issue ID to wait for (creates waits-for dependency for fanout gate) --waits-for-gate string Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children") diff --git a/docs/cli-reference/defer.md b/docs/cli-reference/defer.md index ddea99c3c..5be75dc84 100644 --- a/docs/cli-reference/defer.md +++ b/docs/cli-reference/defer.md @@ -1,6 +1,6 @@ --- title: "bd defer" -description: "Defer one or more issues for later" +description: "Defer issues to put them on ice for later." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/delete.md b/docs/cli-reference/delete.md index 07e5b0b68..aa59ca5d7 100644 --- a/docs/cli-reference/delete.md +++ b/docs/cli-reference/delete.md @@ -1,6 +1,6 @@ --- title: "bd delete" -description: "Delete one or more issues and clean up references" +description: "Delete one or more issues and clean up all references to them." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/dep.md b/docs/cli-reference/dep.md index dc6498c1c..c5e859318 100644 --- a/docs/cli-reference/dep.md +++ b/docs/cli-reference/dep.md @@ -1,6 +1,6 @@ --- title: "bd dep" -description: "Manage dependencies" +description: "Manage dependencies between issues." --- {/* AUTO-GENERATED: do not edit manually */} @@ -21,7 +21,6 @@ Examples: ``` bd dep [issue-id] [flags] -bd dep [command] ``` **Flags:** diff --git a/docs/cli-reference/diff.md b/docs/cli-reference/diff.md index 603a9321b..7920de832 100644 --- a/docs/cli-reference/diff.md +++ b/docs/cli-reference/diff.md @@ -1,6 +1,6 @@ --- title: "bd diff" -description: "Show changes between two commits or branches" +description: "Show the differences in issues between two commits or branches." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/doctor.md b/docs/cli-reference/doctor.md index be6a38e97..a95098089 100644 --- a/docs/cli-reference/doctor.md +++ b/docs/cli-reference/doctor.md @@ -1,6 +1,6 @@ --- title: "bd doctor" -description: "Check and fix beads installation health (start here)" +description: "Sanity check the beads installation for the current directory or specified path." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/dolt.md b/docs/cli-reference/dolt.md index b331113f5..93f50c450 100644 --- a/docs/cli-reference/dolt.md +++ b/docs/cli-reference/dolt.md @@ -1,6 +1,6 @@ --- title: "bd dolt" -description: "Configure Dolt database settings" +description: "Configure and manage Dolt database settings and server lifecycle." --- {/* AUTO-GENERATED: do not edit manually */} @@ -50,7 +50,7 @@ Examples: bd dolt test ``` -bd dolt [command] +bd dolt [flags] ``` ## bd dolt clean-databases @@ -58,7 +58,7 @@ bd dolt [command] Identify and drop leftover test and agent databases that accumulate on the shared Dolt server from interrupted test runs and terminated agents. -Stale database prefixes: testdb_*, beads_test*, beads_pt*, beads_vr*, doctest_*, doctortest_*, benchdb_* +Stale database prefixes: testdb_*, doctest_*, doctortest_*, beads_pt*, beads_vr*, beads_t* These waste server memory and can degrade performance under concurrent load. Use --dry-run to see what would be dropped without actually dropping. @@ -169,7 +169,7 @@ Subcommands: remove <name> Remove a remote ``` -bd dolt remote [command] +bd dolt remote [flags] ``` ### bd dolt remote add @@ -180,12 +180,6 @@ Add a Dolt remote bd dolt remote add [flags] ``` -**Flags:** - -``` - --allow-git-origin Allow adding a Dolt remote whose URL matches the git origin (proceed with a warning instead of aborting) -``` - ### bd dolt remote list List configured Dolt remotes @@ -260,10 +254,10 @@ Show the status of the Dolt engine for the current project. In embedded mode, reports that the Dolt engine runs in-process and shows the on-disk data directory. For beads-managed (local) servers, displays PID, port, and data directory from the local PID file. For externally- -managed servers — a shared server (dolt.shared-server: true), a remote -dolt_server_host, or a local server managed outside bd (dolt.auto-start: -false, e.g. an orchestrator-shared sql-server) — pings the configured -endpoint via SQL and reports reachability, server version, and database. +managed servers — either a remote dolt_server_host or a local server +managed outside bd (dolt.auto-start: false, e.g. an orchestrator-shared +sql-server) — pings the configured endpoint via SQL and reports +reachability, server version, and database. ``` bd dolt status [flags] diff --git a/docs/cli-reference/duplicate.md b/docs/cli-reference/duplicate.md index a21ba1c16..12ec81ef9 100644 --- a/docs/cli-reference/duplicate.md +++ b/docs/cli-reference/duplicate.md @@ -1,6 +1,6 @@ --- title: "bd duplicate" -description: "Mark an issue as a duplicate of another" +description: "Mark an issue as a duplicate of a canonical issue." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/duplicates.md b/docs/cli-reference/duplicates.md index 4b917e357..c1f984c84 100644 --- a/docs/cli-reference/duplicates.md +++ b/docs/cli-reference/duplicates.md @@ -1,6 +1,6 @@ --- title: "bd duplicates" -description: "Find and optionally merge duplicate issues" +description: "Find issues with identical content (title, description, design, acceptance criteria)." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/edit.md b/docs/cli-reference/edit.md index 30ef1cc65..b4db88d57 100644 --- a/docs/cli-reference/edit.md +++ b/docs/cli-reference/edit.md @@ -1,6 +1,6 @@ --- title: "bd edit" -description: "Edit an issue field in $EDITOR" +description: "Edit an issue field using your configured $EDITOR." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/epic.md b/docs/cli-reference/epic.md index d91337256..9fe61582e 100644 --- a/docs/cli-reference/epic.md +++ b/docs/cli-reference/epic.md @@ -10,7 +10,7 @@ Generated from `bd help --doc epic`. Epic management commands ``` -bd epic [command] +bd epic [flags] ``` ## bd epic close-eligible diff --git a/docs/cli-reference/export.md b/docs/cli-reference/export.md index 8fd0bf446..8925989e4 100644 --- a/docs/cli-reference/export.md +++ b/docs/cli-reference/export.md @@ -1,6 +1,6 @@ --- title: "bd export" -description: "Export issues to JSONL format" +description: "Export all issues to JSONL (newline-delimited JSON) format." --- {/* AUTO-GENERATED: do not edit manually */} @@ -39,11 +39,9 @@ bd export [flags] **Flags:** ``` - --all Include all records (infra, templates, gates, memories) - --exclude-owner stringArray Exclude issues created by this identity (repeatable; also reads export.exclude_owners config) - --include-infra Include infrastructure beads (agents, roles, messages) - --include-memories Include persistent memories (from 'bd remember') in the export - -o, --output string Output file path (default: stdout) - --scrub Exclude test/pollution records - --verbose Print filtered issue count when owners are excluded + --all Include all records (infra, templates, gates, memories) + --include-infra Include infrastructure beads (agents, roles, messages) + --include-memories Include persistent memories (from 'bd remember') in the export + -o, --output string Output file path (default: stdout) + --scrub Exclude test/pollution records ``` diff --git a/docs/cli-reference/federation.md b/docs/cli-reference/federation.md index 80316fa6c..b11a4cada 100644 --- a/docs/cli-reference/federation.md +++ b/docs/cli-reference/federation.md @@ -1,6 +1,6 @@ --- title: "bd federation" -description: "Manage peer-to-peer federation (requires CGO)" +description: "Federation commands require CGO and the Dolt storage backend." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/find-duplicates.md b/docs/cli-reference/find-duplicates.md index 92fc123e4..caf55909b 100644 --- a/docs/cli-reference/find-duplicates.md +++ b/docs/cli-reference/find-duplicates.md @@ -1,6 +1,6 @@ --- title: "bd find-duplicates" -description: "Find semantically similar issues using text analysis or AI" +description: "Find issues that are semantically similar but not exact duplicates." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/flatten.md b/docs/cli-reference/flatten.md index a82290149..934df2ec7 100644 --- a/docs/cli-reference/flatten.md +++ b/docs/cli-reference/flatten.md @@ -1,6 +1,6 @@ --- title: "bd flatten" -description: "Squash all Dolt history into a single commit" +description: "Nuclear option: squash ALL Dolt commit history into a single commit." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/forget.md b/docs/cli-reference/forget.md index ced7663e8..28bc7fed7 100644 --- a/docs/cli-reference/forget.md +++ b/docs/cli-reference/forget.md @@ -1,6 +1,6 @@ --- title: "bd forget" -description: "Remove a persistent memory" +description: "Remove a memory by its key." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/formula.md b/docs/cli-reference/formula.md index 49517015b..bdb88ed11 100644 --- a/docs/cli-reference/formula.md +++ b/docs/cli-reference/formula.md @@ -1,6 +1,6 @@ --- title: "bd formula" -description: "Manage workflow formulas" +description: "Manage workflow formulas - the source layer for molecule templates." --- {/* AUTO-GENERATED: do not edit manually */} @@ -19,19 +19,11 @@ Search paths (in order): 4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set) Commands: - list List available formulas from all search paths - show Show formula details, steps, and composition rules - schema Show the formula schema index (alias: primitives) - -Discovering primitives: - bd formula schema # list every declared formula struct - bd formula schema loop # show LoopSpec fields, types, and tags - bd formula primitives gate # alias; same handler as 'schema' - examples/formulas/primitives/ # curated, smoke-tested wired fixtures - docs/workflows/formulas.md # narrative reference + list List available formulas from all search paths + show Show formula details, steps, and composition rules ``` -bd formula [command] +bd formula [flags] ``` ## bd formula convert @@ -77,9 +69,6 @@ Search paths (in order of priority): Formulas in earlier paths shadow those with the same name in later paths. -To list the declared formula schema structs an agent can write inside a .formula.toml, -use 'bd formula schema' (alias: 'bd formula primitives'). - Examples: bd formula list bd formula list --json @@ -96,30 +85,6 @@ bd formula list [flags] --type string Filter by type (workflow, expansion, aspect, convoy) ``` -## bd formula schema - -Show the formula schema index: every exported struct declared -in a .formula.toml/.formula.json, with field names, types, and tags. - -The index is generated from internal/formula/types.go via go:generate; the -struct definitions are the source of truth, so this list cannot drift. It is -structural reference, not proof that every declared runtime behavior is wired. - -Examples: - bd formula schema # list every declared schema struct - bd formula schema loop # show LoopSpec fields - bd formula primitives gate # alias; shows Gate fields - bd formula schema --json # machine-readable index - -Curated smoke-tested fixtures for wired primitives live in -examples/formulas/primitives/ (with a smoke harness that proves they work). - -``` -bd formula schema [primitive] [flags] -``` - -**Aliases:** primitives - ## bd formula show Show detailed information about a formula. @@ -131,9 +96,6 @@ Displays: - Composition rules (extends, aspects, expansions) - Bond points for external composition -To inspect the structure of an individual primitive (e.g. LoopSpec, Gate) -rather than a user-authored formula, use 'bd formula schema <primitive>'. - Examples: bd formula show shiny bd formula show rule-of-five diff --git a/docs/cli-reference/gate.md b/docs/cli-reference/gate.md index 26bffdecc..925626227 100644 --- a/docs/cli-reference/gate.md +++ b/docs/cli-reference/gate.md @@ -1,6 +1,6 @@ --- title: "bd gate" -description: "Manage async coordination gates" +description: "Gates are async wait conditions that block workflow steps." --- {/* AUTO-GENERATED: do not edit manually */} @@ -17,11 +17,9 @@ Gate types: timer - Expires after timeout (Phase 2) gh:run - Waits for GitHub workflow (Phase 3) gh:pr - Waits for PR merge (Phase 3) - bead - Waits for another bead to close (Phase 4) + bead - Waits for cross-rig bead to close (Phase 4) -For bead gates, await_id is a bead ID in this rig's database (e.g., "bd-abc123"). -The historical cross-rig form <rig>:<bead-id> can no longer be evaluated -(multi-rig routing removed) and stays pending until resolved manually. +For bead gates, await_id format is <rig>:<bead-id> (e.g., "other-project:op-abc123"). Examples: bd gate list # Show all open gates @@ -31,7 +29,7 @@ Examples: bd gate resolve <id> # Close a gate manually ``` -bd gate [command] +bd gate [flags] ``` ## bd gate add-waiter @@ -163,16 +161,12 @@ bd gate discover [flags] ## bd gate list -List gate issues. - -With no argument, lists all gate issues in the current beads database. -With an [issue-id] argument, lists ONLY the gates that block that issue -(its own dependency gates) — not every gate in the database. +List all gate issues in the current beads database. By default, shows only open gates. Use --all to include closed gates. ``` -bd gate list [issue-id] [flags] +bd gate list [flags] ``` **Flags:** diff --git a/docs/cli-reference/gc.md b/docs/cli-reference/gc.md index 1c61dcfd7..2b0afd152 100644 --- a/docs/cli-reference/gc.md +++ b/docs/cli-reference/gc.md @@ -1,6 +1,6 @@ --- title: "bd gc" -description: "Garbage collect: decay old issues, compact Dolt commits, run Dolt GC" +description: "Full lifecycle garbage collection for standalone Beads databases." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/github.md b/docs/cli-reference/github.md index aaace89c0..bbc58cf48 100644 --- a/docs/cli-reference/github.md +++ b/docs/cli-reference/github.md @@ -1,6 +1,6 @@ --- title: "bd github" -description: "GitHub integration commands" +description: "Commands for syncing issues between beads and GitHub." --- {/* AUTO-GENERATED: do not edit manually */} @@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables: github.url / GITHUB_API_URL - Custom API URL (GitHub Enterprise) ``` -bd github [command] +bd github [flags] ``` ## bd github pull diff --git a/docs/cli-reference/gitlab.md b/docs/cli-reference/gitlab.md index 3697ba2b9..307a7fd09 100644 --- a/docs/cli-reference/gitlab.md +++ b/docs/cli-reference/gitlab.md @@ -1,6 +1,6 @@ --- title: "bd gitlab" -description: "GitLab integration commands" +description: "Commands for syncing issues between beads and GitLab." --- {/* AUTO-GENERATED: do not edit manually */} @@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables: gitlab.default_project_id / GITLAB_DEFAULT_PROJECT_ID - Project for creating issues in group mode ``` -bd gitlab [command] +bd gitlab [flags] ``` ## bd gitlab projects diff --git a/docs/cli-reference/graph.md b/docs/cli-reference/graph.md index a939a92d3..549727fd9 100644 --- a/docs/cli-reference/graph.md +++ b/docs/cli-reference/graph.md @@ -1,6 +1,6 @@ --- title: "bd graph" -description: "Display issue dependency graph" +description: "Display a visualization of an issue's dependency graph." --- {/* AUTO-GENERATED: do not edit manually */} @@ -13,7 +13,6 @@ For epics, shows all children and their dependencies. For regular issues, shows the issue and its direct dependencies. With --all, shows all open issues grouped by connected component. -With --open, filters to only open/actionable issues (compact layer format). Display formats: (default) DAG with columns and box-drawing edges (terminal-native) @@ -21,7 +20,6 @@ Display formats: --compact Tree format, one line per issue, more scannable --dot Graphviz DOT format (pipe to dot -Tsvg > graph.svg) --html Self-contained interactive HTML with D3.js visualization - --open Open issues only, compact layers (LLM-friendly) The graph shows execution order: - Layer 0 / leftmost = no dependencies (can start immediately) @@ -37,12 +35,9 @@ Examples: bd graph --dot issue-id | dot -Tpng > graph.png # PNG via Graphviz bd graph --html issue-id > graph.html # Interactive browser view bd graph --all --html > all.html # All issues, interactive - bd graph --open issue-id # Open issues only, layered by blocking order - bd graph --all --open # All open issues, compact layers ``` bd graph [issue-id] [flags] -bd graph [command] ``` **Flags:** @@ -53,7 +48,6 @@ bd graph [command] --compact Tree format, one line per issue, more scannable --dot Output Graphviz DOT format (pipe to: dot -Tsvg > graph.svg) --html Output self-contained interactive HTML (redirect to file) - --open Show only open issues (filters out closed/deferred), forces compact layer format ``` ## bd graph check diff --git a/docs/cli-reference/history.md b/docs/cli-reference/history.md index c7e455ea6..364a5d19d 100644 --- a/docs/cli-reference/history.md +++ b/docs/cli-reference/history.md @@ -1,6 +1,6 @@ --- title: "bd history" -description: "Show version history for an issue" +description: "Show the complete version history of an issue, including all commits" --- {/* AUTO-GENERATED: do not edit manually */} @@ -13,7 +13,6 @@ where the issue was modified. Examples: bd history bd-123 # Show all history for issue bd-123 bd history bd-123 --limit 5 # Show last 5 changes - bd history bd-123 --events # Show database audit events ``` bd history [flags] @@ -22,6 +21,5 @@ bd history [flags] **Flags:** ``` - --events Show database audit events instead of commit snapshots --limit int Limit number of history entries (0 = all) ``` diff --git a/docs/cli-reference/hooks.md b/docs/cli-reference/hooks.md index 148d9a66d..6b9f39bdd 100644 --- a/docs/cli-reference/hooks.md +++ b/docs/cli-reference/hooks.md @@ -1,6 +1,6 @@ --- title: "bd hooks" -description: "Manage git hooks for beads integration" +description: "Install, uninstall, or list git hooks for beads integration." --- {/* AUTO-GENERATED: do not edit manually */} @@ -17,7 +17,7 @@ The hooks provide: - prepare-commit-msg: Add agent identity trailers for forensics ``` -bd hooks [command] +bd hooks [flags] ``` ## bd hooks install diff --git a/docs/cli-reference/human.md b/docs/cli-reference/human.md index 949dcf47d..30291f7ca 100644 --- a/docs/cli-reference/human.md +++ b/docs/cli-reference/human.md @@ -1,6 +1,6 @@ --- title: "bd human" -description: "Show essential commands for human users" +description: "Display a focused help menu showing only the most common commands." --- {/* AUTO-GENERATED: do not edit manually */} @@ -22,7 +22,6 @@ SUBCOMMANDS: ``` bd human [flags] -bd human [command] ``` ## bd human dismiss diff --git a/docs/cli-reference/import.md b/docs/cli-reference/import.md index 09269f50e..8f6df553a 100644 --- a/docs/cli-reference/import.md +++ b/docs/cli-reference/import.md @@ -1,6 +1,6 @@ --- title: "bd import" -description: "Import issues from a JSONL file or stdin into the database" +description: "Import issues from a JSONL file (newline-delimited JSON) into the database." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/index.md b/docs/cli-reference/index.md index 94b1267a5..5c9548092 100644 --- a/docs/cli-reference/index.md +++ b/docs/cli-reference/index.md @@ -7,32 +7,12 @@ description: Generated reference for every bd command Generated from `bd help --docs-root`. -This reference covers all 112 live top-level `bd` commands. Regenerate it with: +This reference covers all 108 live top-level `bd` commands. Regenerate it with: ```bash ./scripts/generate-cli-docs.sh ``` -## Global Flags - -These flags apply to all commands: - -``` - --actor string Actor name for audit trail (default: $BEADS_ACTOR, git user.name, $USER) - --db string Database path (default: auto-discover .beads/*.db) - -C, --directory string Change to this directory before running the command (like git -C) - --dolt-auto-commit string Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit - --global Use the global shared-server database (beads_global) - --ignore-schema-skew Proceed despite forward schema drift (some queries may fail) - --json Output in JSON format - --no-color Disable color output (also: NO_COLOR=1 or CLICOLOR=0) - --profile Generate CPU profile for performance analysis - -q, --quiet Suppress non-essential output (errors only) - --readonly Read-only mode: block write operations (for worker sandboxes) - --sandbox Sandbox mode: disables Dolt auto-push - -v, --verbose Enable verbose/debug output -``` - ## Commands - [`bd admin`](/cli-reference/admin) @@ -77,7 +57,6 @@ These flags apply to all commands: - [`bd github`](/cli-reference/github) - [`bd gitlab`](/cli-reference/gitlab) - [`bd graph`](/cli-reference/graph) -- [`bd heartbeat`](/cli-reference/heartbeat) - [`bd history`](/cli-reference/history) - [`bd hooks`](/cli-reference/hooks) - [`bd human`](/cli-reference/human) @@ -97,7 +76,6 @@ These flags apply to all commands: - [`bd merge-slot`](/cli-reference/merge-slot) - [`bd metrics`](/cli-reference/metrics) - [`bd migrate`](/cli-reference/migrate) -- [`bd migrate-personal`](/cli-reference/migrate-personal) - [`bd mol`](/cli-reference/mol) - [`bd note`](/cli-reference/note) - [`bd notion`](/cli-reference/notion) @@ -115,7 +93,6 @@ These flags apply to all commands: - [`bd quickstart`](/cli-reference/quickstart) - [`bd ready`](/cli-reference/ready) - [`bd recall`](/cli-reference/recall) -- [`bd reclaim`](/cli-reference/reclaim) - [`bd recompute-blocked`](/cli-reference/recompute-blocked) - [`bd remember`](/cli-reference/remember) - [`bd rename`](/cli-reference/rename) @@ -139,7 +116,6 @@ These flags apply to all commands: - [`bd tag`](/cli-reference/tag) - [`bd todo`](/cli-reference/todo) - [`bd types`](/cli-reference/types) -- [`bd unclaim`](/cli-reference/unclaim) - [`bd undefer`](/cli-reference/undefer) - [`bd update`](/cli-reference/update) - [`bd upgrade`](/cli-reference/upgrade) diff --git a/docs/cli-reference/info.md b/docs/cli-reference/info.md index e6abb82eb..8ad43af2d 100644 --- a/docs/cli-reference/info.md +++ b/docs/cli-reference/info.md @@ -1,6 +1,6 @@ --- title: "bd info" -description: "Show database information" +description: "Display information about the current database." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/init-safety.md b/docs/cli-reference/init-safety.md index df3b3f349..80ea0db9d 100644 --- a/docs/cli-reference/init-safety.md +++ b/docs/cli-reference/init-safety.md @@ -1,6 +1,6 @@ --- title: "bd init-safety" -description: "Explain bd init flag semantics and the destroy-token format" +description: "bd init flag safety contract." --- {/* AUTO-GENERATED: do not edit manually */} @@ -59,7 +59,7 @@ DESTROY-TOKEN (non-interactive only) In interactive (TTY) mode you confirm via a typed prompt instead. The token is not echoed by bd's runtime error messages — this is a deliberate guard against pattern-matched one-liners (see - engdocs/adr/0002-init-safety-invariants.md). + docs/adr/0002-init-safety-invariants.md). EXIT CODES @@ -71,7 +71,7 @@ EXIT CODES RECOVERY - If you hit a refusal, see docs/recovery/init-safety.md for step-by-step recovery + If you hit a refusal, see docs/RECOVERY.md for step-by-step recovery playbooks for each exit code. diff --git a/docs/cli-reference/init.md b/docs/cli-reference/init.md index 31242baec..3a474ba78 100644 --- a/docs/cli-reference/init.md +++ b/docs/cli-reference/init.md @@ -1,6 +1,6 @@ --- title: "bd init" -description: "Initialize bd in the current directory" +description: "Initialize bd in the current directory by creating a .beads/ directory" --- {/* AUTO-GENERATED: do not edit manually */} @@ -8,11 +8,10 @@ description: "Initialize bd in the current directory" Generated from `bd help --doc init`. Initialize bd in the current directory by creating a .beads/ directory -and its storage (a Dolt database by default). Optionally specify a custom issue prefix. +and Dolt database. Optionally specify a custom issue prefix. -Dolt is the default backend and the only one with version control (history, -branching, sync). Select an alternative with --backend=<postgres|mysql|sqlite>; -see docs/architecture/storage-backends.md for the trade-offs and setup. +Dolt is the default (and only supported) storage backend. The legacy SQLite +backend has been removed. Use --backend=sqlite to see migration instructions. Use --database to specify an existing server database name, overriding the default prefix-based naming. This is useful when an external tool (e.g. an orchestrator) @@ -49,56 +48,46 @@ bd init [flags] **Flags:** ``` - --agents-file string Custom filename for agent instructions (default: AGENTS.md) - --agents-profile string AGENTS.md profile: 'minimal' (default, pointer to bd prime) or 'full' (complete command reference) - --agents-template string Path to custom AGENTS.md template (overrides embedded default) - --backend string Storage backend: dolt (default), postgres, mysql, or sqlite. See docs/architecture/storage-backends.md. - --contributor Run OSS contributor setup wizard - --database string Use existing server database name (overrides prefix-based naming) - --debug Run the managed Dolt sql-server with --loglevel=debug and CPU profiling (--prof cpu). Persisted to config.yaml as dolt.debug. No effect on externally-managed servers. - --destroy-token string Explicit confirmation token for destructive re-init in non-interactive mode (format: 'DESTROY-') - --discard-remote Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'. - --external Server is externally managed (skip server startup); use with --shared-server or --server - --force Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety'). - --from-jsonl Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement - --init-if-missing If the workspace is already initialized, skip init and exit 0 instead of failing (idempotent init for scaffolds) - --mysql-database string MySQL database for this workspace (with --backend=mysql; MySQL's isolation unit) - --mysql-url string MySQL server DSN (with --backend=mysql), e.g. user:pass@tcp(host:3306)/ . A password may be included for init but is never persisted; set BEADS_MYSQL_PASSWORD for later commands. Falls back to BEADS_MYSQL_URL. - --non-interactive Skip all interactive prompts (auto-detected in CI or non-TTY environments) - --pg-schema string Postgres schema for this workspace's tables (with --backend=postgres; provides search_path isolation) - --pg-url string Postgres connection URL (with --backend=postgres). A password may be included for init but is never persisted; set BEADS_PG_PASSWORD for later commands. Falls back to BEADS_POSTGRES_URL. - -p, --prefix string Issue prefix (default: current directory name) - --proxied-server [EXPERIMENTAL] Use a per-workspace proxied dolt sql-server (proxy + child dolt) rooted at .beads/dolt - --proxied-server-config-path string [EXPERIMENTAL] Absolute path to an existing dolt sql-server YAML config (proxied-server mode only). When set, bd uses this file instead of auto-generating one. Relative paths are rejected. - --proxied-server-external-host string [EXPERIMENTAL] Hostname or IP of an externally-managed dolt sql-server the proxy should front (proxied-server mode only). Mutually exclusive with --proxied-server-external-socket-path. - --proxied-server-external-keep-alive duration [EXPERIMENTAL] TCP keepalive period for the proxy→external connection. Zero uses the package default (30s). - --proxied-server-external-port int [EXPERIMENTAL] TCP port of the externally-managed dolt sql-server (proxied-server mode only). Required when --proxied-server-external-host is set. - --proxied-server-external-socket-path string [EXPERIMENTAL] Absolute unix socket path of the externally-managed dolt sql-server (proxied-server mode only). Mutually exclusive with --proxied-server-external-host. Relative paths are rejected. - --proxied-server-external-tls [EXPERIMENTAL] Require TLS when connecting to the externally-managed dolt sql-server (proxied-server mode only). - --proxied-server-external-tls-ca-cert-path string [EXPERIMENTAL] Absolute path to a CA certificate (PEM) used to verify the externally-managed dolt sql-server. Empty uses the system trust store. Relative paths are rejected. - --proxied-server-external-tls-cert-path string [EXPERIMENTAL] Absolute path to a client TLS certificate (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-key-path. Relative paths are rejected. - --proxied-server-external-tls-key-path string [EXPERIMENTAL] Absolute path to the client TLS private key (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-cert-path. Relative paths are rejected. - --proxied-server-external-tls-server-name string [EXPERIMENTAL] Server name to verify in the external dolt sql-server's TLS certificate. Defaults to the external host. Required with a unix socket unless --proxied-server-external-tls-skip-verify is set. - --proxied-server-external-tls-skip-verify [EXPERIMENTAL] Skip TLS certificate verification for the external dolt sql-server. Insecure; testing only. - --proxied-server-external-user string [EXPERIMENTAL] MySQL user for the externally-managed dolt sql-server (proxied-server mode only). Defaults to "root" when empty. Password is read at runtime from $BEADS_PROXIED_SERVER_EXTERNAL_PASSWORD and is never persisted to disk. - --proxied-server-idle-timeout duration [EXPERIMENTAL] Idle duration after which the proxy shuts down its loopback listener and backend (proxied-server mode only). Omit for the built-in default (30s); 0 keeps the proxy and backend alive indefinitely; a positive value sets the window. - --proxied-server-log-path string [EXPERIMENTAL] Absolute path to the proxied dolt sql-server log file (proxied-server mode only). Default: /dolt/server.log. Relative paths are rejected. - --proxied-server-port int [EXPERIMENTAL] Fixed TCP port for the proxy's loopback listener (proxied-server mode only). Default 0 = an OS-assigned free port. Startup fails if the port is already in use. - --proxied-server-root-path string [EXPERIMENTAL] Absolute directory holding the proxied dolt sql-server's lockfiles, pidfiles, and child .dolt repository (proxied-server mode only). Default: /dolt. May not exist yet — bd will create it. Relative paths are rejected. - -q, --quiet Suppress output (quiet mode) - --reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote. - --remote string Dolt remote URL to clone from and persist as sync.remote - --role string Set beads role without prompting: "maintainer" or "contributor" - --server Use external dolt sql-server instead of embedded engine - --server-host string Dolt server host (default: 127.0.0.1) - --server-port int Dolt server port (default: 3307) - --server-socket string Unix domain socket path (overrides host/port) - --server-user string Dolt server MySQL user (default: root) - --setup-exclude Configure .git/info/exclude to keep beads files local (for forks) - --shared-server Enable shared Dolt server mode (all projects share one server at ~/.beads/shared-server/) - --skip-agents Skip AGENTS.md and Claude/Codex/Cursor setup generation - --skip-hooks Skip git hooks installation - --sqlite-path string SQLite database file (with --backend=sqlite; relative to the beads dir, default beads.db) - --stealth Enable stealth mode: global gitattributes and gitignore, no local repo tracking - --team Run team workflow setup wizard + --agents-file string Custom filename for agent instructions (default: AGENTS.md) + --agents-profile string AGENTS.md profile: 'minimal' (default, pointer to bd prime) or 'full' (complete command reference) + --agents-template string Path to custom AGENTS.md template (overrides embedded default) + --backend string Storage backend (default: dolt). --backend=sqlite prints deprecation notice. + --contributor Run OSS contributor setup wizard + --database string Use existing server database name (overrides prefix-based naming) + --debug Run the managed Dolt sql-server with --loglevel=debug and CPU profiling (--prof cpu). Persisted to config.yaml as dolt.debug. No effect on externally-managed servers. + --destroy-token string Explicit confirmation token for destructive re-init in non-interactive mode (format: 'DESTROY-') + --discard-remote Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'. + --external Server is externally managed (skip server startup); use with --shared-server or --server + --force Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety'). + --from-jsonl Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement + --init-if-missing If the workspace is already initialized, skip init and exit 0 instead of failing (idempotent init for scaffolds) + --non-interactive Skip all interactive prompts (auto-detected in CI or non-TTY environments) + -p, --prefix string Issue prefix (default: current directory name) + --proxied-server [EXPERIMENTAL] Use a per-workspace proxied dolt sql-server (proxy + child dolt) rooted at .beads/proxieddb + --proxied-server-config-path string [EXPERIMENTAL] Absolute path to an existing dolt sql-server YAML config (proxied-server mode only). When set, bd uses this file instead of auto-generating one. Relative paths are rejected. + --proxied-server-external-host string [EXPERIMENTAL] Hostname or IP of an externally-managed dolt sql-server the proxy should front (proxied-server mode only). Mutually exclusive with --proxied-server-external-socket-path. + --proxied-server-external-keep-alive duration [EXPERIMENTAL] TCP keepalive period for the proxy→external connection. Zero uses the package default (30s). + --proxied-server-external-port int [EXPERIMENTAL] TCP port of the externally-managed dolt sql-server (proxied-server mode only). Required when --proxied-server-external-host is set. + --proxied-server-external-socket-path string [EXPERIMENTAL] Absolute unix socket path of the externally-managed dolt sql-server (proxied-server mode only). Mutually exclusive with --proxied-server-external-host. Relative paths are rejected. + --proxied-server-external-tls [EXPERIMENTAL] Require TLS when connecting to the externally-managed dolt sql-server (proxied-server mode only). + --proxied-server-external-tls-cert-path string [EXPERIMENTAL] Absolute path to a client TLS certificate (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-key-path. Relative paths are rejected. + --proxied-server-external-tls-key-path string [EXPERIMENTAL] Absolute path to the client TLS private key (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-cert-path. Relative paths are rejected. + --proxied-server-external-user string [EXPERIMENTAL] MySQL user for the externally-managed dolt sql-server (proxied-server mode only). Defaults to "root" when empty. Password is read at runtime from $BEADS_PROXIED_SERVER_EXTERNAL_PASSWORD and is never persisted to disk. + --proxied-server-log-path string [EXPERIMENTAL] Absolute path to the proxied dolt sql-server log file (proxied-server mode only). Default: /proxieddb/server.log. Relative paths are rejected. + --proxied-server-root-path string [EXPERIMENTAL] Absolute directory holding the proxied dolt sql-server's lockfiles, pidfiles, and child .dolt repository (proxied-server mode only). Default: /proxieddb. May not exist yet — bd will create it. Relative paths are rejected. + -q, --quiet Suppress output (quiet mode) + --reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote. + --remote string Dolt remote URL to clone from and persist as sync.remote + --role string Set beads role without prompting: "maintainer" or "contributor" + --server Use external dolt sql-server instead of embedded engine + --server-host string Dolt server host (default: 127.0.0.1) + --server-port int Dolt server port (default: 3307) + --server-socket string Unix domain socket path (overrides host/port) + --server-user string Dolt server MySQL user (default: root) + --setup-exclude Configure .git/info/exclude to keep beads files local (for forks) + --shared-server Enable shared Dolt server mode (all projects share one server at ~/.beads/shared-server/) + --skip-agents Skip AGENTS.md and Claude/Codex setup generation + --skip-hooks Skip git hooks installation + --stealth Enable stealth mode: global gitattributes and gitignore, no local repo tracking + --team Run team workflow setup wizard ``` diff --git a/docs/cli-reference/jira.md b/docs/cli-reference/jira.md index d069f7d14..166748a1e 100644 --- a/docs/cli-reference/jira.md +++ b/docs/cli-reference/jira.md @@ -1,6 +1,6 @@ --- title: "bd jira" -description: "Jira integration commands" +description: "Synchronize issues between beads and Jira." --- {/* AUTO-GENERATED: do not edit manually */} @@ -31,7 +31,7 @@ Examples: bd jira status # Show sync status ``` -bd jira [command] +bd jira [flags] ``` ## bd jira pull diff --git a/docs/cli-reference/kv.md b/docs/cli-reference/kv.md index 502d8b6af..b1421e984 100644 --- a/docs/cli-reference/kv.md +++ b/docs/cli-reference/kv.md @@ -1,6 +1,6 @@ --- title: "bd kv" -description: "Key-value store commands" +description: "Commands for working with the beads key-value store." --- {/* AUTO-GENERATED: do not edit manually */} @@ -19,7 +19,7 @@ Examples: bd kv list # List all key-value pairs ``` -bd kv [command] +bd kv [flags] ``` ## bd kv clear diff --git a/docs/cli-reference/label.md b/docs/cli-reference/label.md index 32a3ecae0..34fdf95c8 100644 --- a/docs/cli-reference/label.md +++ b/docs/cli-reference/label.md @@ -10,15 +10,15 @@ Generated from `bd help --doc label`. Manage issue labels ``` -bd label [command] +bd label [flags] ``` ## bd label add -Add labels to issues. Issue IDs come first; the final argument is the label. Pass multiple labels comma-separated: bd label add bd-123 label1,label2 +Add a label to one or more issues ``` -bd label add [issue-id...] [label[,label...]] [flags] +bd label add [issue-id...] [label] [flags] ``` ## bd label list @@ -47,8 +47,8 @@ bd label propagate [parent-id] [label] [flags] ## bd label remove -Remove labels from issues. Issue IDs come first; the final argument is the label. Pass multiple labels comma-separated: bd label remove bd-123 label1,label2 +Remove a label from one or more issues ``` -bd label remove [issue-id...] [label[,label...]] [flags] +bd label remove [issue-id...] [label] [flags] ``` diff --git a/docs/cli-reference/linear.md b/docs/cli-reference/linear.md index 9445a8715..9f7310023 100644 --- a/docs/cli-reference/linear.md +++ b/docs/cli-reference/linear.md @@ -1,6 +1,6 @@ --- title: "bd linear" -description: "Linear integration commands" +description: "Synchronize issues between beads and Linear." --- {/* AUTO-GENERATED: do not edit manually */} @@ -70,7 +70,7 @@ Examples: bd linear status # Show sync status ``` -bd linear [command] +bd linear [flags] ``` ## bd linear pull @@ -151,18 +151,6 @@ Type Filtering (--push only): --parent TICKET Only push this ticket and its descendants --relations Import Linear relations as bd dependencies on pull -Persistent push-direction ID filters (workflow artifacts, sandbox beads, etc.): - bd config set linear.exclude_id_prefix "hw-mol-" - bd config set linear.exclude_id_patterns "-wisp-,sandbox-,scratch-" - - exclude_id_prefix is a single case-sensitive prefix on the bead ID. - exclude_id_patterns is a comma-separated list of case-sensitive substrings - (matched anywhere in the ID). Both are combined as a union: a bead - matching either rule is skipped from push (no create, no update). Beads - with an existing external_ref that NOW match are silently skipped on - future syncs; the Linear-side issue persists — archive/delete it manually - if desired. - Conflict Resolution: By default, newer timestamp wins. Override with: --prefer-local Always prefer local beads version diff --git a/docs/cli-reference/link.md b/docs/cli-reference/link.md index 3f35d0b35..6a63d60d1 100644 --- a/docs/cli-reference/link.md +++ b/docs/cli-reference/link.md @@ -1,6 +1,6 @@ --- title: "bd link" -description: "Link two issues with a dependency" +description: "Link two issues with a dependency." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/lint.md b/docs/cli-reference/lint.md index f2480cf39..7490a7fd7 100644 --- a/docs/cli-reference/lint.md +++ b/docs/cli-reference/lint.md @@ -1,6 +1,6 @@ --- title: "bd lint" -description: "Check issues for missing template sections" +description: "Check issues for missing recommended sections based on issue type." --- {/* AUTO-GENERATED: do not edit manually */} @@ -15,7 +15,7 @@ Section requirements by type: bug: Steps to Reproduce, Acceptance Criteria task: Acceptance Criteria feature: Acceptance Criteria - epic: Success Criteria (or Acceptance Criteria) + epic: Success Criteria chore: (none) Examples: @@ -34,5 +34,5 @@ bd lint [issue-id...] [flags] ``` -s, --status string Filter by status (default: open, use 'all' for all) - -t, --type string Filter by issue type (bug, task, feature, epic, decision, spike, story, chore, milestone) + -t, --type string Filter by issue type (bug, task, feature, epic) ``` diff --git a/docs/cli-reference/list.md b/docs/cli-reference/list.md index a46d3563c..d2d545722 100644 --- a/docs/cli-reference/list.md +++ b/docs/cli-reference/list.md @@ -31,8 +31,6 @@ bd list [flags] --empty-description Filter issues with empty or missing description --exclude-label strings Exclude issues that have ANY of these labels --exclude-type strings Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic) - --external-contains string Filter by external ref substring (case-insensitive) - --external-ref string Filter by exact external_ref value --flat Disable tree format and use legacy flat list output --format string Output format: 'digraph' (for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or Go template --has-metadata-key string Filter issues that have this metadata key set diff --git a/docs/cli-reference/mail.md b/docs/cli-reference/mail.md index e6d967135..eb0a16e0f 100644 --- a/docs/cli-reference/mail.md +++ b/docs/cli-reference/mail.md @@ -1,6 +1,6 @@ --- title: "bd mail" -description: "Delegate to mail provider (e.g., gt mail)" +description: "Delegates mail operations to an external mail provider." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/memories.md b/docs/cli-reference/memories.md index 43e2b5e8b..e37ba07ac 100644 --- a/docs/cli-reference/memories.md +++ b/docs/cli-reference/memories.md @@ -1,6 +1,6 @@ --- title: "bd memories" -description: "List or search persistent memories" +description: "List all memories, or search by keyword." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/merge-slot.md b/docs/cli-reference/merge-slot.md index dc23dab57..115f136ee 100644 --- a/docs/cli-reference/merge-slot.md +++ b/docs/cli-reference/merge-slot.md @@ -1,6 +1,6 @@ --- title: "bd merge-slot" -description: "Manage merge-slot gates for serialized conflict resolution" +description: "Merge-slot gates serialize conflict resolution in the merge queue." --- {/* AUTO-GENERATED: do not edit manually */} @@ -27,7 +27,7 @@ Examples: bd merge-slot release # Release the slot ``` -bd merge-slot [command] +bd merge-slot [flags] ``` ## bd merge-slot acquire diff --git a/docs/cli-reference/metrics.md b/docs/cli-reference/metrics.md index f53b4b3da..9a5892ed9 100644 --- a/docs/cli-reference/metrics.md +++ b/docs/cli-reference/metrics.md @@ -1,6 +1,6 @@ --- title: "bd metrics" -description: "Show or change anonymous usage-metrics settings" +description: "Show whether anonymous usage metrics are on, see exactly what is sent, and" --- {/* AUTO-GENERATED: do not edit manually */} @@ -22,7 +22,6 @@ any user-supplied text. ``` bd metrics [flags] -bd metrics [command] ``` ## bd metrics example diff --git a/docs/cli-reference/migrate.md b/docs/cli-reference/migrate.md index 1b5287996..e2fe396f9 100644 --- a/docs/cli-reference/migrate.md +++ b/docs/cli-reference/migrate.md @@ -1,6 +1,6 @@ --- title: "bd migrate" -description: "Database migration commands" +description: "Database migration and data transformation commands." --- {/* AUTO-GENERATED: do not edit manually */} @@ -12,125 +12,26 @@ Database migration and data transformation commands. Without subcommand, checks and updates database metadata to current version. Subcommands: - hooks Plan git hook migration to marker-managed format - issues Move issues between repositories - schema Apply pending schema migrations (idempotent) - sync Set up sync.branch workflow for multi-clone setups - from-server-to-proxied-server [EXPERIMENTAL] Switch server mode to proxied-server mode - from-proxied-server-to-server [EXPERIMENTAL] Switch proxied-server mode to server mode - from-shared-server-to-proxied-server [EXPERIMENTAL] Switch shared-server mode to proxied-server mode - from-proxied-server-to-shared-server [EXPERIMENTAL] Switch proxied-server mode to shared-server mode - -On a remote-backed database with pending schema migrations bd refuses to -migrate in place (#4259): migrating two clones independently forks the schema -so bd dolt pull can no longer merge — the break is silent and unrecoverable. -Use --force to confirm you are the single designated migrator, after which you -should publish the migrated schema with 'bd dolt push'. The env-var equivalent -BD_ALLOW_REMOTE_MIGRATE=1 remains supported for scripted/CI use. + hooks Plan git hook migration to marker-managed format + issues Move issues between repositories + schema Apply pending schema migrations (idempotent) + sync Set up sync.branch workflow for multi-clone setups ``` bd migrate [flags] -bd migrate [command] ``` **Flags:** ``` --dry-run Show what would be done without making changes - --force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1) --inspect Show migration plan and database state for AI agent analysis --json Output migration statistics in JSON format --update-repo-id Update repository ID (use after changing git remote) --yes Auto-confirm prompts ``` -## bd migrate from-proxied-server-to-server - -Switch a repo from proxied-server mode to server mode (bd init --server). - -Both modes root their dolt sql-server at the same .beads/dolt directory, so this -only rewrites .beads/metadata.json (dolt_mode) and removes the proxied-server -sidecar — no Dolt data is copied or moved. Stop the running proxy first with -'bd dolt stop'. - -Note: dolt_mode lives in the committed metadata.json, so this change propagates -to clones on the next push. - -``` -bd migrate from-proxied-server-to-server [flags] -``` - -**Flags:** - -``` - --dry-run Show what would be done without making changes -``` - -## bd migrate from-proxied-server-to-shared-server - -Switch a repo from proxied-server mode back to shared-server mode. - -Only applies to a proxied-server repo rooted at the shared dolt directory -(~/.beads/shared-server/dolt) — the reverse of from-shared-server-to-proxied-server. -This rewrites .beads/metadata.json (dolt_mode), re-enables dolt.shared-server, and -removes the proxied-server sidecar; no Dolt data is copied or moved. Stop the -running proxy first with 'bd dolt stop'. - -``` -bd migrate from-proxied-server-to-shared-server [flags] -``` - -**Flags:** - -``` - --dry-run Show what would be done without making changes -``` - -## bd migrate from-server-to-proxied-server - -Switch a repo from server mode (bd init --server) to proxied-server mode. - -Both modes root their dolt sql-server at the same .beads/dolt directory, so this -only rewrites .beads/metadata.json (dolt_mode) and writes the proxied-server -sidecar — no Dolt data is copied or moved. Stop the running server first with -'bd dolt stop'. - -Note: dolt_mode lives in the committed metadata.json, so this change propagates -to clones on the next push. - -``` -bd migrate from-server-to-proxied-server [flags] -``` - -**Flags:** - -``` - --dry-run Show what would be done without making changes - --idle-timeout duration Proxy idle timeout; omit for the 30s default, 0 for indefinite uptime -``` - -## bd migrate from-shared-server-to-proxied-server - -Switch a repo from shared-server mode to proxied-server mode. - -The proxied server is rooted at the shared dolt directory -(~/.beads/shared-server/dolt), so no Dolt data is copied or moved; this rewrites -.beads/metadata.json (dolt_mode), turns off dolt.shared-server for this repo, and -writes the proxied-server sidecar. Stop the running shared server first with -'bd dolt stop' — note that stops it for every project sharing it. - -``` -bd migrate from-shared-server-to-proxied-server [flags] -``` - -**Flags:** - -``` - --dry-run Show what would be done without making changes - --idle-timeout duration Proxy idle timeout; omit for the 30s default, 0 for indefinite uptime -``` - ## bd migrate hooks Analyze git hook files and sidecar artifacts for migration to marker-managed format. @@ -221,8 +122,7 @@ bd migrate schema [flags] **Flags:** ``` - --force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1) - --json Output in JSON format + --json Output in JSON format ``` ## bd migrate sync diff --git a/docs/cli-reference/mol.md b/docs/cli-reference/mol.md index 055f69c86..a87d970a0 100644 --- a/docs/cli-reference/mol.md +++ b/docs/cli-reference/mol.md @@ -1,6 +1,6 @@ --- title: "bd mol" -description: "Molecule commands (work templates)" +description: "Manage molecules - work templates for agent workflows." --- {/* AUTO-GENERATED: do not edit manually */} @@ -31,7 +31,7 @@ Commands: Use "bd formula list" to list available formulas. ``` -bd mol [command] +bd mol [flags] ``` **Aliases:** protomolecule @@ -238,8 +238,7 @@ bd mol last-activity [flags] Pour a proto into a persistent mol - like pouring molten metal into a mold. This is the chemistry-inspired command for creating PERSISTENT work from templates. -The resulting mol is stored as persistent beads in the issue database and -syncs like any other bead (bd dolt push / pull). +The resulting mol lives in .beads/ (permanent storage) and is synced with git. Phase transition: Proto (solid) -> pour -> Mol (liquid) @@ -319,12 +318,6 @@ Examples: bd mol ready --gated [flags] ``` -**Flags:** - -``` - --gated Find molecules ready for gate-resume dispatch (always on for this subcommand) -``` - ## bd mol seed Verify that a formula is accessible and can be cooked. @@ -492,7 +485,6 @@ Subcommands: ``` bd mol wisp [proto-id] [flags] -bd mol wisp [command] ``` **Flags:** diff --git a/docs/cli-reference/note.md b/docs/cli-reference/note.md index 925e76fbb..5c84ad1d1 100644 --- a/docs/cli-reference/note.md +++ b/docs/cli-reference/note.md @@ -1,6 +1,6 @@ --- title: "bd note" -description: "Append a note to an issue" +description: "Append a note to an issue's notes field." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/notion.md b/docs/cli-reference/notion.md index 3670b3623..8a0bb5896 100644 --- a/docs/cli-reference/notion.md +++ b/docs/cli-reference/notion.md @@ -1,6 +1,6 @@ --- title: "bd notion" -description: "Notion integration commands" +description: "Commands for syncing issues between beads and Notion." --- {/* AUTO-GENERATED: do not edit manually */} @@ -10,7 +10,7 @@ Generated from `bd help --doc notion`. Commands for syncing issues between beads and Notion. ``` -bd notion [command] +bd notion [flags] ``` ## bd notion connect diff --git a/docs/cli-reference/onboard.md b/docs/cli-reference/onboard.md index 5c60655a1..29424eb8a 100644 --- a/docs/cli-reference/onboard.md +++ b/docs/cli-reference/onboard.md @@ -1,6 +1,6 @@ --- title: "bd onboard" -description: "Display minimal snippet for agent instructions file" +description: "Display a minimal snippet to add to your agent instructions file for bd integration." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/orphans.md b/docs/cli-reference/orphans.md index 5631af325..de1fb2a00 100644 --- a/docs/cli-reference/orphans.md +++ b/docs/cli-reference/orphans.md @@ -1,6 +1,6 @@ --- title: "bd orphans" -description: "Identify orphaned issues (referenced in commits but still open)" +description: "Identify orphaned issues - issues that are referenced in commit messages but remain open or in_progress in the database." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/ping.md b/docs/cli-reference/ping.md index e3c86d550..39f2b5ee7 100644 --- a/docs/cli-reference/ping.md +++ b/docs/cli-reference/ping.md @@ -1,6 +1,6 @@ --- title: "bd ping" -description: "Check database connectivity" +description: "Lightweight health check that confirms bd can reach its database." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/preflight.md b/docs/cli-reference/preflight.md index 25ea5d76b..78f00e677 100644 --- a/docs/cli-reference/preflight.md +++ b/docs/cli-reference/preflight.md @@ -1,6 +1,6 @@ --- title: "bd preflight" -description: "Show PR readiness checklist" +description: "Display a checklist of common pre-PR checks for contributors." --- {/* AUTO-GENERATED: do not edit manually */} @@ -32,7 +32,7 @@ bd preflight [flags] ``` --check Run checks automatically - --fix Auto-fix issues where possible (vendorHash, version sync) + --fix Auto-fix issues where possible (not yet implemented) --json Output results as JSON --skip-lint Skip lint check explicitly ``` diff --git a/docs/cli-reference/prime.md b/docs/cli-reference/prime.md index bd68ffc8d..a6376671f 100644 --- a/docs/cli-reference/prime.md +++ b/docs/cli-reference/prime.md @@ -1,6 +1,6 @@ --- title: "bd prime" -description: "Output AI-optimized workflow context" +description: "Output essential Beads workflow context in AI-optimized markdown format." --- {/* AUTO-GENERATED: do not edit manually */} @@ -20,28 +20,11 @@ Config options: - no-git-ops: When true, outputs stealth mode (no git commands in session close protocol). Set via: bd config set no-git-ops true Useful when you want to control when commits happen manually. -- agent.profile: Explicit policy profile for git/commit authority wording - (conservative | minimal | team-maintainer; default conservative). - Set via: bd config set agent.profile team-maintainer - Or per-session: BD_AGENT_PROFILE=team-maintainer (env var takes precedence). - See docs/getting-started/ide-setup.md#policy-profiles for what each profile means. Workflow customization: - - Place a .beads/PRIME.md file in the local clone or resolved workspace to override the default workflow text. Persistent memories (from bd remember) are still appended so memory injection keeps working under a custom template. + - Place a .beads/PRIME.md file in the local clone or resolved workspace to override the default output entirely. - Use --export to dump the default content for customization. - - Use --memories-only for hook contexts that should inject only persistent memories; this returns only the memories section even when a custom PRIME.md is present. - - Use --no-memories to omit the persistent memories section (useful when the memories section is large and would dominate a context budget). --memories-only takes precedence if both are set. - -Memory injection caps: - Large memory sets can exceed what a session-start hook host will ingest, - and hosts truncate silently. Cap what prime injects with --max-memories N - and/or --max-memory-chars N (or the prime.max-memories / - prime.max-memory-chars config keys; an explicit flag wins, and an explicit - 0 forces unlimited). Caps apply at whole-memory boundaries, at least one - memory is always emitted, and a banner ahead of the entries reports how - many were elided and how to browse the rest with bd memories. - --max-memory-chars caps the total bytes of the injected memory entries; - the section header and elision banner are excluded from the budget. + - Use --memories-only for hook contexts that should inject only persistent memories. ``` bd prime [flags] @@ -50,13 +33,10 @@ bd prime [flags] **Flags:** ``` - --export Output default content (ignores PRIME.md override) - --full Force full CLI output (ignore MCP detection) - --hook-json Wrap output in the SessionStart hook JSON envelope (Claude Code, Gemini CLI, Codex) - --max-memories int Cap injected persistent memories to N entries (0 = unlimited; falls back to the prime.max-memories config key) - --max-memory-chars int Cap the total bytes of injected memory entries, at whole-memory boundaries; section header and banner are not counted (0 = unlimited; falls back to the prime.max-memory-chars config key) - --mcp Force MCP mode (minimal output) - --memories-only Output only persistent memories for compact hook contexts - --no-memories Omit the persistent memories section (ignored when --memories-only is set, which wins) - --stealth Stealth mode (no git operations, flush only) + --export Output default content (ignores PRIME.md override) + --full Force full CLI output (ignore MCP detection) + --hook-json Wrap output in the SessionStart hook JSON envelope (Claude Code, Gemini CLI, Codex) + --mcp Force MCP mode (minimal output) + --memories-only Output only persistent memories for compact hook contexts + --stealth Stealth mode (no git operations, flush only) ``` diff --git a/docs/cli-reference/priority.md b/docs/cli-reference/priority.md index 892542fe8..323ab3ea5 100644 --- a/docs/cli-reference/priority.md +++ b/docs/cli-reference/priority.md @@ -1,6 +1,6 @@ --- title: "bd priority" -description: "Set the priority of an issue" +description: "Set the priority of an issue." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/promote.md b/docs/cli-reference/promote.md index 06b12f76e..fefc1ccd7 100644 --- a/docs/cli-reference/promote.md +++ b/docs/cli-reference/promote.md @@ -1,6 +1,6 @@ --- title: "bd promote" -description: "Promote a wisp to a permanent bead" +description: "Promote a wisp (ephemeral issue) to a permanent bead." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/prune.md b/docs/cli-reference/prune.md index a9d93a973..6ef3af215 100644 --- a/docs/cli-reference/prune.md +++ b/docs/cli-reference/prune.md @@ -1,6 +1,6 @@ --- title: "bd prune" -description: "Delete old closed beads to reclaim space and shrink exports" +description: "Permanently delete closed non-ephemeral beads and their associated data." --- {/* AUTO-GENERATED: do not edit manually */} @@ -20,12 +20,6 @@ Use `--pattern '*'` if you really do want to sweep everything closed. Deletes: issues, dependencies, labels, events, and comments for matching beads. Skips: pinned beads (protected), open/in-progress beads, and ephemeral beads. -Also skips closed beads whose ID appears in the description, notes, or -comments of any open / in-progress bead. This protects ADR / decision / -verification trails that downstream beads still cite. Use ---ignore-references to override (e.g., when bulk-decommissioning a -retired label across the rig). - To delete closed ephemeral beads (wisps, transient molecules) use `bd purge` instead. @@ -48,7 +42,6 @@ bd prune [flags] ``` --dry-run Preview what would be pruned with stats -f, --force Actually prune (without this, shows preview) - --ignore-references Delete closed beads even when referenced by open beads (use with care; see --help for details) --older-than string Only prune beads closed more than N ago (e.g., 30d, 2w, 60) --pattern string Only prune beads matching ID glob pattern (e.g., 'gm-old-*') ``` diff --git a/docs/cli-reference/purge.md b/docs/cli-reference/purge.md index a5425e052..f62acb40b 100644 --- a/docs/cli-reference/purge.md +++ b/docs/cli-reference/purge.md @@ -1,6 +1,6 @@ --- title: "bd purge" -description: "Delete closed ephemeral beads to reclaim space" +description: "Permanently delete closed ephemeral beads and their associated data." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/q.md b/docs/cli-reference/q.md index f9100cb7b..31ecd8701 100644 --- a/docs/cli-reference/q.md +++ b/docs/cli-reference/q.md @@ -1,6 +1,6 @@ --- title: "bd q" -description: "Quick capture: create issue and output only ID" +description: "Quick capture creates an issue and outputs only the issue ID." --- {/* AUTO-GENERATED: do not edit manually */} @@ -14,7 +14,6 @@ Example: bd q "Fix login bug" # Outputs: bd-a1b2 ISSUE=$(bd q "New feature") # Capture ID in variable bd q "Task" | xargs bd show # Pipe to other commands - bd q "Subtask" --parent=bd-a1b2 # Hierarchical child (outputs: bd-a1b2.1) ``` bd q [title] [flags] @@ -24,7 +23,6 @@ bd q [title] [flags] ``` -l, --labels strings Labels - --parent string Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9') -p, --priority string Priority (0-4 or P0-P4) (default "2") -t, --type string Issue type (default "task") ``` diff --git a/docs/cli-reference/query.md b/docs/cli-reference/query.md index ad99eff37..a2e4d51bd 100644 --- a/docs/cli-reference/query.md +++ b/docs/cli-reference/query.md @@ -1,6 +1,6 @@ --- title: "bd query" -description: "Query issues using a simple query language" +description: "Query issues using a simple query language that supports compound filters," --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/quickstart.md b/docs/cli-reference/quickstart.md index 10eaaaeb2..0694e7020 100644 --- a/docs/cli-reference/quickstart.md +++ b/docs/cli-reference/quickstart.md @@ -1,6 +1,6 @@ --- title: "bd quickstart" -description: "Quick start guide for bd" +description: "Display a quick start guide showing common bd workflows and patterns." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/ready.md b/docs/cli-reference/ready.md index e35accfd5..ecb492ded 100644 --- a/docs/cli-reference/ready.md +++ b/docs/cli-reference/ready.md @@ -1,6 +1,6 @@ --- title: "bd ready" -description: "Show ready work (open, no active blockers)" +description: "Show ready work (open issues with no active blockers)." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/recall.md b/docs/cli-reference/recall.md index d3710ef87..786aa2802 100644 --- a/docs/cli-reference/recall.md +++ b/docs/cli-reference/recall.md @@ -1,6 +1,6 @@ --- title: "bd recall" -description: "Retrieve a specific memory" +description: "Retrieve the full content of a memory by its key." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/recompute-blocked.md b/docs/cli-reference/recompute-blocked.md index 337909bcc..cd0713620 100644 --- a/docs/cli-reference/recompute-blocked.md +++ b/docs/cli-reference/recompute-blocked.md @@ -1,6 +1,6 @@ --- title: "bd recompute-blocked" -description: "Recompute is_blocked for all issues (repairs stale flags after a pull)" +description: "Recompute the denormalized is_blocked flag for every issue and wisp." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/remember.md b/docs/cli-reference/remember.md index daec23808..c20bed167 100644 --- a/docs/cli-reference/remember.md +++ b/docs/cli-reference/remember.md @@ -1,6 +1,6 @@ --- title: "bd remember" -description: "Store a persistent memory" +description: "Store a memory that persists across sessions and account rotations." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/rename-prefix.md b/docs/cli-reference/rename-prefix.md index ca8b4bdeb..7c57f3908 100644 --- a/docs/cli-reference/rename-prefix.md +++ b/docs/cli-reference/rename-prefix.md @@ -1,6 +1,6 @@ --- title: "bd rename-prefix" -description: "Rename the issue prefix for all issues in the database" +description: "Rename the issue prefix for all issues in the database." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/rename.md b/docs/cli-reference/rename.md index bc9cd3962..aa18be001 100644 --- a/docs/cli-reference/rename.md +++ b/docs/cli-reference/rename.md @@ -1,6 +1,6 @@ --- title: "bd rename" -description: "Rename an issue ID" +description: "Rename an issue from one ID to another." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/reopen.md b/docs/cli-reference/reopen.md index a48dd34af..6263ee8c0 100644 --- a/docs/cli-reference/reopen.md +++ b/docs/cli-reference/reopen.md @@ -1,6 +1,6 @@ --- title: "bd reopen" -description: "Reopen one or more closed issues" +description: "Reopen closed issues by setting status to 'open' and clearing the closed_at timestamp." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/repo.md b/docs/cli-reference/repo.md index c9a4e5794..7fb29a788 100644 --- a/docs/cli-reference/repo.md +++ b/docs/cli-reference/repo.md @@ -1,6 +1,6 @@ --- title: "bd repo" -description: "Manage multiple repository configuration" +description: "Configure and manage multiple repository support for multi-repo hydration." --- {/* AUTO-GENERATED: do not edit manually */} @@ -28,7 +28,7 @@ Examples: bd repo sync # Sync from all configured repos ``` -bd repo [command] +bd repo [flags] ``` ## bd repo add diff --git a/docs/cli-reference/restore.md b/docs/cli-reference/restore.md index a668fc726..97c029bae 100644 --- a/docs/cli-reference/restore.md +++ b/docs/cli-reference/restore.md @@ -1,6 +1,6 @@ --- title: "bd restore" -description: "Restore the pre-compaction content of a compacted issue" +description: "Restore the pre-compaction content of a compacted issue." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/rules.md b/docs/cli-reference/rules.md index 1fc721bbc..c1c1bbf68 100644 --- a/docs/cli-reference/rules.md +++ b/docs/cli-reference/rules.md @@ -10,7 +10,7 @@ Generated from `bd help --doc rules`. Audit and compact Claude rules ``` -bd rules [command] +bd rules [flags] ``` ## bd rules audit diff --git a/docs/cli-reference/search.md b/docs/cli-reference/search.md index b1f4ac012..8fa2bcc86 100644 --- a/docs/cli-reference/search.md +++ b/docs/cli-reference/search.md @@ -1,6 +1,6 @@ --- title: "bd search" -description: "Search issues by text query" +description: "Search issues across title and ID (excludes closed issues by default)." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/set-state.md b/docs/cli-reference/set-state.md index 4ed7e49ec..15824d51a 100644 --- a/docs/cli-reference/set-state.md +++ b/docs/cli-reference/set-state.md @@ -1,6 +1,6 @@ --- title: "bd set-state" -description: "Set operational state (creates event + updates label)" +description: "Atomically set operational state on an issue." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/setup.md b/docs/cli-reference/setup.md index 4123ea1c9..8fefab335 100644 --- a/docs/cli-reference/setup.md +++ b/docs/cli-reference/setup.md @@ -1,6 +1,6 @@ --- title: "bd setup" -description: "Setup integration with AI editors" +description: "Setup integration files for AI editors and coding assistants." --- {/* AUTO-GENERATED: do not edit manually */} @@ -13,8 +13,7 @@ Recipes define where beads workflow instructions are written. Built-in recipes include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode. Examples: - bd setup cursor # Install Cursor IDE integration (rules + agent hooks) - bd setup cursor --global # Install global Cursor hooks (~/.cursor/hooks.json) + bd setup cursor # Install Cursor IDE integration bd setup codex # Install Codex skill + AGENTS.md guidance + native hooks bd setup codex --global # Install global Codex skill + guidance + native hooks bd setup copilot # Install Copilot CLI plugin + repository instructions @@ -38,7 +37,7 @@ bd setup [recipe] [flags] ``` --add string Add a custom recipe with given name --check Check if integration is installed - --global Install globally (claude/codex/cursor/mux; writes to ~/.claude/settings.json, $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md, ~/.cursor/hooks.json, or ~/.mux/AGENTS.md) + --global Install globally (claude/codex/mux; writes to ~/.claude/settings.json, $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md, or ~/.mux/AGENTS.md) --list List all available recipes -o, --output string Write template to custom path --print Print the template to stdout diff --git a/docs/cli-reference/ship.md b/docs/cli-reference/ship.md index ac7f33eca..791369616 100644 --- a/docs/cli-reference/ship.md +++ b/docs/cli-reference/ship.md @@ -1,6 +1,6 @@ --- title: "bd ship" -description: "Publish a capability for cross-project dependencies" +description: "Ship a capability to satisfy cross-project dependencies." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/sql.md b/docs/cli-reference/sql.md index e4ccff808..6d085b499 100644 --- a/docs/cli-reference/sql.md +++ b/docs/cli-reference/sql.md @@ -1,6 +1,6 @@ --- title: "bd sql" -description: "Execute raw SQL against the beads database" +description: "Execute a raw SQL query against the underlying database (SQLite or Dolt)." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/stale.md b/docs/cli-reference/stale.md index f3b3dc361..8bc14e0ae 100644 --- a/docs/cli-reference/stale.md +++ b/docs/cli-reference/stale.md @@ -1,6 +1,6 @@ --- title: "bd stale" -description: "Show stale issues (not updated recently)" +description: "Show issues that haven't been updated recently and may need attention." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/state.md b/docs/cli-reference/state.md index 291da54fa..cd27d5db4 100644 --- a/docs/cli-reference/state.md +++ b/docs/cli-reference/state.md @@ -1,6 +1,6 @@ --- title: "bd state" -description: "Query the current value of a state dimension" +description: "Query the current value of a state dimension from an issue's labels." --- {/* AUTO-GENERATED: do not edit manually */} @@ -23,7 +23,6 @@ Examples: ``` bd state [flags] -bd state [command] ``` ## bd state list diff --git a/docs/cli-reference/status.md b/docs/cli-reference/status.md index fb851c7d5..2330f6724 100644 --- a/docs/cli-reference/status.md +++ b/docs/cli-reference/status.md @@ -1,6 +1,6 @@ --- title: "bd status" -description: "Show issue database overview and statistics" +description: "Show a quick snapshot of the issue database state and statistics." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/statuses.md b/docs/cli-reference/statuses.md index aeef4c1fe..156b62d65 100644 --- a/docs/cli-reference/statuses.md +++ b/docs/cli-reference/statuses.md @@ -1,6 +1,6 @@ --- title: "bd statuses" -description: "List valid issue statuses" +description: "List all valid issue statuses and their categories." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/supersede.md b/docs/cli-reference/supersede.md index 2fd2e1629..d4deb136b 100644 --- a/docs/cli-reference/supersede.md +++ b/docs/cli-reference/supersede.md @@ -1,6 +1,6 @@ --- title: "bd supersede" -description: "Mark an issue as superseded by a newer one" +description: "Mark an issue as superseded by a newer version." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/swarm.md b/docs/cli-reference/swarm.md index c4efdf0a4..f1bad1a90 100644 --- a/docs/cli-reference/swarm.md +++ b/docs/cli-reference/swarm.md @@ -1,6 +1,6 @@ --- title: "bd swarm" -description: "Swarm management for structured epics" +description: "Swarm management commands for coordinating parallel work on epics." --- {/* AUTO-GENERATED: do not edit manually */} @@ -13,7 +13,7 @@ A swarm is a structured body of work defined by an epic and its children, with dependencies forming a DAG (directed acyclic graph) of work. ``` -bd swarm [command] +bd swarm [flags] ``` ## bd swarm create diff --git a/docs/cli-reference/tag.md b/docs/cli-reference/tag.md index a143aa739..0607bde9b 100644 --- a/docs/cli-reference/tag.md +++ b/docs/cli-reference/tag.md @@ -1,6 +1,6 @@ --- title: "bd tag" -description: "Add a label to an issue" +description: "Add a label to an issue." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/todo.md b/docs/cli-reference/todo.md index ba57af7a1..43b21ea2c 100644 --- a/docs/cli-reference/todo.md +++ b/docs/cli-reference/todo.md @@ -1,6 +1,6 @@ --- title: "bd todo" -description: "Manage TODO items (convenience wrapper for task issues)" +description: "Manage TODO items as lightweight task issues." --- {/* AUTO-GENERATED: do not edit manually */} @@ -19,7 +19,6 @@ TODOs can be promoted to full issues by changing type or priority: ``` bd todo [flags] -bd todo [command] ``` ## bd todo add diff --git a/docs/cli-reference/types.md b/docs/cli-reference/types.md index 23f78be45..95a3db033 100644 --- a/docs/cli-reference/types.md +++ b/docs/cli-reference/types.md @@ -1,6 +1,6 @@ --- title: "bd types" -description: "List valid issue types" +description: "List all valid issue types that can be used with bd create --type." --- {/* AUTO-GENERATED: do not edit manually */} @@ -9,21 +9,14 @@ Generated from `bd help --doc types`. List all valid issue types that can be used with bd create --type. -Core work types (bug, task, feature, chore, epic, decision, spike, story, milestone) are always valid. +Core work types (bug, task, feature, chore, epic, decision) are always valid. Additional types require configuration via types.custom in .beads/config.yaml. Examples: bd types # List all types with descriptions - bd types --sections # List required sections for each type bd types --json # Output as JSON ``` bd types [flags] ``` - -**Flags:** - -``` - --sections Show required sections for each issue type -``` diff --git a/docs/cli-reference/undefer.md b/docs/cli-reference/undefer.md index 251596099..c43443978 100644 --- a/docs/cli-reference/undefer.md +++ b/docs/cli-reference/undefer.md @@ -1,6 +1,6 @@ --- title: "bd undefer" -description: "Undefer one or more issues (restore to open)" +description: "Undefer issues to restore them to open status." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/update.md b/docs/cli-reference/update.md index 72460521d..7de697ff2 100644 --- a/docs/cli-reference/update.md +++ b/docs/cli-reference/update.md @@ -1,6 +1,6 @@ --- title: "bd update" -description: "Update one or more issues" +description: "Update one or more issues." --- {/* AUTO-GENERATED: do not edit manually */} @@ -26,7 +26,7 @@ bd update [id...] [flags] -a, --assignee string Assignee --await-id string Set gate await_id (e.g., GitHub run ID for gh:run gates) --body-file string Read description from file (use - for stdin) - --claim Atomically claim the issue (sets assignee to you, status to in_progress; idempotent if already claimed by you; issues assigned to a pool alias listed in the claim.pools config are claimable too) + --claim Atomically claim the issue (sets assignee to you, status to in_progress; idempotent if already claimed by you) --defer string Defer until date (empty to clear). Issue hidden from bd ready until then -d, --description string Issue description --design string Design notes diff --git a/docs/cli-reference/upgrade.md b/docs/cli-reference/upgrade.md index 4d9367548..ddfc5c36e 100644 --- a/docs/cli-reference/upgrade.md +++ b/docs/cli-reference/upgrade.md @@ -1,6 +1,6 @@ --- title: "bd upgrade" -description: "Check and manage bd version upgrades" +description: "Commands for checking bd version upgrades and reviewing changes." --- {/* AUTO-GENERATED: do not edit manually */} @@ -17,7 +17,7 @@ The upgrade command helps you stay aware of bd version changes: Version tracking is automatic - bd updates metadata.json on every run. ``` -bd upgrade [command] +bd upgrade [flags] ``` ## bd upgrade ack diff --git a/docs/cli-reference/vc.md b/docs/cli-reference/vc.md index 6bb01ffd6..3dbcf9d5f 100644 --- a/docs/cli-reference/vc.md +++ b/docs/cli-reference/vc.md @@ -1,6 +1,6 @@ --- title: "bd vc" -description: "Version control operations" +description: "Version control operations for the beads database." --- {/* AUTO-GENERATED: do not edit manually */} @@ -16,7 +16,7 @@ Note: 'bd history', 'bd diff', and 'bd branch' also work for quick access. This subcommand provides additional operations like merge and commit. ``` -bd vc [command] +bd vc [flags] ``` ## bd vc commit diff --git a/docs/cli-reference/where.md b/docs/cli-reference/where.md index bb0afc3ec..8dcc9c567 100644 --- a/docs/cli-reference/where.md +++ b/docs/cli-reference/where.md @@ -1,6 +1,6 @@ --- title: "bd where" -description: "Show active beads location" +description: "Show the active beads database location, including redirect information." --- {/* AUTO-GENERATED: do not edit manually */} diff --git a/docs/cli-reference/worktree.md b/docs/cli-reference/worktree.md index 649eced2a..5405dad27 100644 --- a/docs/cli-reference/worktree.md +++ b/docs/cli-reference/worktree.md @@ -1,6 +1,6 @@ --- title: "bd worktree" -description: "Manage git worktrees for parallel development" +description: "Manage git worktrees with proper beads configuration." --- {/* AUTO-GENERATED: do not edit manually */} @@ -23,7 +23,7 @@ Examples: bd worktree info # Show info about current worktree ``` -bd worktree [command] +bd worktree [flags] ``` ## bd worktree create diff --git a/docs/docs.json b/docs/docs.json index c0685282c..b4c947f0f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -377,7 +377,6 @@ "cli-reference/github", "cli-reference/gitlab", "cli-reference/graph", - "cli-reference/heartbeat", "cli-reference/history", "cli-reference/hooks", "cli-reference/human", @@ -396,7 +395,6 @@ "cli-reference/memories", "cli-reference/merge-slot", "cli-reference/metrics", - "cli-reference/migrate-personal", "cli-reference/migrate", "cli-reference/mol", "cli-reference/note", @@ -415,7 +413,6 @@ "cli-reference/quickstart", "cli-reference/ready", "cli-reference/recall", - "cli-reference/reclaim", "cli-reference/recompute-blocked", "cli-reference/remember", "cli-reference/rename-prefix", @@ -439,7 +436,6 @@ "cli-reference/tag", "cli-reference/todo", "cli-reference/types", - "cli-reference/unclaim", "cli-reference/undefer", "cli-reference/update", "cli-reference/upgrade", diff --git a/engdocs/decisions/2026-07-17-docs-release-pin.md b/engdocs/decisions/2026-07-17-docs-release-pin.md new file mode 100644 index 000000000..c68e97be3 --- /dev/null +++ b/engdocs/decisions/2026-07-17-docs-release-pin.md @@ -0,0 +1,56 @@ +# Decision record: the docs describe the pinned release, not main + +Date: 2026-07-17 +Decided by: Chris Sells +Status: settled — do not relitigate without new information + +Scope: which bd version the user docs (`docs/`) — hand-written pages and the +generated CLI reference — are written against and validated against. + +## The problem + +The Mintlify site publishes from `main`, but users run the latest release. +Between a release tag and the next release, `main` accumulates commands, +flags, and behavior no released binary has; docs generated from `main`'s +source then document features users cannot run (as happened between v1.1.0 +and this decision: storage backends, pool claiming, `bd migrate --force`, +four unreleased commands). + +## Decisions + +### 1. The published docs describe the latest release + +Hand-written pages state what the released binary does. The docs homepage +names the release it documents and links its release notes. Features that +exist only on `main` are not documented — no "coming soon" warnings, no +future-feature pages. + +### 2. The generated CLI reference is pinned via docs/cli-docs.pin + +`docs/cli-docs.pin` names the release tag. The docs pipeline +(`scripts/generate-cli-docs.sh`, `scripts/check-doc-flags.sh`, +`scripts/check-cli-docs-drift.sh`) builds bd from that tag +(`scripts/resolve-docs-bd.sh`, CGO_ENABLED=0 `-tags gms_pure_go` — CI's +canonical build) and generates/validates the committed docs against it. A +binary supplied on the command line is ignored while the pin is set +(`BD_DOCS_IGNORE_PIN=1` bypasses, e.g. to preview an unreleased emitter). +The pin is bumped as part of each release, followed by +`./scripts/generate-cli-docs.sh`. + +Why: the drift gates stay (docs remain regenerable and hand-edit-proof), but +they now enforce the policy in decision 1 instead of docs-match-main. + +### 3. Legacy-emitter releases are bridged in docsmint + +Releases up to v1.1.0 emit the CLI reference in the pre-overhaul Docusaurus +form (`website/docs/cli-reference/`). `tools/docsmint` detects that layout +and converts it to the generic staging form before its normal Mintlify +transform (`tools/docsmint/legacy.go`). The shim is removable once the pin +reaches a release whose emitter writes `build/cli-docs/` natively. + +### 4. Hidden escape hatches are not documented + +`BD_ALLOW_REMOTE_MIGRATE` (and equivalents added later, e.g. a `--force` +migrate flag) stay out of the user docs. The remote-migrate gate prints its +own operator guidance by design; docs defer to it rather than teaching +agents a ready-to-run bypass. diff --git a/scripts/check-cli-docs-drift.sh b/scripts/check-cli-docs-drift.sh index ff4631685..2b28c14df 100755 --- a/scripts/check-cli-docs-drift.sh +++ b/scripts/check-cli-docs-drift.sh @@ -77,22 +77,27 @@ GEN_PATHSPECS=( print_fix_help() { echo "" - echo "To fix in any environment (build a canonical bd, then regenerate):" - echo " CGO_ENABLED=0 go build -tags gms_pure_go -o ./bd-docs ./cmd/bd/" - echo " ./scripts/generate-cli-docs.sh ./bd-docs" - echo " rm ./bd-docs" + echo "To fix in any environment, regenerate with the pipeline's canonical bd" + echo "(built from the release pin in docs/cli-docs.pin when set, else from" + echo "this checkout, CGO_ENABLED=0 -tags gms_pure_go):" + echo " ./scripts/generate-cli-docs.sh" } # Check out a commit into a scratch worktree and regenerate every generated -# doc artifact there with the canonical pinned build. +# doc artifact there with the canonical build: the release pin when that +# commit has one, else a pure-Go build of the commit's own source. regen_worktree() { local sha="$1" dir="$2" git -C "$PROJECT_ROOT" worktree add --detach --quiet "$dir" "$sha" ( cd "$dir" - CGO_ENABLED=0 go build -tags gms_pure_go -o "$dir/.docs-bd" ./cmd/bd/ - ./scripts/generate-cli-docs.sh "$dir/.docs-bd" >/dev/null - rm -f "$dir/.docs-bd" + if [ -x scripts/resolve-docs-bd.sh ] && [ -n "$(scripts/resolve-docs-bd.sh)" ]; then + ./scripts/generate-cli-docs.sh >/dev/null + else + CGO_ENABLED=0 go build -tags gms_pure_go -o "$dir/.docs-bd" ./cmd/bd/ + ./scripts/generate-cli-docs.sh "$dir/.docs-bd" >/dev/null + rm -f "$dir/.docs-bd" + fi ) } diff --git a/scripts/check-doc-flags.sh b/scripts/check-doc-flags.sh index 23822e2dd..24c16464b 100755 --- a/scripts/check-doc-flags.sh +++ b/scripts/check-doc-flags.sh @@ -21,6 +21,19 @@ ERRORS=0 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" +# Release pin (docs/cli-docs.pin): the docs describe the pinned release, so +# every check below validates against a bd built from that tag, not the +# supplied binary. Set BD_DOCS_IGNORE_PIN=1 to bypass. +if [ "${BD_DOCS_IGNORE_PIN:-0}" != "1" ]; then + PINNED_BD="$("$SCRIPT_DIR/resolve-docs-bd.sh")" + if [ -n "$PINNED_BD" ]; then + if [ "$BD" != "$PINNED_BD" ]; then + echo "Note: docs are pinned via docs/cli-docs.pin; validating against the pinned bd." + fi + BD="$PINNED_BD" + fi +fi + # Verify bd binary exists and runs if ! command -v "$BD" &>/dev/null && [ ! -x "$BD" ]; then echo "Error: bd binary not found at '$BD'" @@ -28,6 +41,15 @@ if ! command -v "$BD" &>/dev/null && [ ! -x "$BD" ]; then exit 1 fi +# macOS has no coreutils timeout(1) by default; degrade to an unbounded run. +run_bounded() { + if command -v timeout >/dev/null 2>&1; then + timeout 30 "$@" + else + "$@" + fi +} + echo "Checking documentation against CLI flags..." echo "Using: $($BD version 2>/dev/null | head -1 || echo "$BD")" echo "" @@ -117,7 +139,7 @@ CLI_REF="$PROJECT_ROOT/docs/CLI_REFERENCE.md" if [ -f "$CLI_REF" ]; then TMPDIR_CHECK=$(mktemp -d) trap "rm -rf $TMPDIR_CHECK" EXIT - if timeout 30 "$BD" help --list > "$TMPDIR_CHECK/help-cmds.txt" 2>/dev/null; then + if run_bounded "$BD" help --list > "$TMPDIR_CHECK/help-cmds.txt" 2>/dev/null; then sort -u "$TMPDIR_CHECK/help-cmds.txt" -o "$TMPDIR_CHECK/help-cmds.txt" grep -oE '\bbd [a-z][a-z0-9-]*\b' "$CLI_REF" \ diff --git a/scripts/generate-cli-docs.sh b/scripts/generate-cli-docs.sh index 694109e70..3813c5aaa 100755 --- a/scripts/generate-cli-docs.sh +++ b/scripts/generate-cli-docs.sh @@ -37,6 +37,10 @@ and the CLI pages array in docs/docs.json) from one bd process plus the tools/docsmint post-processor. --check regenerates into a scratch root and fails if the committed copies are stale. +When docs/cli-docs.pin names a release tag, bd is built from that tag +(the published docs describe the pinned release, not this checkout) and a +supplied binary is ignored; set BD_DOCS_IGNORE_PIN=1 to bypass the pin. + If the resolved bd binary is CGO-enabled it emits the full `bd federation` help tree that CI (CGO_ENABLED=0) stubs out; the script rebuilds a pinned pure-go binary to keep committed docs in sync. Set BD_DOCS_ALLOW_CGO=1 to @@ -65,7 +69,21 @@ cleanup() { } trap cleanup EXIT -if [ -n "$BD_ARG" ]; then +# Release pin (docs/cli-docs.pin): the published docs describe the pinned +# release, so the pipeline builds bd from that tag and ignores any supplied +# binary. Set BD_DOCS_IGNORE_PIN=1 to bypass (e.g. to preview docs for an +# unreleased emitter). +PINNED_BD="" +if [ "${BD_DOCS_IGNORE_PIN:-0}" != "1" ]; then + PINNED_BD="$("$SCRIPT_DIR/resolve-docs-bd.sh")" +fi + +if [ -n "$PINNED_BD" ]; then + if [ -n "$BD_ARG" ] && [ "$BD_ARG" != "$PINNED_BD" ]; then + echo "Note: docs are pinned via docs/cli-docs.pin; ignoring supplied binary $BD_ARG." >&2 + fi + BD="$PINNED_BD" +elif [ -n "$BD_ARG" ]; then BD="$BD_ARG" elif [ "$CHECK_MODE" -eq 0 ] && [ -x "$PROJECT_ROOT/bd" ]; then # Convenience for regeneration only. --check never trusts a repo-root @@ -91,7 +109,7 @@ fi # the committed docs always match CI. Set BD_DOCS_ALLOW_CGO=1 to bypass the rebuild and # trust the supplied binary as-is (e.g. to deliberately regenerate the full federation # tree); you then own any federation churn the diff introduces. -if [ -x "$BD" ] && ! "$BD" federation --help 2>&1 | grep -q "Federation commands require CGO"; then +if [ -z "$PINNED_BD" ] && [ -x "$BD" ] && ! "$BD" federation --help 2>&1 | grep -q "Federation commands require CGO"; then if [ "${BD_DOCS_ALLOW_CGO:-0}" = "1" ]; then echo "WARNING: $BD looks CGO-enabled and emits the full 'bd federation' help tree," >&2 echo " which CI's pure-go docs build stubs out. BD_DOCS_ALLOW_CGO=1 is set," >&2 @@ -117,8 +135,18 @@ fi generate_all() { local root="$1" + local had_website=0 + [ -d "$root/website" ] && had_website=1 + # Clear stale staging so docsmint can only consume what this bd emitted + # (a pinned legacy bd stages under website/, not build/cli-docs). + rm -rf "$root/build/cli-docs" "$BD" help --docs-root "$root" (cd "$PROJECT_ROOT" && go run -tags=gms_pure_go ./tools/docsmint "$root") + # A pinned legacy emitter (bd <= v1.1.0) stages Docusaurus pages under + # website/; docsmint has consumed them, so drop the scaffolding. + if [ "$had_website" -eq 0 ] && [ -d "$root/website" ]; then + rm -rf "$root/website" + fi } if [ "$CHECK_MODE" -eq 1 ]; then diff --git a/scripts/resolve-docs-bd.sh b/scripts/resolve-docs-bd.sh new file mode 100755 index 000000000..9c01ed8bd --- /dev/null +++ b/scripts/resolve-docs-bd.sh @@ -0,0 +1,59 @@ +#!/bin/bash +# resolve-docs-bd.sh — Resolve the bd binary the docs pipeline must use. +# +# Reads the release pin from docs/cli-docs.pin. When the pin names a tag, +# builds (and caches) a canonical pure-Go bd from that tag's source and +# prints the binary's absolute path on stdout. When the pin is HEAD or the +# pin file is absent, prints nothing and exits 0: callers fall back to their +# current-checkout behavior. +# +# The build matches CI's canonical docs build (CGO_ENABLED=0, -tags +# gms_pure_go), so regenerated docs are reproducible in any environment. +# The binary is cached at build/docs-bd//bd (gitignored via /build/). +# +# Usage: scripts/resolve-docs-bd.sh +# stdout: absolute path to the pinned bd binary, or empty when unpinned +# diagnostics go to stderr + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" +PIN_FILE="$PROJECT_ROOT/docs/cli-docs.pin" + +if [ ! -f "$PIN_FILE" ]; then + exit 0 +fi + +PIN="$(grep -v '^[[:space:]]*#' "$PIN_FILE" | grep -m1 '[^[:space:]]' | tr -d '[:space:]' || true)" +if [ -z "$PIN" ] || [ "$PIN" = "HEAD" ]; then + exit 0 +fi + +CACHE_DIR="$PROJECT_ROOT/build/docs-bd/$PIN" +CACHED_BD="$CACHE_DIR/bd" +if [ -x "$CACHED_BD" ]; then + echo "$CACHED_BD" + exit 0 +fi + +# Make sure the pinned tag exists locally; shallow CI checkouts may not have +# fetched tags. +if ! git -C "$PROJECT_ROOT" rev-parse --verify --quiet "refs/tags/$PIN^{commit}" >/dev/null; then + echo "docs pin: fetching tag $PIN from origin..." >&2 + git -C "$PROJECT_ROOT" fetch --depth=1 origin "refs/tags/$PIN:refs/tags/$PIN" >&2 +fi + +echo "docs pin: building bd from tag $PIN (CGO_ENABLED=0 -tags gms_pure_go)..." >&2 +WT="$(mktemp -d)" +cleanup() { + git -C "$PROJECT_ROOT" worktree remove --force "$WT" >/dev/null 2>&1 || true + rm -rf "$WT" +} +trap cleanup EXIT + +git -C "$PROJECT_ROOT" worktree add --detach --quiet "$WT" "refs/tags/$PIN" +mkdir -p "$CACHE_DIR" +(cd "$WT" && CGO_ENABLED=0 go build -tags gms_pure_go -o "$CACHED_BD" ./cmd/bd/) >&2 + +echo "$CACHED_BD" diff --git a/tools/docsmint/docsmint.go b/tools/docsmint/docsmint.go index a2aa77a59..97501a029 100644 --- a/tools/docsmint/docsmint.go +++ b/tools/docsmint/docsmint.go @@ -22,15 +22,26 @@ var ( // run post-processes the generic staging tree at /build/cli-docs into // the committed Mintlify pages at /docs/cli-reference and splices the -// CLI Reference pages array in /docs/docs.json. +// CLI Reference pages array in /docs/docs.json. When the generic tree +// is absent but the pinned bd's legacy emitter wrote +// /website/docs/cli-reference (Docusaurus form, bd <= v1.1.0), those +// pages are converted to the generic form first (see legacy.go). func run(root string) error { staging := filepath.Join(root, "build", "cli-docs") + legacyStaging := filepath.Join(root, "website", "docs", "cli-reference") target := filepath.Join(root, "docs", "cli-reference") docsJSON := filepath.Join(root, "docs", "docs.json") + stagingDir := staging + legacy := false entries, err := os.ReadDir(staging) if err != nil { - return fmt.Errorf("reading staging tree %s (run `bd help --docs-root` first): %w", staging, err) + entries, err = os.ReadDir(legacyStaging) + if err != nil { + return fmt.Errorf("no staging tree at %s or %s (run `bd help --docs-root` first)", staging, legacyStaging) + } + stagingDir = legacyStaging + legacy = true } var pages []string @@ -41,7 +52,7 @@ func run(root string) error { pages = append(pages, entry.Name()) } if len(pages) == 0 { - return fmt.Errorf("staging tree %s contains no markdown pages (run `bd help --docs-root` first)", staging) + return fmt.Errorf("staging tree %s contains no markdown pages (run `bd help --docs-root` first)", stagingDir) } sort.Strings(pages) @@ -60,11 +71,22 @@ func run(root string) error { for _, name := range pages { // #nosec G304: name comes from os.ReadDir over the repo's own staging // tree (filtered to *.md above), not from external input. - data, err := os.ReadFile(filepath.Join(staging, name)) + data, err := os.ReadFile(filepath.Join(stagingDir, name)) if err != nil { return err } - out := transformPage(string(data)) + generic := string(data) + if legacy { + if name == "index.md" { + generic, err = convertLegacyIndex(generic) + } else { + generic, err = convertLegacyPage(generic) + } + if err != nil { + return fmt.Errorf("converting legacy page %s: %w", name, err) + } + } + out := transformPage(generic) // #nosec G306: generated repository Markdown should be readable like source files. if err := os.WriteFile(filepath.Join(target, name), []byte(out), 0o644); err != nil { return err diff --git a/tools/docsmint/legacy.go b/tools/docsmint/legacy.go new file mode 100644 index 000000000..28509ba95 --- /dev/null +++ b/tools/docsmint/legacy.go @@ -0,0 +1,142 @@ +package main + +import ( + "fmt" + "strings" +) + +// Legacy-emitter support. Release tags before the docsmint pipeline (bd +// v1.1.0 and earlier) emit Docusaurus-style pages to +// website/docs/cli-reference/ instead of the generic staging tree at +// build/cli-docs/. While docs/cli-docs.pin points at such a release, docsmint +// converts those pages to the generic form here and then runs its normal +// Mintlify transform. This shim is removable once the pin reaches a release +// whose emitter writes build/cli-docs/ natively. + +const autoGeneratedComment = "" + +// convertLegacyPage converts one Docusaurus-form command page (frontmatter +// with id/title/slug/sidebar_position, an H2 command heading, subcommands one +// heading level deeper) into the generic staging form the modern emitter +// writes (title/description frontmatter, no top command heading, subcommands +// at H2). +func convertLegacyPage(content string) (string, error) { + body, err := stripFrontmatter(content) + if err != nil { + return "", err + } + lines := trimLeadingBlank(strings.Split(body, "\n")) + if len(lines) == 0 || lines[0] != autoGeneratedComment { + return "", fmt.Errorf("missing %q marker", autoGeneratedComment) + } + if len(lines) < 2 || !strings.HasPrefix(lines[1], "Generated from") { + return "", fmt.Errorf("missing Generated-from line") + } + genLine := strings.TrimRight(lines[1], " ") + if !strings.HasSuffix(genLine, ".") { + genLine += "." + } + + rest := trimLeadingBlank(lines[2:]) + if len(rest) == 0 || !strings.HasPrefix(rest[0], "## bd ") { + return "", fmt.Errorf("expected '## bd ' heading") + } + title := strings.TrimPrefix(rest[0], "## ") + + rest = trimLeadingBlank(rest[1:]) + // The Cobra Short line doubles as the page description and stays in the + // body, exactly as the modern emitter leaves it. + short := "" + if len(rest) > 0 { + first := strings.TrimSpace(rest[0]) + if first != "" && !strings.HasPrefix(first, "#") && !strings.HasPrefix(first, "```") { + short = first + } + } + rest = promoteHeadings(rest) + + var b strings.Builder + b.WriteString("---\n") + // #nosec G705: not a web-output sink — this developer tool emits repo + // Markdown frontmatter; title/description are %q-quoted strings taken + // from the repo's own generated staging pages. + fmt.Fprintf(&b, "title: %q\ndescription: %q\n", title, short) + b.WriteString("---\n\n") + b.WriteString(autoGeneratedComment + "\n\n") + b.WriteString(genLine + "\n\n") + b.WriteString(strings.Join(rest, "\n")) + return strings.TrimRight(b.String(), "\n") + "\n", nil +} + +// convertLegacyIndex converts the Docusaurus-form index page (H1 title, +// versioned intro line) into the generic staging index form. +func convertLegacyIndex(content string) (string, error) { + body, err := stripFrontmatter(content) + if err != nil { + return "", err + } + lines := trimLeadingBlank(strings.Split(body, "\n")) + if len(lines) == 0 || lines[0] != "# CLI Reference" { + return "", fmt.Errorf("expected '# CLI Reference' heading") + } + lines = trimLeadingBlank(lines[1:]) + if len(lines) == 0 || lines[0] != autoGeneratedComment { + return "", fmt.Errorf("missing %q marker", autoGeneratedComment) + } + if len(lines) < 2 || !strings.HasPrefix(lines[1], "Reference for bd") { + return "", fmt.Errorf("missing 'Reference for bd' line") + } + rest := trimLeadingBlank(lines[2:]) + + var b strings.Builder + b.WriteString("---\n") + b.WriteString("title: CLI Reference\n") + b.WriteString("description: Generated reference for every bd command\n") + b.WriteString("---\n\n") + b.WriteString(autoGeneratedComment + "\n\n") + b.WriteString("Generated from `bd help --docs-root`.\n\n") + b.WriteString(strings.Join(rest, "\n")) + return strings.TrimRight(b.String(), "\n") + "\n", nil +} + +// stripFrontmatter removes the leading YAML frontmatter block and returns the +// remaining body. +func stripFrontmatter(content string) (string, error) { + lines := strings.Split(content, "\n") + if len(lines) == 0 || lines[0] != "---" { + return "", fmt.Errorf("missing frontmatter") + } + for i := 1; i < len(lines); i++ { + if lines[i] == "---" { + return strings.Join(lines[i+1:], "\n"), nil + } + } + return "", fmt.Errorf("unterminated frontmatter") +} + +// promoteHeadings lifts every H3+ heading one level (### -> ##) outside code +// fences: the legacy layout nests subcommands under the page's own command +// heading, which the generic form does not have. +func promoteHeadings(lines []string) []string { + out := make([]string, len(lines)) + inFence := false + for i, line := range lines { + if strings.HasPrefix(strings.TrimSpace(line), "```") { + inFence = !inFence + out[i] = line + continue + } + if !inFence && strings.HasPrefix(line, "###") { + line = line[1:] + } + out[i] = line + } + return out +} + +func trimLeadingBlank(lines []string) []string { + for len(lines) > 0 && strings.TrimSpace(lines[0]) == "" { + lines = lines[1:] + } + return lines +} diff --git a/tools/docsmint/legacy_test.go b/tools/docsmint/legacy_test.go new file mode 100644 index 000000000..6cbb8cccd --- /dev/null +++ b/tools/docsmint/legacy_test.go @@ -0,0 +1,160 @@ +package main + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +const legacyShowPage = `--- +id: show +title: bd show +slug: /cli-reference/show +sidebar_position: 40 +--- + + +Generated from ` + "`bd help --doc show`" + ` + +## bd show + +Show issue details + +### bd show sub + +Nested subcommand help. + +` + "```" + ` +### fenced heading stays put +` + "```" + ` +` + +const legacyIndexPage = `--- +id: index +title: CLI Reference +sidebar_position: 0 +--- + +# CLI Reference + + +Reference for bd Latest. Generated from ` + "`bd help --docs-root`" + `. + +This reference covers all 2 live top-level ` + "`bd`" + ` commands. + +## Commands + +- [` + "`bd show`" + `](./show.md) +` + +func TestConvertLegacyPageProducesGenericForm(t *testing.T) { + got, err := convertLegacyPage(legacyShowPage) + if err != nil { + t.Fatal(err) + } + for _, want := range []string{ + "title: \"bd show\"\n", + "description: \"Show issue details\"\n", + "Generated from `bd help --doc show`.\n", + "\n## bd show sub\n", + "\n### fenced heading stays put\n", + } { + if !strings.Contains(got, want) { + t.Errorf("converted page missing %q\n--- got ---\n%s", want, got) + } + } + if strings.Contains(got, "sidebar_position") || strings.Contains(got, "slug:") { + t.Errorf("legacy frontmatter leaked into converted page:\n%s", got) + } + if strings.Contains(got, "\n## bd show\n") { + t.Errorf("top command heading should be dropped:\n%s", got) + } +} + +func TestConvertLegacyIndexProducesGenericForm(t *testing.T) { + got, err := convertLegacyIndex(legacyIndexPage) + if err != nil { + t.Fatal(err) + } + for _, want := range []string{ + "title: CLI Reference\n", + "description: Generated reference for every bd command\n", + "Generated from `bd help --docs-root`.\n", + "- [`bd show`](./show.md)", + } { + if !strings.Contains(got, want) { + t.Errorf("converted index missing %q\n--- got ---\n%s", want, got) + } + } + if strings.Contains(got, "# CLI Reference\n\n\nGenerated from `bd help --doc x`\n\nprose\n", + } { + if _, err := convertLegacyPage(content); err == nil { + t.Errorf("%s: expected error, got none", name) + } + } +} + +func TestRunConsumesLegacyStagingTree(t *testing.T) { + root := t.TempDir() + writeFile(t, filepath.Join(root, "website", "docs", "cli-reference", "index.md"), legacyIndexPage) + writeFile(t, filepath.Join(root, "website", "docs", "cli-reference", "show.md"), legacyShowPage) + writeFile(t, filepath.Join(root, "docs", "CLI_REFERENCE.md"), "# bd — Complete Command Reference\n") + writeFile(t, filepath.Join(root, "docs", "docs.json"), `{ + "navigation": { + "groups": [ + { + "group": "CLI Reference", + "pages": [ + "cli-reference/index" + ] + } + ] + } +} +`) + + if err := run(root); err != nil { + t.Fatal(err) + } + + out, err := os.ReadFile(filepath.Join(root, "docs", "cli-reference", "show.md")) + if err != nil { + t.Fatal(err) + } + page := string(out) + if !strings.Contains(page, "{/* AUTO-GENERATED: do not edit manually */}") { + t.Errorf("legacy page should get the Mintlify comment transform:\n%s", page) + } + if !strings.Contains(page, "title: \"bd show\"") { + t.Errorf("legacy page should carry generic frontmatter:\n%s", page) + } + + idx, err := os.ReadFile(filepath.Join(root, "docs", "cli-reference", "index.md")) + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(idx), "](/cli-reference/show)") { + t.Errorf("legacy index links should become extensionless routes:\n%s", idx) + } + + nav, err := os.ReadFile(filepath.Join(root, "docs", "docs.json")) + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(nav), `"cli-reference/show"`) { + t.Errorf("nav should include the legacy-converted page:\n%s", nav) + } +}