Working with beads (bd)

Offline reference for the beads CLI, pinned to a known version (see PINNED_VERSION). The CLI pages in references/cli/ are generated verbatim from the installed pinned bd binary; the conceptual docs in references/docs/ are fetched from the repo at the matching tag. Every file carries source/fetched_at/sha256 frontmatter.

How to use this skill

1. CLI reference: read references/cli/_index.md for the command tree, then references/cli/<command>.md (or <command>__<subcommand>.md) for exact flags/usage — these are the literal output of bd <command> --help at the pinned version.
2. Workflow context: references/prime.md is the captured bd prime output (auto-generated; empty when captured outside a beads project). For how bd prime is wired into sessions, its flags/config, the PRIME.md override + resolution, and neutralizing the conservative preamble, see the beads-operations skill (references/prime-customization.md).
3. Concepts/advanced: grep references/docs/ (ADVANCED, federation, adaptive IDs, config, etc.).
4. If the installed bd differs from PINNED_VERSION, the reference may not match — bump the pin (see below) and regenerate, or run bd <cmd> --help directly.

Behavioral guidance

• The reference reflects the pinned version only. Always trust bd <cmd> --help from the live binary if they disagree, and surface the drift.
• For how Joe runs beads (--shared-server, shared Dolt server on port 3308, --skip-agents) and for fixing broken states, use the beads-operations skill — not this one.
• For the BeadBoard multi-agent dashboard that sits on top of bd: the agent-side coordination contract is the beadboard-driver skill; running its launchd services/dashboard/diagnostics is the beadboard-operations skill.

Reference map

• references/cli/_index.md — bd help top-level command tree.
• references/cli/<command>.md — per-command --help (nested groups as <command>__<subcommand>.md).
• references/prime.md — captured bd prime output (auto-generated). For the mechanics + PRIME.md customization, see beads-operations/references/prime-customization.md.
• references/docs/*.md — upstream docs/ + README.md at the pinned tag.

Keeping this current

Regenerated by scripts/update_docs.js: it reads PINNED_VERSION, generates the CLI reference from the local pinned bd, and fetches repo docs at the tag. Refresh locally with make update-working-with-beads. Bumping the pin is signoff-gated: edit PINNED_VERSION, run brew unpin beads && brew upgrade beads && brew pin beads (or install the target version), then rerun the update. The weekly CI workflow auto-discovers the script but produces no churn while the tag is unchanged, and skips CLI generation when bd is absent.