/beads-docs

name: beads-docs
description: >-
  Project conventions for writing, editing, restructuring, or reviewing the
  beads user documentation — the Mintlify site under docs/. Use this whenever
  you touch anything in docs/ (pages, concept docs, reference, integration
  guides, recovery runbooks, diagrams, docs.json navigation) or write/edit
  prose about beads, even when the request is just "fix the docs", "write a
  docs page", "the docs are wrong/confusing", "rename X across the docs", or
  an edit to a file under docs/. It defines the canonical concept model
  (bead → dependencies → ready work; formula → proto → molecule/wisp; gates;
  Dolt sync and federation), required terminology, the prose/emphasis/diagram
  conventions, the rule that generated docs are edited at their source, and
  the gates to run before docs work is done.

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.

Storage facts that pages keep getting wrong: embedded mode (the default `bd init`) stores data at `.beads/embeddeddolt/`; server mode (`bd init --server`) uses `.beads/dolt/`. Never present `.beads/dolt/` as the general data path.

**Cross-project vocabulary (beads ↔ Gas City).** Gas City (the sibling project) shares the words molecule, formula, wisp, and gate, but the two doc corpora use them differently: Gas City's docs treat molecule/wisp as v1 implementation detail (never a user concept), and a Gas City formula is an orchestration method the orchestrator runs across agents. In beads, molecule/wisp/proto ARE user concepts, and a formula is the TOML source you cook into a proto. Never import Gas City's definitions into beads pages (or vice versa); when a page must bridge the two projects, say explicitly which project's sense is meant.

2. Required terminology

Use the left column; never the right (except as noted). The full prose-vs-literal rename discipline is in [references/terminology.md](references/terminology.md).

| Use this | Not this | Notes | |---|---|---| | **bead** / **issue** | "task", "ticket", "TODO item" as the unit's name | Both terms are correct and interchangeable; lead with *bead* when teaching identity, use *issue* when mirroring CLI output or flags (`bd create`, "issue types"). "task" is one issue *type*, never the generic unit. | | **ready work** | "unblocked queue", "available tasks", "the ready set" as a formal term | Say what `bd ready` returns: open beads with no open blockers. | | **proto** | "template" as a noun for the concept | `template` stays only as the literal label name protos carry. | | **molecule** | "mol" in prose | `mol` is the command literal (`bd mol pour`); the concept is a molecule. | | **formula** | conflating formula with molecule/proto | The formula is the *file*; cooking makes a proto; pouring makes live work. | | **gate** | "barrier", "checkpoint", "lock" | Gates are async wait conditions with types (human, timer, gh:run, gh:pr, bead). | | **sync** = Dolt push/pull | export/import as a sync workflow | `bd dolt push` / `bd dolt pull` over `refs/dolt/data`. `.beads/issues.jsonl` is a passive export for viewers and interchange. | | **embedded mode** / **server mode** | "local mode", "daemon mode" for storage | Embedded is the default; data at `.beads/embeddeddolt/`. Server mode connects to `dolt sql-server`; data at `.beads/dolt/`. | | **federation** | "multi-repo sync" as a distinct feature name | Federation is the peer-to-peer cross-repo sharing feature. | | **hash ID** | "random ID", "UUID" | IDs like `bd-a1b2` are content-derived hashes sized adaptively to prevent collisions. |

3. Content stan