docs(cli): move the graph plan schema into an embedded doc supplement

The --graph schema section was hand-written into the generated
docs/CLI_REFERENCE.md, which the byte-exact drift gate rejects and any
regeneration (including the docs-autofix bot) would erase — breaking
TestDocsGraphPlanExampleValidates. Long: strings can't carry it either:
escapeMDXText would mangle the fenced JSON example.

Add a command doc-supplement mechanism: raw Markdown embedded from
cmd/bd/help_supplements/ and appended after a command's flags by the docs
generator, so regeneration reproduces the section byte-for-byte in both
CLI_REFERENCE.md and the per-command create.md page. Document the
parent/estimate aliases and their precedence while moving the text.
Regeneration also restores the four per-command pages (heartbeat,
migrate-personal, reclaim, unclaim) that docs.json already listed but the
committed tree was missing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Isis Anisoptera 2026-07-17 19:44:38 -07:00
commit aadd21c40b
9 changed files with 341 additions and 0 deletions

View file

@ -241,6 +241,11 @@ func writeCommandBody(w io.Writer, cmd *cobra.Command) {
if localFlags.HasFlags() {
fmt.Fprintf(w, "**Flags:**\n\n```\n%s```\n\n", localFlags.FlagUsages())
}
// Embedded doc supplement (raw Markdown, no MDX escaping).
if sup, ok := commandDocSupplements[cmd.CommandPath()]; ok {
fmt.Fprintf(w, "%s\n\n", strings.TrimSpace(sup))
}
}
// writeSingleCommandDoc generates one command's documentation page as generic

View file

@ -0,0 +1,20 @@
package main
import (
_ "embed"
)
// Command doc supplements are extra reference Markdown appended after a
// command's flags in the generated CLI docs (bd help --docs-root and the
// per-command staging tree). They are embedded sources, not hand edits:
// regeneration always reproduces them, so the docs drift gate stays
// byte-exact. Supplements are raw Markdown (fenced code allowed) and are
// emitted without MDX escaping — keep prose MDX-safe outside code fences.
//go:embed help_supplements/create_graph_plan.md
var createGraphPlanSupplement string
// commandDocSupplements maps a cobra CommandPath() to its supplement.
var commandDocSupplements = map[string]string{
"bd create": createGraphPlanSupplement,
}

View file

