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.

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. Information architecture

Navigation lives in docs/docs.json: Getting Started, Core Concepts, Architecture, Workflows, Recovery, Multi-Agent, Integrations, Community, and Reference — with the generated CLI Reference nested inside Reference as a collapsed sub-group.

• Every section has an index/Overview page that introduces the section in a sentence or two, then lists every child page with a one-line accurate summary and link.
• One page, one purpose. A page that tries to teach and specify does neither — split it and cross-link.
• Concept material is unified on core-concepts/index; don't re-derive the model on other pages — link to it.
• The repository map belongs in the README, not in docs/.

5. Prose doctrine — cut words, sharpen points

Most bloat is information stored in the wrong medium. Move it to a cheaper carrier, then delete what isn't pulling weight. Every page must stand alone — a reader landing cold needs a one-line setup, not a previous page.

Convert (move load off prose):

• A relationship or sequence → a diagram (mermaid renders natively; richer diagrams follow the Excalidraw pipeline — see §7).
• Parallel options/fields/comparisons → a table.
• "you run X, which does Y" narration → an annotated CLI snippet (show the command and its output, comment the interesting lines).
• Edge cases and deep mechanics → an <Accordion>, or a reference page. Keep the 80% case on the page.

Delete (the load was fake): throat-clearing openers ("In this section we'll…"), hedge chains ("generally / typically / in most cases"), restatement, narrating an artifact a snippet already shows, and adjectives standing in for evidence.

When you run a deliberate simplification pass, follow references/simplification.md — the per-page loop and the two guardrails that keep a trim honest: a loss-check (never drop a fact that lives nowhere else) and a fact-check (trimmed prose must not drift from the code).

6. Emphasis and formatting

• Bold names a term, on first mention only. Italic marks a property or contrast. ~1–2 marks per paragraph; never re-emphasize a term already introduced; never give one phrase both treatments.
• No body # H1 — the frontmatter title is the H1. Use ##/###.
• Links are root-relative and extensionless (/getting-started/quickstart). Links out of the site (engdocs/, repo files) use full GitHub URLs.
• Mintlify parses .md as MDX: no HTML comments ({/* … */} instead), and angle-bracket placeholders like <id> must stay inside backticks or code fences.
• Mintlify components (<Note>, <Tip>, <Warning>, <Accordion>) sparingly — they lose force with repetition.

7. Diagrams

Mermaid fences render natively — prefer them for graphs and flows. For richer diagrams use the Excalidraw pipeline: author the .excalidraw source under docs/diagrams/excalidraw/, render with make diagrams-excalidraw (source and rendered .svg are both committed), embed as /diagrams/excalidraw-rendered/<name>.svg with descriptive alt text, and keep labels short (a two-line "Name / role" beats a sentence crammed in a box). Two non-negotiables:

• Rasterize and look at every rendered diagram — text overflow and layout problems are invisible in a text diff.
• Diagrams and images cannot be reviewed in a diff. Render them and get the maintainer's approval before committing.

8. Generated content is edited at its source

Never hand-edit a generated file. The generated surfaces are:

• docs/cli-reference/*.md and the CLI Reference pages array inside docs/docs.json — bd emits vendor-neutral pages (bd help --docs-root, from the Cobra command strings in cmd/bd/*.go) into an uncommitted staging tree, and tools/docsmint post-processes them into the committed Mintlify form. bd itself never emits Mintlify (or any site-generator) specifics; that lives in docsmint.
• docs/CLI_REFERENCE.md — the single-file reference, emitted directly by bd help --docs-root.

To change wording in any of them, edit the Go source (Short:, Long:, Example: strings) and run ./scripts/generate-cli-docs.sh (which runs both stages). To change the Mintlify page form itself (comment markers, link style, nav), edit tools/docsmint and its tests. The drift gates (generate-cli-docs.sh --check, scripts/check-cli-docs-drift.sh in PR CI, and the docs-autofix bot) fail or auto-fix any hand edit.

The docs describe the pinned release, not main. docs/cli-docs.pin names the release tag the whole docs corpus targets; the pipeline builds bd from that tag and validates against it, so a Go-source edit on main shows up in the committed docs only after the pin is bumped (at release time, followed by a regeneration). Hand-written pages follow the same policy: document what the pinned release does, never main-only features. See engdocs/decisions/2026-07-17-docs-release-pin.md.

9. Verify before you call it done

Run the gates in references/verification.md. The short list: go test ./test/docsync (nav↔file sync + link conventions), ./scripts/generate-cli-docs.sh --check (generated docs fresh), ./scripts/check-doc-freshness.sh (Last reviewed markers), and a live preview with make docs-dev (or ./mint.sh dev) at localhost:3000.

When you move or remove a page: add a redirect to the redirects array in docs/docs.json, rewrite inbound links repo-wide (README, engdocs/, examples/, npm-package/, plugin resources — grep, don't guess), and check whether bd prints the old path (if so, fix the Go source and regenerate — never a pointer stub; decision 6 covers old routes with redirects).

10. Review and commit discipline

• Author → the maintainer reviews → commit on explicit approval. This matters most for diagrams and images, which can't be reviewed in a text diff.
• Group commits by audience: user docs (docs/) separate from contributor docs (engdocs/, AGENTS.md) separate from generator/Go changes.
• Track docs work as bd issues per AGENTS.md.