docs: canonical concept page, section overviews, and concept diagrams

- Rewrite docs/core-concepts/index.md as 'How Beads Works' — the one
  canonical concept page (modeled on Gas City's how-gas-city-works):
  problem-first framing, the bead -> dependencies -> ready-work loop, hash
  IDs, the formula -> proto -> molecule/wisp pipeline, gates, Dolt sync,
  federation, and storage modes, led by four mermaid diagrams. Other pages
  link here instead of re-deriving the model.
- Fact fixes caught while writing (verified against source/live help):
  hash IDs are content-derived SHA-256 (internal/types/id_generator.go),
  not random; bd pour/bd wisp/bd pin/bd hook are not commands (the real
  surface is bd mol pour, bd mol wisp, bd assign, bd update --claim);
  wisps are not stored in .beads-wisp/; cross-repo dependency syntax is
  external:<project>:<capability> (cmd/bd/dep.go); recovery index claimed
  SQLite errors in a Dolt product.
- Section overview pages: rewrite workflows/index, extend recovery,
  multi-agent, and integrations indexes to list every child with one-line
  summaries; add reference/index and put it in the nav.
- New concept diagrams: sequential-vs-hash ID merge collision
  (core-concepts/hash-ids) and embedded-vs-server mode
  (architecture/dolt).
- website/README.md: real build/verify instructions and parallel-run
  status for the Docusaurus site.
- Repoint example READMEs and page labels at the real quickstart page.
This commit is contained in:
Chris Sells 2026-07-10 18:13:05 -07:00
commit 54a7547b0d
16 changed files with 312 additions and 156 deletions

View file

@ -59,6 +59,18 @@ Migration creates backups automatically. Your original SQLite database is preser
## Modes of Operation
```mermaid
flowchart LR
subgraph embedded["Embedded mode (default) — bd init"]
bd1["bd process<br/>Dolt runs in-process"] --> d1[(".beads/embeddeddolt/<br/>single writer, file-locked")]
end
subgraph server["Server mode — bd init --server"]
bd2["bd (agent 1)"] --> srv["dolt sql-server"]
bd3["bd (agent 2)"] --> srv
srv --> d2[(".beads/dolt/<br/>concurrent writers")]
end
```
### Embedded Mode (Solo / Standalone)
In-process Dolt engine — no separate server needed. This is the default for

View file

@ -321,7 +321,7 @@ bd ready # Only "Design" is ready
## See Also
- [QUICKSTART.md](/getting-started/quickstart) — First steps with dependencies
- [Quick Start](/getting-started/quickstart) — First steps with dependencies
- [MOLECULES.md](/workflows/molecules) — Molecule workflows using gates and dependencies
- [MULTI_REPO_AGENTS.md](/multi-agent/coordination) — Cross-repo dependency patterns
- [DOLT.md](/architecture/dolt) — Dolt backend configuration

View file

@ -11,6 +11,18 @@ Traditional sequential IDs (`#1`, `#2`, `#3`) break when:
- Different branches have independent numbering
- Forks diverge and later merge
```mermaid
flowchart TD
subgraph seq["Sequential IDs — collision on merge"]
a1["agent A creates #7"] --> m1["merge: two different #7s ✗"]
b1["agent B creates #7"] --> m1
end
subgraph hash["Hash IDs — no coordination needed"]
a2["agent A creates bd-a1b2"] --> m2["merge: both IDs survive ✓"]
b2["agent B creates bd-f14c"] --> m2
end
```
## The Solution
Beads uses hash-based IDs:

View file

@ -1,72 +1,163 @@
---
title: Core Concepts
title: How Beads Works
description: The orientation for beads — the dependency-aware issue graph, what bd ready computes, the formula-to-molecule workflow pipeline, and how Dolt sync moves it all between machines.
---
Understanding the fundamental concepts behind beads.
Coding agents lose their memory every time a session ends. Markdown plans rot,
TODO comments scatter, and a crashed agent takes its context with it. Beads
replaces that with a **persistent, structured work graph**: every unit of work
is a **bead** (an issue) in a version-controlled database, connected by
dependencies, and `bd ready` computes exactly what can be worked on right now.
Work survives the agent; the next session picks up where the last one died.
## Design Philosophy
Beads was built with these principles:
1. **Dolt as source of truth** - Issues stored in a version-controlled SQL database (Dolt), enabling collaboration via Dolt-native replication
2. **AI-native workflows** - Hash-based IDs, JSON output, dependency-aware execution
3. **Local-first operation** - Dolt database for fast queries, background sync
4. **Declarative workflows** - Formulas define repeatable patterns
## Key Components
### Issues
Work items with:
- **ID** - Hash-based (e.g., `bd-a1b2`) or hierarchical (e.g., `bd-a1b2.1`)
- **Type** - `bug`, `feature`, `task`, `epic`, `chore`
- **Priority** - 0 (critical) to 4 (backlog)
- **Status** - `open`, `in_progress`, `closed`
- **Labels** - Flexible tagging
- **Dependencies** - Blocking relationships
### Dependencies
Four types of relationships:
| Type | Description | Affects Ready Queue |
|------|-------------|---------------------|
| `blocks` | Hard dependency (X blocks Y) | Yes |
| `parent-child` | Epic/subtask relationship | No |
| `discovered-from` | Track issues found during work | No |
| `related` | Soft relationship | No |
### Dolt Server Mode
Dolt provides the database backend for beads:
- Start with `bd dolt start`
- Handles auto-commit and sync
- Logs available at `.beads/dolt/sql-server.log`
- Check health with `bd doctor`
### Dolt Sync
The synchronization mechanism:
```
Dolt DB (.beads/dolt/)
↕ dolt commit
Local Dolt history
↕ dolt push/pull
Remote Dolt repository
```mermaid
flowchart LR
create["bd create<br/>new bead"] --> graph["dependency<br/>graph"]
graph --> ready["bd ready<br/>claimable work"]
ready --> claim["bd update --claim<br/>agent takes it"]
claim --> close["bd close<br/>work done"]
close -->|blockers released| ready
```
### Formulas
The loop above is the whole product in miniature: creating and closing beads
reshapes the graph, and the graph — not a human dispatcher — decides what is
workable next.
Declarative workflow templates:
- Define steps with dependencies
- Variable substitution
- Gates for async coordination
- Aspect-oriented transformations
## Beads and dependencies
## Navigation
A **bead** is one tracked unit of work: a hash ID (`bd-a1b2`), a title, a
type (`bug`, `task`, `feature`, `epic`, `chore`, and friends — see
[`bd types`](/cli-reference/types)), a priority (`0` critical → `4` backlog),
and a status moving `open` → `in_progress` → `closed`. "Bead" and "issue"
name the same thing; the CLI says issue, the product says bead.
- [Issues & Dependencies](/core-concepts/issues)
- [Dolt Server Mode](#dolt-server-mode)
- [Dolt Sync](#dolt-sync)
- [Hash-based IDs](/core-concepts/hash-ids)
**Dependencies** connect beads into a graph. Only one edge type affects what
agents may work on:
| Type | Meaning | Affects ready work |
|------|---------|--------------------|
| `blocks` | hard ordering — the blocker must close first | **yes** |
| `parent-child` | epic/subtask structure | no |
| `discovered-from` | provenance — found while working on the parent | no |
| `related` | soft association | no |
Richer knowledge-graph edges (`relates_to`, `duplicates`, `supersedes`,
`replies_to`) are covered in [Graph Links](/core-concepts/graph-links).
## Ready work — what `bd ready` computes
**Ready work** is the claimable frontier of the graph: open beads with no
open blockers, excluding anything in progress, blocked, deferred, or held by
a gate. Agents never scan the whole tracker; they ask for the frontier and
claim atomically.
```mermaid
flowchart TD
A["bd-a1b2 · open<br/>design schema"] --> C["bd-c3d4 · open<br/>implement API"]
B["bd-b9f0 · closed<br/>pick database"] --> C
C --> D["bd-e5f6 · open<br/>write e2e tests"]
E["bd-77aa · open<br/>update README"]
classDef ready fill:#2e8555,color:#fff,stroke:#205d3b
classDef blocked fill:#eee,color:#888,stroke:#bbb
classDef done fill:#fff,color:#888,stroke:#2e8555,stroke-dasharray: 5 5
class A,E ready
class C,D blocked
class B done
```
Here `bd ready` returns `bd-a1b2` and `bd-77aa` — everything else is either
closed or waiting on an open blocker. Closing `bd-a1b2` makes `bd-c3d4`
ready; nothing needs re-planning.
```bash
bd ready --json # the claimable frontier, machine-readable
bd ready --claim --json # atomically claim the first match
```
## Hash IDs — why agents never collide
IDs like `bd-a1b2` are content-derived hashes (of title, description,
creation time, and workspace), not sequence numbers. Two agents (or two
branches) creating beads at the same time cannot mint the same ID, so merges
never renumber work. The hash length extends automatically on collision and
scales with database size — see
[Hash IDs](/core-concepts/hash-ids) and
[Adaptive ID Length](/core-concepts/adaptive-ids).
## Workflows — formula → proto → molecule
Repeatable multi-step work is declared once and stamped out on demand:
```mermaid
flowchart LR
formula["formula<br/>(TOML file)"] -->|bd cook| proto["proto<br/>(template epic)"]
proto -->|bd mol pour| mol["molecule<br/>(persistent beads)"]
proto -->|bd mol wisp| wisp["wisp<br/>(ephemeral beads)"]
gate["gate<br/>(async wait)"] -.blocks a step.-> mol
```
- A **formula** is the source: a TOML/JSON file defining a DAG of steps —
see [Formulas](/workflows/formulas).
- Cooking compiles it into a **proto**: a template epic with
`{{variables}}`, not yet live work.
- Pouring instantiates a **molecule**: real beads whose steps flow through
`bd ready` like any other work — see [Molecules](/workflows/molecules).
- A **wisp** is the same instantiation with an ephemeral lifecycle — gone at
the next `bd purge` — see [Wisps](/workflows/wisps).
- A **gate** parks a step until something external happens: a human sign-off,
a timer, a GitHub run or PR, or a bead closing in another repo — see
[Gates](/workflows/gates).
## Sync — how work moves between machines
Beads stores everything in [Dolt](https://github.com/dolthub/dolt), a
version-controlled SQL database. Every write auto-commits to Dolt history;
sync is native push/pull, piggybacking on your existing git remote under a
separate ref — no server to run.
```mermaid
flowchart LR
subgraph you["your machine"]
db[("Dolt DB<br/>.beads/embeddeddolt/")]
end
subgraph remote["git remote (origin)"]
ref[("refs/dolt/data")]
end
subgraph teammate["teammate / other clone"]
db2[("Dolt DB")]
end
db -->|bd dolt push| ref
ref -->|bd dolt pull| db
db2 <-->|push / pull| ref
```
`.beads/issues.jsonl` is a passive export for viewers and interchange — it
is not the database, not the sync protocol, and not a backup. The full model
(and its anti-patterns) is in [Sync Concepts](/core-concepts/sync-concepts);
**federation** — peer-to-peer sharing across repos and organizations — is in
[Federation](/multi-agent/federation).
## Storage modes
| Mode | Command | Data lives at | Writers |
|------|---------|---------------|---------|
| **Embedded** (default) | `bd init` | `.beads/embeddeddolt/` | one (file-locked) |
| **Server** | `bd init --server` | `.beads/dolt/` | many concurrent |
Embedded runs Dolt in-process and is right for almost everyone; server mode
connects to an external `dolt sql-server` for multi-writer setups. Other SQL
backends exist without Dolt's history — see
[Storage Backends](/architecture/storage-backends) and the
[architecture overview](/architecture/index).
## Where to go next
- [Quick Start](/getting-started/quickstart) — install, create, claim, and
close your first beads.
- [Issues & Dependencies](/core-concepts/issues) — field-level detail on
beads and their relationships.
- [Workflows](/workflows/index) — molecules, formulas, gates, and wisps in
depth.
- [Multi-Agent](/multi-agent/index) — routing, coordination, and federation
for fleets of agents.

View file

@ -246,6 +246,7 @@
{
"group": "Reference",
"pages": [
"reference/index",
"reference/configuration",
"reference/git-integration",
"reference/worktrees",

View file

@ -279,7 +279,7 @@ bd dolt start
## See Also
- [SYNC_CONCEPTS.md](/core-concepts/sync-concepts) — The conceptual model behind this setup (why Dolt is the source of truth, what JSONL is for)
- [QUICKSTART.md](/getting-started/quickstart) — Getting started with beads
- [Quick Start](/getting-started/quickstart) — Getting started with beads
- [DOLT.md](/architecture/dolt) — Dolt backend details, server modes, federation, remote types, and sync modes
- [INSTALLING.md](/getting-started/installation) — Installation for all platforms

View file

@ -34,5 +34,16 @@ bd setup --list
These integrations use the Beads MCP server rather than a dedicated `bd setup` recipe:
- [MCP Server](/integrations/mcp-server)
- [GitHub Copilot](/integrations/github-copilot)
- [MCP Server](/integrations/mcp-server) — the beads MCP server for any
MCP-capable client.
- [GitHub Copilot](/integrations/github-copilot) — Copilot in VS Code via
MCP.
- [GitHub Copilot CLI](/integrations/copilot-cli) — the Copilot coding-agent
CLI.
## Other Integration Surfaces
- [Claude Code Plugin](/integrations/claude-code-plugin) — the packaged
plugin with slash commands and MCP tools (`/plugin install beads`).
- [Azure DevOps](/integrations/azure-devops) — configuration reference for
syncing beads with ADO work items.

View file

@ -25,11 +25,12 @@ Routes define which repository handles which issues:
### Work Assignment
Pin work to specific agents:
Assign or atomically claim work:
```bash
bd pin bd-42 --for agent-1 --start
bd hook --agent agent-1 # Show pinned work
bd assign bd-42 agent-1 # shorthand for bd update bd-42 --assignee agent-1
bd update bd-42 --claim # atomically set assignee + in_progress
bd ready --claim --json # claim the first ready match
```
### Cross-repo Dependencies
@ -37,7 +38,7 @@ bd hook --agent agent-1 # Show pinned work
Track dependencies across repositories:
```bash
bd dep add bd-42 external:other-repo/bd-100
bd dep add bd-42 external:other-repo:api-ready
```
## Architecture
@ -62,7 +63,13 @@ bd dep add bd-42 external:other-repo/bd-100
2. **Multi-repo**: Configure routes and cross-repo deps
3. **Multi-agent**: Add work assignment and handoff
## Navigation
## Pages in this section
- [Routing](/multi-agent/routing) - Auto-routing configuration
- [Coordination](/multi-agent/coordination) - Agent coordination patterns
- [Routing](/multi-agent/routing) — automatic issue routing across
repositories and `BEADS_DIR` resolution.
- [Coordination](/multi-agent/coordination) — work assignment and handoff
patterns between agents.
- [Federation](/multi-agent/federation) — peer-to-peer sharing of beads
across repos and organizations.
- [Multi-Repo Migration](/multi-agent/multi-repo-migration) — moving an
existing single-repo setup to multi-repo routing.

View file

@ -12,7 +12,7 @@ This guide helps you adopt beads' multi-repo workflow for OSS contributions, tea
- [Multi-Phase Development](#multi-phase-development) - Separate repos per phase
- [Multiple Personas](#multiple-personas) - Architect vs. implementer separation
**New to beads?** See [QUICKSTART.md](/getting-started/quickstart) first.
**New to beads?** See [Quick Start](/getting-started/quickstart) first.
## What is Multi-Repo Mode?

View file

@ -9,10 +9,12 @@ This section provides step-by-step recovery procedures for common Beads issues.
| Issue | Symptoms | Runbook |
|-------|----------|---------|
| Database Corruption | SQLite errors, missing data | [Database Corruption](/recovery/database-corruption) |
| Init Safety Refusals | `bd init` or `bd dolt` refuses with a pattern code like `pk-fork-refused` | [Recovery Playbooks](/recovery/init-safety) |
| Database Corruption | Database errors, missing data | [Database Corruption](/recovery/database-corruption) |
| Merge Conflicts | Dolt conflicts during sync | [Merge Conflicts](/recovery/merge-conflicts) |
| Circular Dependencies | Cycle detection errors | [Circular Dependencies](/recovery/circular-dependencies) |
| Sync Failures | `bd dolt push`/`bd dolt pull` errors | [Sync Failures](/recovery/sync-failures) |
| Removing beads | Uninstall bd or strip beads from a repo | [Uninstalling](/recovery/uninstalling) |
## Quick Diagnostic

30
docs/reference/index.md Normal file
View file

@ -0,0 +1,30 @@
---
title: Reference
description: Lookup material — configuration, git integration, JSON contracts, observability, troubleshooting, and the FAQ.
---
Lookup material for beads: the pages here specify contracts and edge cases
rather than teach concepts (that's [How Beads Works](/core-concepts/index)).
## Pages in this section
- [Configuration](/reference/configuration) — every config key, environment
variable, default, and the precedence between them.
- [Git Integration](/reference/git-integration) — hooks, `refs/dolt/data`,
role detection, and branchless (jujutsu) workflows.
- [Git Worktrees Guide](/reference/worktrees) — how beads behaves across
worktrees sharing one repository.
- [Protected Branches](/reference/protected-branches) — sync-branch mode for
repos where direct pushes to main are blocked.
- [Advanced Features](/reference/advanced) — rename, merge, compaction, and
other power-user operations.
- [JSON Output Schema Contract](/reference/json-schema) — the stability
contract behind every `--json` flag.
- [Observability (OpenTelemetry)](/reference/observability) — traces and
metrics bd can emit, and how to point them at a collector.
- [Troubleshooting](/reference/troubleshooting) — symptom-first fixes for
common failures (deeper runbooks live in [Recovery](/recovery/index)).
- [Antivirus False Positives](/reference/antivirus) — Windows AV heuristics
and binary verification.
- [FAQ](/reference/faq) — beads vs other trackers, and the questions
everyone asks in week one.

View file

@ -1,90 +1,40 @@
---
title: Workflows
description: Declare multi-step work once as a formula, then stamp it out as molecules of real, dependency-ordered beads.
---
Beads provides powerful workflow primitives for complex, multi-step processes.
## Chemistry Metaphor
Beads uses a molecular chemistry metaphor:
| Phase | Storage | Synced | Use Case |
|-------|---------|--------|----------|
| **Proto** (solid) | Built-in | N/A | Reusable templates |
| **Mol** (liquid) | `.beads/` | Yes | Persistent work |
| **Wisp** (vapor) | `.beads-wisp/` | No | Ephemeral operations |
## Core Concepts
### Formulas
Declarative workflow templates in TOML or JSON:
```toml
formula = "feature-workflow"
version = 1
type = "workflow"
[[steps]]
id = "design"
title = "Design the feature"
type = "human"
[[steps]]
id = "implement"
title = "Implement the feature"
needs = ["design"]
```
### Molecules
Work graphs with parent-child relationships:
- Created by instantiating formulas with `bd pour`
- Steps have dependencies (`needs`)
- Progress tracked via issue status
### Gates
Async coordination primitives:
- **Human gates** - Wait for human approval
- **Timer gates** - Wait for duration
- **GitHub gates** - Wait for PR merge, CI, etc.
### Wisps
Ephemeral operations that don't sync to git:
- Created with `bd wisp`
- Stored in `.beads-wisp/` (gitignored)
- Auto-expire after completion
## Workflow Commands
| Command | Description |
|---------|-------------|
| `bd pour` | Instantiate formula as molecule |
| `bd wisp` | Create ephemeral wisp |
| `bd mol list` | List molecules |
| `bd pin` | Pin work to agent |
| `bd hook` | Show pinned work |
## Simple Example
Repeatable multi-step work — a release checklist, a feature pipeline, a
review process — shouldn't be re-planned by hand every time. Beads lets you
declare the shape once and instantiate it on demand: a **formula** (TOML
source) is cooked into a **proto** (template), and the proto is poured into a
**molecule** — real beads whose steps flow through `bd ready` like any other
work. The full pipeline is diagrammed in
[How Beads Works](/core-concepts/index).
```bash
# Create a release workflow
bd pour release --var version=1.0.0
# View the molecule
bd mol show release-1.0.0
# Work through steps
bd update release-1.0.0.1 --claim
bd close release-1.0.0.1
# Next step becomes ready...
bd formula list # formulas visible on the search paths
bd cook release.formula.toml # compile the formula into a proto
bd mol pour release --var version=1.2.0 # instantiate real work
bd ready --mol <mol-id> # which steps can run right now
```
## Navigation
The three phases, in the chemistry metaphor the CLI uses:
- [Molecules](/workflows/molecules) - Work graphs and execution
- [Formulas](/workflows/formulas) - Declarative templates
- [Gates](/workflows/gates) - Async coordination
- [Wisps](/workflows/wisps) - Ephemeral operations
| Phase | What it is | Lifecycle |
|-------|------------|-----------|
| **Proto** (solid) | template epic with `{{variables}}`, carries the `template` label | reusable, not live work |
| **Molecule** (liquid) | persistent beads poured from a proto (`bd mol pour`) | synced like any bead |
| **Wisp** (vapor) | ephemeral instantiation (`bd mol wisp`) | excluded from federation push by default; deleted by `bd purge` |
## Pages in this section
- [Molecules](/workflows/molecules) — instantiated work graphs: pouring,
inspecting, bonding, and squashing molecules.
- [Formulas](/workflows/formulas) — the TOML/JSON source format: steps,
`needs` dependencies, variables, and composition rules.
- [Gates](/workflows/gates) — async wait conditions (human, timer, GitHub
run/PR, cross-rig bead) that park a step until the world catches up.
- [Wisps](/workflows/wisps) — ephemeral molecules for transient operational
work that shouldn't clutter history.
- [TODO Command](/workflows/todo) — `bd todo`, the lightweight interface for
managing TODO items as task beads.

View file

@ -237,4 +237,4 @@ This pattern is used in production by:
## See Also
- [../../README.md](../../README.md) - bd documentation
- [QUICKSTART.md](../../docs/QUICKSTART.md) - Quick start tutorial
- [quickstart](../../docs/getting-started/quickstart.md) - Quick start tutorial

View file

@ -276,4 +276,4 @@ jobs:
- [docs/reference/protected-branches.md](../../docs/reference/protected-branches.md) - Complete guide
- [AGENTS.md](../../AGENTS.md) - Agent integration instructions
- [docs/QUICKSTART.md](../../docs/QUICKSTART.md) - `bd dolt push` / `bd dolt pull` usage
- [docs/getting-started/quickstart.md](../../docs/getting-started/quickstart.md) - `bd dolt push` / `bd dolt pull` usage

View file

@ -42,6 +42,7 @@ var docsPublishExemptions = map[string]bool{
"PLUGIN.md": true, // pointer stub; bd doctor output references it
"RECOVERY.md": true, // pointer stub; bd dolt output references its runbook anchors
"JSON_SCHEMA.md": true, // pointer stub; bd schema-migration output references it
"SYNC_CONCEPTS.md": true, // pointer stub; bd init agent templates link it on GitHub
}
// rootDocFiles are the curated root-level markdown files whose local links

View file

@ -1 +1,40 @@
# Beads Documentation Site
# Beads Documentation Site (Docusaurus)
This is the Docusaurus site behind https://gastownhall.github.io/beads/.
> **Status: parallel-run.** The docs are being migrated to a Mintlify site
> that lives in `docs/` (preview with `../mint.sh dev`). This Docusaurus site
> keeps building and deploying until the cutover, after which `website/` and
> `.github/workflows/deploy-docs.yml` retire. Author new content in `docs/`;
> only fix things here that break the still-live site.
## Local development
```bash
cd website
npm ci
npm start # dev server with hot reload at http://localhost:3000
```
## Build and verify
```bash
npm run typecheck # TS config sanity
npm run build # production build into website/build/
npm run serve # serve the production build locally
```
The CI package gate is `make ci-website` from the repo root (npm ci,
typecheck, `scripts/generate-llms-full.sh`, build). The Pages deploy runs
from `.github/workflows/deploy-docs.yml` on pushes to `main` that touch
`website/**`.
## Generated content
- `website/docs/cli-reference/` and the versioned CLI snapshots are emitted
by `bd help --docs-root` via `scripts/generate-cli-docs.sh` — never edit
them by hand.
- `website/static/llms-full.txt` and `llms.txt` come from
`scripts/generate-llms-full.sh`.
- Doc versions live in `website/versioned_docs/` (managed by
`npm run docusaurus docs:version <x.y.z>` at release time).