@ -0,0 +1,88 @@
**Graph plan schema (`--graph`):**
`bd create --graph plan.json` creates a whole issue graph atomically from a
JSON plan. Node field names follow the issue model's JSON tags (the same
names `bd show --json` emits), and every field single-issue `bd create` can
set is addressable from a plan — plus an initial `status` and `pinned`,
which `bd create` has no flags for:
```json
{
"commit_message": "optional Dolt commit message",
"nodes": [
{
"key": "api",
"title": "Design the API",
"type": "task",
"description": "…", "design": "…", "acceptance_criteria": "…", "notes": "…",
"status": "in_progress",
"priority": 1,
"assignee": "alice", "assign_after_create": false,
"owner": "alice@example.com",
"labels": ["backend"],
"estimated_minutes": 45,
"due_at": "2030-01-02T15:04:05Z",
"defer_until": "2030-01-01T00:00:00Z",
"spec_id": "bd-spec1", "external_ref": "gh-42",
"metadata": {"any": "json", "count": 3},
"metadata_refs": {"tracker": "impl"},
"id": "bd-a1b2c3",
"ephemeral": false, "no_history": false,
"wisp_type": "heartbeat", "mol_type": "swarm",
"pinned": false
},
{ "key": "impl", "title": "Implement it", "parent_key": "api" },
{ "key": "gate", "title": "Fanout gate" },
{ "key": "launch", "title": "Launch announced", "type": "event",
"event_kind": "agent.started", "actor": "agent://a", "target": "bead://b", "payload": "{}" }
],
"edges": [
{ "from_key": "gate", "to_key": "api", "type": "blocks" },
{ "from_key": "gate", "to_key": "impl", "type": "waits-for",
"gate": "any-children", "spawner_key": "impl" }
]
}
```
Node notes:
- `key` is a plan-local symbolic name; the result maps each key to the minted
issue ID. `id` optionally pins an explicit issue ID instead (must match the
database prefix, like `bd create --id`).
- `parent_key` (a plan node key) or `parent_id` (an existing issue ID) adds a
`parent-child` dependency on the created node.
- `parent` and `estimate` are accepted aliases for `parent_key` and
`estimated_minutes`; the canonical field wins when both spellings are set.
- `status` sets the initial status (default `open`, or `deferred` when
`defer_until` is in the future). Nodes created `closed` get `closed_at`
auto-filled. Timestamps are RFC3339; relative forms like `+6h` are not
accepted in plans.
- `ephemeral` / `no_history` override the plan-wide `--ephemeral` /
`--no-history` flags per node (mutually exclusive per node; in
proxied-server mode the effective storage class must be uniform across the
plan).
- `event_kind`, `actor`, `target`, and `payload` require `"type": "event"`.
- `metadata` accepts arbitrary JSON values; `metadata_refs` values name other
node keys and are replaced with their minted IDs after creation.
- Unlike `bd create --parent`, graph children do not inherit parent labels
and receive flat (non-hierarchical) IDs; plans are explicit artifacts.
Edge notes:
- `type` defaults to `blocks`. `parent_key`/`parent_id` on nodes already
create `parent-child` edges; don't repeat them in `edges`.
- `gate` (`all-children` | `any-children`) and `spawner_key`/`spawner_id`
attach fanout-gate metadata to `waits-for` edges, mirroring
`--waits-for`/`--waits-for-gate`. The `to` endpoint of a `waits-for` edge
*is* the spawner (gate evaluation watches its children), so `spawner_key`
must match `to_key` and `spawner_id` must match `to_id`; they exist to make
plans self-documenting. Since an explicit `to_id` overrides `to_key` as the
target, `spawner_key` cannot be combined with `to_id` — use `spawner_id`.
- Edges with ready-work-affecting types (`blocks`, `waits-for`, …) may not
duplicate or reverse a `parent_key`/`parent_id` relationship, and a parent
may not be connected to its own child through them.
- `thread_id` threads conversation edges (e.g. `replies-to`).
Comments cannot be created from a plan; use `bd comments add` after creation.
Model fields without `bd create` flags (`sender`, `work_type`, `is_template`,
`await_*`, `bonded_from`, `source_*`) are likewise not settable from plans.

View file

@ -572,6 +572,8 @@ Node notes:
database prefix, like `bd create --id`).
- `parent_key` (a plan node key) or `parent_id` (an existing issue ID) adds a
`parent-child` dependency on the created node.
- `parent` and `estimate` are accepted aliases for `parent_key` and
`estimated_minutes`; the canonical field wins when both spellings are set.
- `status` sets the initial status (default `open`, or `deferred` when
`defer_until` is in the future). Nodes created `closed` get `closed_at`
auto-filled. Timestamps are RFC3339; relative forms like `+6h` are not

View file

@ -61,3 +61,92 @@ bd create [title] [flags]
--waits-for-gate string Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children")
--wisp-type string Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation
```
**Graph plan schema (`--graph`):**
`bd create --graph plan.json` creates a whole issue graph atomically from a
JSON plan. Node field names follow the issue model's JSON tags (the same
names `bd show --json` emits), and every field single-issue `bd create` can
set is addressable from a plan — plus an initial `status` and `pinned`,
which `bd create` has no flags for:
```json
{
"commit_message": "optional Dolt commit message",
"nodes": [
{
"key": "api",
"title": "Design the API",
"type": "task",
"description": "…", "design": "…", "acceptance_criteria": "…", "notes": "…",
"status": "in_progress",
"priority": 1,
"assignee": "alice", "assign_after_create": false,
"owner": "alice@example.com",
"labels": ["backend"],
"estimated_minutes": 45,
"due_at": "2030-01-02T15:04:05Z",
"defer_until": "2030-01-01T00:00:00Z",
"spec_id": "bd-spec1", "external_ref": "gh-42",
"metadata": {"any": "json", "count": 3},
"metadata_refs": {"tracker": "impl"},
"id": "bd-a1b2c3",
"ephemeral": false, "no_history": false,
"wisp_type": "heartbeat", "mol_type": "swarm",
"pinned": false
},
{ "key": "impl", "title": "Implement it", "parent_key": "api" },
{ "key": "gate", "title": "Fanout gate" },
{ "key": "launch", "title": "Launch announced", "type": "event",
"event_kind": "agent.started", "actor": "agent://a", "target": "bead://b", "payload": "{}" }
],
"edges": [
{ "from_key": "gate", "to_key": "api", "type": "blocks" },
{ "from_key": "gate", "to_key": "impl", "type": "waits-for",
"gate": "any-children", "spawner_key": "impl" }
]
}
```
Node notes:
- `key` is a plan-local symbolic name; the result maps each key to the minted
issue ID. `id` optionally pins an explicit issue ID instead (must match the
database prefix, like `bd create --id`).
- `parent_key` (a plan node key) or `parent_id` (an existing issue ID) adds a
`parent-child` dependency on the created node.
- `parent` and `estimate` are accepted aliases for `parent_key` and
`estimated_minutes`; the canonical field wins when both spellings are set.
- `status` sets the initial status (default `open`, or `deferred` when
`defer_until` is in the future). Nodes created `closed` get `closed_at`
auto-filled. Timestamps are RFC3339; relative forms like `+6h` are not
accepted in plans.
- `ephemeral` / `no_history` override the plan-wide `--ephemeral` /
`--no-history` flags per node (mutually exclusive per node; in
proxied-server mode the effective storage class must be uniform across the
plan).
- `event_kind`, `actor`, `target`, and `payload` require `"type": "event"`.
- `metadata` accepts arbitrary JSON values; `metadata_refs` values name other
node keys and are replaced with their minted IDs after creation.
- Unlike `bd create --parent`, graph children do not inherit parent labels
and receive flat (non-hierarchical) IDs; plans are explicit artifacts.
Edge notes:
- `type` defaults to `blocks`. `parent_key`/`parent_id` on nodes already
create `parent-child` edges; don't repeat them in `edges`.
- `gate` (`all-children` | `any-children`) and `spawner_key`/`spawner_id`
attach fanout-gate metadata to `waits-for` edges, mirroring
`--waits-for`/`--waits-for-gate`. The `to` endpoint of a `waits-for` edge
*is* the spawner (gate evaluation watches its children), so `spawner_key`
must match `to_key` and `spawner_id` must match `to_id`; they exist to make
plans self-documenting. Since an explicit `to_id` overrides `to_key` as the
target, `spawner_key` cannot be combined with `to_id` — use `spawner_id`.
- Edges with ready-work-affecting types (`blocks`, `waits-for`, …) may not
duplicate or reverse a `parent_key`/`parent_id` relationship, and a parent
may not be connected to its own child through them.
- `thread_id` threads conversation edges (e.g. `replies-to`).
Comments cannot be created from a plan; use `bd comments add` after creation.
Model fields without `bd create` flags (`sender`, `work_type`, `is_template`,
`await_*`, `bonded_from`, `source_*`) are likewise not settable from plans.

View file

@ -0,0 +1,33 @@
---
title: "bd heartbeat"
description: "Refresh the lease on an issue you hold in_progress"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc 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 <id> [flags]
```
**Aliases:** hb

View file

@ -0,0 +1,33 @@
---
title: "bd migrate-personal"
description: "Move personal planning issues from the project database to your planning repo"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc 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
```

View file

@ -0,0 +1,37 @@
---
title: "bd reclaim"
description: "Revert stale-lease in_progress issues back to ready (dead-worker recovery)"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc 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 &gt;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)
```

View file

@ -0,0 +1,34 @@
---
title: "bd unclaim"
description: "Release a claimed issue"
---
{/* AUTO-GENERATED: do not edit manually */}
Generated from `bd help --doc 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
```