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:
parent
473d7ce99a
commit
54a7547b0d
16 changed files with 312 additions and 156 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -246,6 +246,7 @@
|
|||
{
|
||||
"group": "Reference",
|
||||
"pages": [
|
||||
"reference/index",
|
||||
"reference/configuration",
|
||||
"reference/git-integration",
|
||||
"reference/worktrees",
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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?
|
||||
|
||||
|
|
|
|||
|
|
@ -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
30
docs/reference/index.md
Normal 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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue