beads-docs

Writing beads docs

This is the house style for docs/ — the beads user documentation, published as a Mintlify site. The goal is docs that motivate before they jargon, say the same thing the same way everywhere, show concepts as pictures and snippets instead of walls of prose, and never drift from the code. Apply it to any page you create, edit, or review.

The audience of docs/ is a user of beads — a human or agent installing bd, tracking work, and syncing it. Contributor-facing material lives in engdocs/ and AGENTS.md and follows different rules (it may describe the implementation literally). When this skill says "the docs," it means docs/.

1. The canonical model

Beads is a dependency-aware issue graph with a workflow layer on top. Teach it consistently and link to the canonical concept page — docs/core-concepts/index.md — rather than re-explaining it.

Concept	Role	Key idea
bead (issue)	the unit of work	one tracked item with a hash ID (bd-a1b2), type, status, priority; "bead" and "issue" name the same thing
dependency	ordering	blocks edges hide a bead from agents until its blockers close; parent-child, related, discovered-from organize without blocking
ready work	what bd ready computes	open beads with no open blockers, excluding in_progress, blocked, deferred, and hooked — the claimable frontier
formula	workflow source	a TOML/JSON file defining a DAG of steps; bd cook compiles it into a proto
proto	workflow template	a template epic (label template) with {{variables}}; not live work
molecule	instantiated workflow	real beads poured from a proto (bd mol pour); persistent
wisp	ephemeral molecule	same instantiation, transient lifecycle (bd mol wisp); purged by bd purge
gate	async wait	blocks a workflow step until closed — by a human, a timer, a GitHub run/PR, or a cross-rig bead
sync	cross-machine movement	Dolt push/pull over refs/dolt/data on the git remote; .beads/issues.jsonl is a passive export, never the database
federation	cross-repo sync	peer-to-peer sharing of beads across repos/organizations

The pipeline worth internalizing: formula → (cook) → proto → (pour) → molecule or → (wisp) → wisp. Gates pause molecule steps; bd ready surfaces the claimable steps; sync moves the whole graph between machines.