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.

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 stance

- **Motivate before you mechanize.** Lead a page with the problem it solves,
  then the solution, then the mechanics. Never open on vocabulary.
- **Docs are not the project's history.** No `internal/*` package paths, no
  "this was removed in vX", no "(v0.20.1+)" gating on user pages — beads is a
  1.x product and pre-1.0 archaeology belongs in `engdocs/` or the CHANGELOG.
- **Lead with the value.** Beads' value is persistent, dependency-aware memory
  for coding agents — agents that survive context loss because the work graph
  outlives the session. The comparison framing (vs GitHub Issues, Jira,
  markdown TODO lists) is the best newcomer conversion tool; keep it early
  where it exists.
- **One concrete example beats three abstract sentences.** Where you assert a
  capability, show a `bd` invocation and what it prints.

## 4. I