# Beads Documentation (Complete)

> This file contains the complete beads documentation for LLM consumption.
> Generated automatically from the documentation source files (version: 1.0.0).
> For the web version, visit: https://gastownhall.github.io/beads/

---

<document path="docs/intro.md">


# Beads Documentation

**Beads** (`bd`) is a Dolt-powered issue tracker designed for AI-supervised coding workflows.

## Why Beads?

Traditional issue trackers (Jira, GitHub Issues) weren't designed for AI agents. Beads was built from the ground up for:

- **AI-native workflows** - Hash-based IDs prevent collisions when multiple agents work concurrently
- **Dolt-backed storage** - Issues stored in a version-controlled SQL database, enabling collaboration via Dolt-native replication
- **Dependency-aware execution** - `bd ready` shows only unblocked work
- **Formula system** - Declarative templates for repeatable workflows
- **Multi-agent coordination** - Routing, gates, and molecules for complex workflows

## Quick Start

```bash
# Install via Homebrew (macOS/Linux)
brew install beads

# Or quick install (macOS/Linux/FreeBSD)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Initialize in your project
cd your-project
bd init --quiet

# Create your first issue
bd create "Set up database" -p 1 -t task

# See ready work
bd ready
```

## Core Concepts

| Concept | Description |
|---------|-------------|
| **Issues** | Work items with priorities, types, labels, and dependencies |
| **Dependencies** | `blocks`, `parent-child`, `discovered-from`, `related` |
| **Dolt Server** | Database server for multi-writer access and performance |
| **Formulas** | Declarative workflow templates (TOML or JSON) |
| **Molecules** | Work graphs with parent-child relationships |
| **Gates** | Async coordination primitives (human, timer, GitHub) |

## For AI Agents

Beads is optimized for AI coding agents:

```bash
# Always use --json for programmatic access
bd list --json
bd show bd-42 --json

# Track discovered work during implementation
bd create "Found bug in auth" --description="Details..." \
  --deps discovered-from:bd-100 --json

# Push changes at end of session
bd dolt push
```

See the [Claude Code integration](/integrations/claude-code) for detailed agent instructions.

## Architecture

```
Dolt DB (.beads/dolt/, gitignored)
    ↕ dolt commit
Local Dolt history
    ↕ dolt push/pull
Remote Dolt repository (shared across machines)
```

The magic is automatic synchronization via Dolt's version-controlled database with built-in replication.

## Next Steps

- [Installation](/getting-started/installation) - Get bd installed
- [Quick Start](/getting-started/quickstart) - Create your first issues
- [CLI Reference](/cli-reference) - All available commands
- [Workflows](/workflows) - Formulas, molecules, and gates

</document>

<document path="docs/getting-started/ide-setup.md">


# IDE Setup for AI Agents

Configure your IDE for optimal beads integration.

## Claude Code

The recommended approach for Claude Code:

```bash
# Setup Claude Code integration
bd setup claude
```

This installs:
- **SessionStart hook** - Runs `bd prime` when Claude Code starts
- **PreCompact hook** - Ensures `bd dolt push` before context compaction

**How it works:**
1. SessionStart hook runs `bd prime` automatically
2. `bd prime` injects ~1-2k tokens of workflow context
3. You use `bd` CLI commands directly
4. Git hooks auto-sync the database

**Verify installation:**
```bash
bd setup claude --check
```

### Manual Setup

If you prefer manual configuration, add to your Claude Code hooks:

```json
{
  "hooks": {
    "SessionStart": ["bd prime"],
    "PreCompact": ["bd dolt push"]
  }
}
```

## Cursor IDE

```bash
# Setup Cursor integration
bd setup cursor
```

This creates `.cursor/rules/beads.mdc` with beads-aware rules.

**Verify:**
```bash
bd setup cursor --check
```

## Aider

```bash
# Setup Aider integration
bd setup aider
```

This creates/updates `.aider.conf.yml` with beads context.

**Verify:**
```bash
bd setup aider --check
```

## GitHub Copilot

For VS Code with GitHub Copilot, use the MCP server:

```bash
# Install MCP server
uv tool install beads-mcp
```

Create `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```

**For all projects:** Add to VS Code user-level MCP config:

| Platform | Path |
|----------|------|
| macOS | `~/Library/Application Support/Code/User/mcp.json` |
| Linux | `~/.config/Code/User/mcp.json` |
| Windows | `%APPDATA%\Code\User\mcp.json` |

```json
{
  "servers": {
    "beads": {
      "command": "beads-mcp",
      "args": []
    }
  }
}
```

Initialize beads and reload VS Code:

```bash
bd init --quiet
```

See [GitHub Copilot Integration](/integrations/github-copilot) for detailed setup.

## Context Injection with `bd prime`

All integrations use `bd prime` to inject context:

```bash
bd prime
```

This outputs a compact (~1-2k tokens) workflow reference including:
- Available commands
- Current project status
- Workflow patterns
- Best practices

**Why context efficiency matters:**
- Compute cost scales with tokens
- Latency increases with context size
- Models attend better to smaller, focused contexts

## MCP Server (Alternative)

For MCP-only environments (Claude Desktop, no shell access):

```bash
# Install MCP server
pip install beads-mcp
```

Add to Claude Desktop config:
```json
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```

**Trade-offs:**
- Works in MCP-only environments
- Higher context overhead (10-50k tokens for tool schemas)
- Additional latency from MCP protocol

See [MCP Server](/integrations/mcp-server) for detailed configuration.

## Git Hooks

Ensure git hooks are installed for auto-sync:

```bash
bd hooks install
```

This installs:
- **pre-commit** - Validates changes before commit
- **post-merge** - Imports changes after pull
- **pre-push** - Ensures sync before push

**Check hook status:**
```bash
bd info  # Shows warnings if hooks are outdated
```

## Verifying Your Setup

Run a complete health check:

```bash
# Check version
bd version

# Check project health
bd doctor

# Check hooks
bd hooks status

# Check editor integration
bd setup claude --check   # or cursor, aider
```

</document>

<document path="docs/getting-started/installation.md">


# Installing bd

Complete installation guide for all platforms.

## Quick Install (Recommended)

### Homebrew (macOS/Linux)

```bash
brew install beads
```

**Why Homebrew?**
- Simple one-command install
- Automatic updates via `brew upgrade`
- No need to install Go
- Handles PATH setup automatically

### Quick Install Script (All Platforms)

```bash
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
```

The installer will:
- Detect your platform (macOS/Linux/FreeBSD, amd64/arm64)
- Install via `go install` if Go is available
- Fall back to building from source if needed
- Guide you through PATH setup if necessary

## Build Dependencies (go install / from source)

If you install via `go install` or build from source, you need system dependencies for CGO:

macOS (Homebrew):
```bash
brew install icu4c zstd
```

Linux (Debian/Ubuntu):
```bash
sudo apt-get install -y libicu-dev libzstd-dev
```

Linux (Fedora/RHEL):
```bash
sudo dnf install -y libicu-devel libzstd-devel
```

If you see `unicode/uregex.h` missing on macOS, `icu4c` is keg-only. Use:
```bash
ICU_PREFIX="$(brew --prefix icu4c)"
CGO_CFLAGS="-I${ICU_PREFIX}/include" CGO_CPPFLAGS="-I${ICU_PREFIX}/include" CGO_LDFLAGS="-L${ICU_PREFIX}/lib" go install github.com/steveyegge/beads/cmd/bd@latest
```

## Platform-Specific Installation

### macOS

**Via Homebrew** (recommended):
```bash
brew install beads
```

**Via go install**:
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```

**From source**:
```bash
git clone https://github.com/steveyegge/beads
cd beads
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```

### Linux

**Via Homebrew** (works on Linux too):
```bash
brew install beads
```

**Arch Linux** (AUR):
```bash
# Install from AUR
yay -S beads-git
# or
paru -S beads-git
```

**Via go install**:
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```

### FreeBSD

**Via quick install script**:
```bash
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
```

**Via go install**:
```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```

### Windows 11

Beads ships with native Windows support—no MSYS or MinGW required.

**Prerequisites:**
- [Go 1.24+](https://go.dev/dl/) installed (add `%USERPROFILE%\go\bin` to your `PATH`)
- Git for Windows

**Via PowerShell script**:
```pwsh
irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
```

The script installs a prebuilt Windows release if available. Go is only required for `go install` or building from source.

**Via go install**:
```pwsh
go install github.com/steveyegge/beads/cmd/bd@latest
```

If you see `unicode/uregex.h` missing while building, use the PowerShell install script instead.

## IDE and Editor Integrations

### CLI + Hooks (Recommended)

The recommended approach for Claude Code, Cursor, Windsurf, and other editors with shell access:

```bash
# 1. Install bd CLI (see Quick Install above)
brew install beads

# 2. Initialize in your project
cd your-project
bd init --quiet

# 3. Setup editor integration (choose one)
bd setup claude   # Claude Code - installs SessionStart/PreCompact hooks
bd setup cursor   # Cursor IDE - creates .cursor/rules/beads.mdc
bd setup aider    # Aider - creates .aider.conf.yml
```

**How it works:**
- Editor hooks/rules inject `bd prime` automatically on session start
- `bd prime` provides ~1-2k tokens of workflow context
- You use `bd` CLI commands directly
- Git hooks (installed by `bd init`) auto-sync the database

**Why this is recommended:**
- **Context efficient** - ~1-2k tokens vs 10-50k for MCP tool schemas
- **Lower latency** - Direct CLI calls, no MCP protocol overhead
- **Universal** - Works with any editor that has shell access

### MCP Server (Alternative)

Use MCP only when CLI is unavailable (Claude Desktop, Sourcegraph Amp without shell):

```bash
# Using uv (recommended)
uv tool install beads-mcp

# Or using pip
pip install beads-mcp
```

**Configuration for Claude Desktop** (macOS):

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```

## Verifying Installation

After installing, verify bd is working:

```bash
bd version
bd help
```

## Troubleshooting

### `bd: command not found`

bd is not in your PATH:

```bash
# Check if installed
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd

# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(go env GOPATH)/bin"
```

### `zsh: killed bd` or crashes on macOS

This is typically caused by CGO/SQLite compatibility issues:

```bash
# Build with CGO enabled
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
```

## Updating bd

### Quick install script (macOS/Linux/FreeBSD)

```bash
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
```

### PowerShell installer (Windows)

```pwsh
irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
```

### Homebrew

```bash
brew upgrade beads
```

### go install

```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```

For post-upgrade steps (hooks, migrations), see [Upgrading](/getting-started/upgrading).

## Next Steps

After installation:

1. **Initialize a project**: `cd your-project && bd init`
2. **Learn the basics**: See [Quick Start](/getting-started/quickstart)
3. **Configure your agent**: See [IDE Setup](/getting-started/ide-setup)

</document>

<document path="docs/getting-started/quickstart.md">


# Beads Quick Start

Get up and running with Beads in a few minutes.

## Why Beads?

Flat issue trackers (GitHub Issues, Jira, etc.) show you a list of open items. You pick one. But if that item depends on something else that isn't done yet, you've wasted time. Multiply this across a team of AI agents and humans, and you get thrashing.

Beads tracks **dependencies between issues** and computes a **ready queue** — only items with no active blockers appear. Here's the difference:

**Flat tracker (GitHub Issues):**
```
Open issues: Set up database, Create API, Add authentication
→ An agent picks "Add authentication" and gets stuck immediately
```

**Beads:**
```bash
$ bd ready
1. [P1] [task] bd-1: Set up database

$ bd ready --explain --json | jq '.blocked[0]'
{
  "id": "bd-3",
  "title": "Add authentication",
  "blocked_by": [{"id": "bd-2", "title": "Create API", "status": "open"}]
}
```

The agent picks the right task every time. No wasted cycles.

## Installation

Install `bd` using [the full installation guide](/getting-started/installation) (Homebrew, install script, npm, or `go install`).

**Developing in a clone of this repository:** use `make install` so the binary gets correct build metadata and a consistent install path. Avoid ad-hoc `go build` / `go install` without the Makefile unless you know what you are doing — see the repository `README` and `AGENTS.md`.

```bash
bd --help
```

## Initialize

First time in a repository:

```bash
# Basic setup (prompts for contributor mode)
bd init

# For AI agents (non-interactive)
bd init --quiet

# OSS contributor (fork workflow with separate planning repo)
bd init --contributor

# Team member (branch workflow for collaboration)
bd init --team

# Protected main branch (GitHub/GitLab)
# Note: Dolt stores data under refs/dolt/data, separate from
# Git refs, so no --branch flag is needed.
```

The wizard will:
- Create `.beads/` directory and embedded Dolt database
- **Prompt for your role** (maintainer or contributor) unless a flag is provided
- Import existing issues from git (if any)
- Prompt to install git hooks (recommended)
- Prompt to configure git merge driver (recommended)

Notes:
- Dolt is the default (and only) storage backend. Data is stored in `.beads/embeddeddolt/`.
- By default, Dolt runs in **embedded mode** (in-process, no server needed).
- For multi-writer setups, use `bd init --server` to connect to a `dolt sql-server` instead.
- To import issues from an older installation, run `bd init --from-jsonl`.

### Role configuration

During `bd init`, you'll be asked: "Contributing to someone else's repo? [y/N]"

- Answer **Y** if you're contributing to a fork (runs contributor wizard)
- Answer **N** if you're the maintainer or have push access

This sets `git config beads.role` which determines how beads routes issues:

| Role | Use case | Issue storage |
|------|----------|---------------|
| `maintainer` | Repo owner, team with push access | In-repo `.beads/` |
| `contributor` | Fork contributor, OSS contributor | Separate planning repo |

You can also configure manually:

```bash
# Set as contributor
git config beads.role contributor

# Set as maintainer
git config beads.role maintainer

# Check current role
git config --get beads.role
```

**Note:** If `beads.role` is not configured, beads falls back to URL-based detection (deprecated). Run `bd doctor` to check configuration status.

## Your first issues

```bash
# Create a few issues
bd create "Set up database" -p 1 -t task
bd create "Create API" -p 2 -t feature
bd create "Add authentication" -p 2 -t feature

# List them
bd list
```

**Note:** Issue IDs are hash-based (e.g., `bd-a1b2`, `bd-f14c`) to prevent collisions when multiple agents/branches work concurrently.

## Hierarchical issues (epics)

For large features, use hierarchical IDs to organize work:

```bash
# Create epic (generates parent hash ID)
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9

# Create child tasks (use --parent to attach to the epic)
bd create "Design login UI" -p 1 --parent bd-a3f8e9       # bd-a3f8e9.1
bd create "Backend validation" -p 1 --parent bd-a3f8e9    # bd-a3f8e9.2
bd create "Integration tests" -p 1 --parent bd-a3f8e9     # bd-a3f8e9.3

# View hierarchy
bd dep tree bd-a3f8e9
```

Output:
```
Dependency tree for bd-a3f8e9:

> bd-a3f8e9: Auth System [epic] [P1] (open)
  > bd-a3f8e9.1: Design login UI [P1] (open)
  > bd-a3f8e9.2: Backend validation [P1] (open)
  > bd-a3f8e9.3: Integration tests [P1] (open)
```

## Add dependencies

```bash
# API depends on database
bd dep add bd-2 bd-1

# Auth depends on API
bd dep add bd-3 bd-2

# View the tree
bd dep tree bd-3
```

Output:
```
Dependency tree for bd-3:

> bd-3: Add authentication [P2] (open)
  > bd-2: Create API [P2] (open)
    > bd-1: Set up database [P1] (open)
```

**Dependency visibility:** `bd list` shows blocking dependencies inline:
```
○ bd-a1b2 [P1] [task] - Set up database
○ bd-f14c [P2] [feature] - Create API (blocked by: bd-a1b2)
○ bd-g25d [P2] [feature] - Add authentication (blocked by: bd-f14c)
```

## Find ready work

```bash
bd ready
```

Output:
```
Ready work (1 issues with no blockers):

1. [P1] bd-1: Set up database
```

Only bd-1 is ready because bd-2 and bd-3 are blocked.

**Understanding why:** Use `--explain` to see the full graph reasoning:

```bash
bd ready --explain
```

Output:
```
Ready Work Explanation

● Ready (1 issues):

  bd-1 [P1] Set up database
    Reason: no blocking dependencies
    Unblocks: 1 issue(s)

● Blocked (2 issues):

  bd-2 [P2] Create API
    ← blocked by bd-1: Set up database [open]

  bd-3 [P2] Add authentication
    ← blocked by bd-2: Create API [open]

─ Summary: 1 ready, 2 blocked
```

**Note:** `bd ready` is not the same as `bd list --status open`. The `list` command shows all open issues regardless of blockers. The `ready` command computes the dependency graph and only shows truly unblocked work.

## Work the queue

```bash
# Start working on bd-1
bd update bd-1 --claim

# Complete it
bd close bd-1 --reason "Database setup complete"

# Check ready work again
bd ready
```

Now bd-2 is ready.

## Track progress

```bash
# See blocked issues
bd blocked

# View statistics
bd stats
```

## Team sync

Share issues with your team using Dolt remotes. Dolt stores data under `refs/dolt/data` on the same Git remote, separate from standard Git refs.

```bash
# Add a remote (GitHub example — also supports DoltHub, S3, GCS, local paths)
bd dolt remote add origin git+ssh://git@github.com/org/repo.git

# Push your issues
bd dolt push

# Pull teammates' changes
bd dolt pull
```

When a teammate clones the repo, `bd bootstrap` auto-detects the existing database on `refs/dolt/data` and clones it — no manual remote setup needed.

See [Sync](/cli-reference/sync) for CLI details. For remote configuration and federation, see the repository docs [DOLT-BACKEND.md](https://github.com/steveyegge/beads/blob/main/docs/DOLT-BACKEND.md) and [FEDERATION-SETUP.md](https://github.com/steveyegge/beads/blob/main/FEDERATION-SETUP.md).

## Optional: Notion sync

If you keep project issues in Notion, save an integration token first:

```bash
bd config set notion.token <your-token>
```

Then either create a new Beads database under a parent page or connect to an existing target:

```bash
bd notion init --parent <page-id>
# or
bd notion connect --url <notion-database-or-data-source-url>
```

The same auth value can also come from `NOTION_TOKEN`. Directly setting `notion.data_source_id` remains available as an escape hatch for advanced setups.

Check which auth source is active and whether the target schema is ready:

```bash
bd notion status
bd notion status --json
```

Preview or run sync:

```bash
bd notion sync --dry-run
bd notion sync
bd notion sync --pull
bd notion sync --push
```

## Database location

By default (embedded mode), data is stored in `.beads/embeddeddolt/` within your repository.
In server mode, data is managed by the external `dolt sql-server`.

## Migrating databases

After upgrading bd, use `bd migrate` to check for and migrate old database files:

```bash
# Inspect migration plan (AI agents)
bd migrate --inspect --json

# Check schema and config
bd info --schema --json

# Preview migration changes
bd migrate --dry-run

# Migrate old databases to beads.db
bd migrate

# Migrate and clean up old files
bd migrate --cleanup --yes
```

**AI agents:** Use `--inspect` to analyze migration safety before running. The system verifies required config keys and data integrity invariants.

## Database maintenance

As your project accumulates closed issues, the database grows. Manage size with these commands:

```bash
# View compaction statistics
bd admin compact --stats

# Preview compaction candidates (30+ days closed)
bd admin compact --analyze --json

# Apply agent-generated summary
bd admin compact --apply --id bd-42 --summary summary.txt

# Immediately delete closed issues (CAUTION: permanent!)
bd admin cleanup --force
```

**When to compact:**
- Database file > 10MB with many old closed issues
- After major project milestones when old issues are no longer relevant
- Before archiving a project phase

**Note:** Compaction is permanent graceful decay. Original content is discarded but viewable via `bd restore <id>` from git history.

## Next steps

- Add labels: `bd create "Task" -l "backend,urgent"`
- Filter ready work: `bd ready --priority 1`
- Explain the graph: `bd ready --explain`
- Check graph integrity: `bd graph check`
- Search issues: `bd list --status open`
- Detect cycles: `bd dep cycles`
- Gates for PR/CI sync: [Dependencies](/cli-reference/dependencies)
- More sync scenarios: [Sync](/cli-reference/sync)
- Full command list: [CLI Reference](/cli-reference)

See the [repository README](https://github.com/steveyegge/beads/blob/main/README.md) for an overview and links to deeper docs.

</document>

<document path="docs/getting-started/upgrading.md">


# Upgrading bd

How to upgrade bd and keep your projects in sync.

## Checking for Updates

```bash
# Current version
bd version

# What's new in recent versions
bd info --whats-new
bd info --whats-new --json  # Machine-readable
```

## Upgrading

Use the command that matches your install method.

| Install method | Platforms | Command |
|---|---|---|
| Quick install script | macOS, Linux, FreeBSD | `curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh \| bash` |
| PowerShell installer | Windows | `irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 \| iex` |
| Homebrew | macOS, Linux | `brew upgrade beads` |
| go install | macOS, Linux, FreeBSD, Windows | `go install github.com/steveyegge/beads/cmd/bd@latest` |
| npm | macOS, Linux, Windows | `npm update -g @beads/bd` |
| bun | macOS, Linux, Windows | `bun install -g --trust @beads/bd` |
| From source (Unix shell) | macOS, Linux, FreeBSD | `git pull && go build -o bd ./cmd/bd` |

### Quick install script (macOS/Linux/FreeBSD)

```bash
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
```

### PowerShell installer (Windows)

```pwsh
irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
```

### Homebrew

```bash
brew upgrade beads
```

### go install

```bash
go install github.com/steveyegge/beads/cmd/bd@latest
```

### From Source

```bash
cd beads
git pull
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
```

## After Upgrading

**Important:** After upgrading, update your hooks:

```bash
# 1. Check what changed
bd info --whats-new

# 2. Update git hooks to match new version
bd hooks install

# 3. Check for any outdated hooks
bd info  # Shows warnings if hooks are outdated

# 4. If using Dolt backend, restart the server
bd dolt stop && bd dolt start
```

**Why update hooks?** Git hooks are versioned with bd. Outdated hooks may miss new auto-sync features or bug fixes.

## Database Migrations

After major upgrades, check for database migrations:

```bash
# Inspect migration plan (AI agents)
bd migrate --inspect --json

# Preview migration changes
bd migrate --dry-run

# Apply migrations
bd migrate

# Migrate and clean up old files
bd migrate --cleanup --yes
```

## Troubleshooting Upgrades

### Hooks out of date

```bash
bd hooks install
```

### Database schema changed

```bash
bd migrate --dry-run
bd migrate
```

### Recovery after upgrade

If you need to restore from a backup:

```bash
bd init
bd backup restore [path] --force
```

Or pull from a Dolt remote:

```bash
bd dolt pull
```

</document>

<document path="docs/core-concepts/index.md">


# Core Concepts

Understanding the fundamental concepts behind beads.

## 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
```

### Formulas

Declarative workflow templates:
- Define steps with dependencies
- Variable substitution
- Gates for async coordination
- Aspect-oriented transformations

## Navigation

- [Issues & Dependencies](/core-concepts/issues)
- [Dolt Server Mode](#dolt-server-mode)
- [Dolt Sync](#dolt-sync)
- [Hash-based IDs](/core-concepts/hash-ids)

</document>

<document path="docs/core-concepts/hash-ids.md">


# Hash-based IDs

Understanding beads' collision-resistant ID system.

## The Problem

Traditional sequential IDs (`#1`, `#2`, `#3`) break when:
- Multiple agents create issues simultaneously
- Different branches have independent numbering
- Forks diverge and later merge

## The Solution

Beads uses hash-based IDs:

```
bd-a1b2c3    # Short hash
bd-f14c      # Even shorter
bd-a3f8e9.1  # Hierarchical (child of bd-a3f8e9)
```

**Properties:**
- Globally unique (content-based hash)
- No coordination needed between creators
- Merge-friendly across branches
- Predictable length (configurable)

## How Hashes Work

IDs are generated from:
- Issue title
- Creation timestamp
- Random salt

```bash
# Create issue - ID assigned automatically
bd create "Fix authentication bug"
# Returns: bd-7x2f

# The ID is deterministic for same content+timestamp
```

## Hierarchical IDs

For epics and subtasks:

```bash
# Parent epic
bd create "Auth System" -t epic
# Returns: bd-a3f8e9

# Children auto-increment
bd create "Design UI" --parent bd-a3f8e9    # bd-a3f8e9.1
bd create "Backend" --parent bd-a3f8e9      # bd-a3f8e9.2
bd create "Tests" --parent bd-a3f8e9        # bd-a3f8e9.3
```

Benefits:
- Clear parent-child relationship
- No namespace collision (parent hash is unique)
- Up to 3 levels of nesting

## ID Configuration

Configure ID prefix and length:

```bash
# Set prefix (default: bd)
bd config set id.prefix myproject

# Set hash length (default: 4)
bd config set id.hash_length 6

# New issues use new format
bd create "Test"
# Returns: myproject-a1b2c3
```

## Collision Handling

While rare, collisions are handled automatically:

1. On import, if hash collision detected
2. Beads appends disambiguator
3. Both issues preserved

```bash
# Check for collisions
bd info --schema --json | jq '.collision_count'
```

## Working with IDs

```bash
# Partial ID matching
bd show a1b2     # Finds bd-a1b2...
bd show auth     # Fuzzy match by title

# Full ID required for ambiguous cases
bd show bd-a1b2c3d4

# List with full IDs
bd list --full-ids
```

## Migration from Sequential IDs

If migrating from a system with sequential IDs:

```bash
# Bootstrap from a JSONL export (preserves original IDs in metadata)
bd init --from-jsonl old-issues.jsonl

# View original ID
bd show bd-new --json | jq '.original_id'
```

## Best Practices

1. **Use short references** - `bd-a1b2` is usually unique enough
2. **Use `--json` for scripts** - Parse full ID programmatically
3. **Reference by hash in commits** - `Fixed bd-a1b2` in commit messages
4. **Let hierarchies form naturally** - Create epics, add children as needed

</document>

<document path="docs/core-concepts/issues.md">


# Issues & Dependencies

Understanding the issue model in beads.

## Issue Structure

Every issue has:

```bash
bd show bd-42 --json
```

```json
{
  "id": "bd-42",
  "title": "Implement authentication",
  "description": "Add JWT-based auth",
  "type": "feature",
  "status": "open",
  "priority": 1,
  "labels": ["backend", "security"],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

## Issue Types

| Type | Use Case |
|------|----------|
| `bug` | Something broken that needs fixing |
| `feature` | New functionality |
| `task` | Work item (tests, docs, refactoring) |
| `epic` | Large feature with subtasks |
| `chore` | Maintenance (dependencies, tooling) |

## Priorities

| Priority | Level | Examples |
|----------|-------|----------|
| 0 | Critical | Security, data loss, broken builds |
| 1 | High | Major features, important bugs |
| 2 | Medium | Nice-to-have features, minor bugs |
| 3 | Low | Polish, optimization |
| 4 | Backlog | Future ideas |

## Creating Issues

```bash
# Basic issue
bd create "Fix login bug" -t bug -p 1

# With description
bd create "Add password reset" \
  --description="Users need to reset forgotten passwords via email" \
  -t feature -p 2

# With labels
bd create "Update dependencies" -t chore -l "maintenance,security"

# JSON output for agents
bd create "Task" -t task --json
```

## Dependencies

### Blocking Dependencies

The `blocks` relationship affects the ready queue:

```bash
# Add dependency: bd-2 depends on bd-1
bd dep add bd-2 bd-1

# View dependencies
bd dep tree bd-2

# See blocked issues
bd blocked

# See ready work (not blocked)
bd ready
```

### Structural Relationships

These don't affect the ready queue:

```bash
# Parent-child (epic subtasks)
bd create "Epic" -t epic
bd create "Subtask" --parent bd-42

# Discovered-from (found during work)
bd create "Found bug" --deps discovered-from:bd-42

# Related (soft link)
bd relate bd-1 bd-2
```

### Dependency Types

| Type | Description | Ready Queue Impact |
|------|-------------|-------------------|
| `blocks` | Hard dependency | Yes - blocked items not ready |
| `parent-child` | Epic/subtask hierarchy | No |
| `discovered-from` | Tracks origin of discovery | No |
| `related` | Soft relationship | No |

## Hierarchical Issues

For large features, use hierarchical IDs:

```bash
# Create epic
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9

# Child tasks auto-number
bd create "Design login UI" --parent bd-a3f8e9     # bd-a3f8e9.1
bd create "Backend validation" --parent bd-a3f8e9  # bd-a3f8e9.2

# View hierarchy
bd dep tree bd-a3f8e9
```

## Updating Issues

```bash
# Change status
bd update bd-42 --claim

# Change priority
bd update bd-42 --priority 0

# Add labels
bd update bd-42 --add-label urgent

# Multiple changes
bd update bd-42 --claim --priority 1 --add-label "in-review"
```

## Closing Issues

```bash
# Simple close
bd close bd-42

# With reason
bd close bd-42 --reason "Implemented in PR #123"

# JSON output
bd close bd-42 --json
```

## Searching and Filtering

```bash
# By status
bd list --status open
bd list --status in_progress

# By priority
bd list --priority 1
bd list --priority 0,1  # Multiple

# By type
bd list --type bug
bd list --type feature,task

# By label
bd list --label-any urgent,critical
bd list --label-all backend,security

# Combined filters
bd list --status open --priority 1 --type bug --json
```

</document>

<document path="docs/architecture/index.md">


# Architecture Overview

This document explains how Beads' architecture works with Dolt as its storage backend.

## Architecture

Beads uses **Dolt** as its sole storage backend -- a version-controlled SQL database that provides git-like semantics (branch, merge, diff, push, pull) natively at the database level.

By default, Dolt runs in **embedded mode** (in-process, no separate server). For multi-writer
setups (multiple agents, orchestrator), switch to **server mode** which connects to a
running `dolt sql-server`. See the [Dolt Server Mode](#dolt-server-mode) section below for details.

```mermaid
flowchart TD
    subgraph DOLT["🗄️ Dolt Database"]
        D[(".beads/dolt/<br/><i>Version-Controlled SQL</i>")]
    end

    subgraph REMOTE["🌐 Dolt Remotes"]
        R[("DoltHub / S3 / GCS<br/><i>Sync & Backup</i>")]
    end

    D <-->|"bd dolt push/pull"| R

    U((User)) -->|"bd create<br/>bd update"| D
    D -->|"bd list<br/>bd show"| U

    style DOLT fill:#2d5a27,stroke:#4a9c3e,color:#fff
    style REMOTE fill:#1a4a6e,stroke:#3a8ac4,color:#fff
```

:::info Source of Truth
**Dolt** is the source of truth. Every write auto-commits to Dolt history, providing full version control, branching, and merge capabilities at the database level.

Recovery is straightforward: pull from a Dolt remote with `bd dolt pull`, or restore from a Dolt-native backup with `bd backup restore`.
:::

### Why Dolt?

- **Version-controlled SQL**: Full SQL queries with native version control
- **Cell-level merge**: Concurrent changes merge automatically at the field level
- **Multi-writer**: Server mode supports concurrent agents
- **Native branching**: Dolt branches independent of git branches
- **Works offline**: All queries run against local database
- **Portable**: `bd export` produces JSONL for migration and interoperability

## Data Flow

### Write Path
```text
User runs bd create
    → Dolt database updated
    → Auto-committed to Dolt history
```

### Read Path
```text
User runs bd list
    → Dolt SQL query
    → Results returned immediately
```

### Sync Path
```text
User runs bd dolt push
    → Commits pushed to Dolt remote

User runs bd dolt pull
    → Remote commits fetched and merged
```

### Multi-Machine Sync Considerations

When working across multiple machines or clones:

1. **Always sync before switching machines**
   ```bash
   bd dolt push  # Push changes before leaving
   ```

2. **Pull before creating new issues**
   ```bash
   bd dolt pull  # Pull changes first on new machine
   bd create "New issue"
   ```

3. **Avoid parallel edits** - If two machines create issues simultaneously without syncing, Dolt's cell-level merge handles most conflicts automatically

See [Sync Failures Recovery](/recovery/sync-failures) for data loss prevention in multi-machine workflows (Pattern A5/C3).

## Dolt Server Mode

The Dolt server handles background synchronization and database operations:

- Manages the Dolt database backend
- Handles auto-commit for change tracking
- Provides concurrent access for multiple agents
- Logs available at `.beads/dolt/sql-server.log`

:::tip
Start the Dolt server with `bd dolt start`. Check health with `bd doctor`.
:::

### Embedded Mode (No Server)

For CI/CD pipelines, containers, and single-use scenarios, no server is needed. Beads operates in embedded mode automatically when no Dolt server is running:

```bash
bd create "CI-generated issue"
bd dolt push
```

**When embedded mode is appropriate:**
- CI/CD pipelines (Jenkins, GitHub Actions)
- Docker containers
- Ephemeral environments
- Scripts that should not leave background processes

### Multi-Clone Scenarios

:::warning Race Conditions in Multi-Clone Workflows
When multiple git clones of the same repository run sync operations simultaneously, race conditions can occur during push/pull operations. This is particularly common in:
- Multi-agent AI workflows (multiple Claude/GPT instances)
- Developer workstations with multiple checkouts
- Worktree-based development workflows

**Prevention:**
1. Stop the Dolt server (`bd dolt stop`) before switching between clones
2. Dolt handles worktrees natively in server mode
3. Use embedded mode for automated workflows
:::

See [Sync Failures Recovery](/recovery/sync-failures) for sync race condition troubleshooting (Pattern B2).

## Recovery Model

Dolt's version control makes recovery straightforward:

1. **Lost database?** → Pull from Dolt remote: `bd dolt pull`
2. **Have a backup?** → Restore it: `bd backup restore [path] --force`
3. **Merge conflicts?** → Dolt handles cell-level merge natively

### Universal Recovery Sequence

The following sequence resolves the majority of reported issues. For detailed procedures, see [Recovery Runbooks](/recovery).

```bash
bd dolt stop                 # Stop Dolt server (prevents race conditions)
git worktree prune           # Clean orphaned worktrees
bd dolt pull                 # Pull from Dolt remote
bd dolt start                # Restart server
```

:::warning Use `bd doctor --fix` With Care
Always back up and preview before running `bd doctor --fix`:

1. **Back up first:** `cp -r .beads .beads.backup`
2. **Preview changes:** `bd doctor --dry-run` — shows what would be fixed without making changes
3. **Review diagnostics:** `bd doctor` (no flags) — diagnostic only, no changes made
4. **Then fix:** `bd doctor --fix` — or `bd doctor --fix -i` to confirm each fix individually

**Why caution?** The `--fix` flag may remove dependencies it flags as circular, including valid parent-child relationships. Use `--fix-child-parent` only if you're certain the flagged deps are invalid.

**Other diagnostic tools:**
- `bd blocked` — check which issues are blocked and why
- `bd show <issue-id>` — inspect a specific issue's state
:::

See [Recovery](/recovery) for specific procedures and [Database Corruption Recovery](/recovery/database-corruption) for Dolt recovery steps.

## Design Decisions

### Why Dolt?

Dolt is a version-controlled SQL database that provides git-like semantics natively. Unlike plain SQLite (binary merge conflicts) or JSONL (slow queries), Dolt gives you both fast SQL queries and proper merge semantics.

### Why not a cloud server?

Beads is designed for offline-first, local-first development. The Dolt server runs locally -- no cloud dependency, no downtime, no vendor lock-in, and full functionality on airplanes or in restricted networks.

### Trade-offs

| Benefit | Trade-off |
|---------|-----------|
| Works offline | No real-time collaboration |
| Version-controlled database | Requires Dolt server |
| Cell-level merge | Requires initial setup |
| Local-first speed | Manual sync to remotes |
| SQL queries | Dolt binary dependency |

### When NOT to use Beads

Beads is not suitable for:

- **Large teams (10+)** — Git-based sync doesn't scale well for high-frequency concurrent edits
- **Non-developers** — Requires Git and command-line familiarity
- **Real-time collaboration** — No live updates; requires explicit sync
- **Cross-repository tracking** — Issues are scoped to a single repository
- **Rich media attachments** — Designed for text-based issue tracking

For these use cases, consider GitHub Issues, Linear, or Jira.

## Related Documentation

- [Recovery Runbooks](/recovery) — Step-by-step procedures for common issues
- [CLI Reference](/cli-reference) — Complete command documentation
- [Getting Started](/) — Installation and first steps

</document>

<document path="docs/cli-reference/index.md">


# CLI Reference

Complete reference for all `bd` commands.

## Command Structure

```bash
bd [global-flags] <command> [command-flags] [arguments]
```

### Global Flags

| Flag | Description |
|------|-------------|
| `--db <path>` | Use specific database file |
| `--json` | Output in JSON format |
| `--quiet` | Suppress non-essential output |
| `--verbose` | Verbose output |
| `--version` | Show version |
| `--help` | Show help |

## Command Categories

### Essential Commands

Most frequently used:

| Command | Description |
|---------|-------------|
| `bd create` | Create new issue |
| `bd list` | List issues with filters |
| `bd show` | Show issue details |
| `bd update` | Update issue fields |
| `bd close` | Close an issue |
| `bd ready` | Show unblocked work |
| `bd dolt push` | Push changes to Dolt remote |
| `bd dolt pull` | Pull changes from Dolt remote |

### Issue Management

| Command | Description |
|---------|-------------|
| `bd create` | Create issue |
| `bd show` | Show details |
| `bd update` | Update fields |
| `bd close` | Close issue |
| `bd delete` | Delete issue |
| `bd reopen` | Reopen closed issue |

### Dependencies

| Command | Description |
|---------|-------------|
| `bd dep add` | Add dependency |
| `bd dep remove` | Remove dependency |
| `bd dep tree` | Show dependency tree |
| `bd dep cycles` | Detect circular dependencies |
| `bd blocked` | Show blocked issues |
| `bd ready` | Show unblocked issues |

### Labels & Comments

| Command | Description |
|---------|-------------|
| `bd label add` | Add label to issue |
| `bd label remove` | Remove label |
| `bd label list` | List all labels |
| `bd comment add` | Add comment |
| `bd comment list` | List comments |

### Sync & Export

| Command | Description |
|---------|-------------|
| `bd dolt push` | Push changes to Dolt remote |
| `bd dolt pull` | Pull changes from Dolt remote |
| `bd export` | Export data to JSONL |
| `bd migrate` | Migrate database schema |

### System

| Command | Description |
|---------|-------------|
| `bd init` | Initialize beads in project |
| `bd info` | Show system info |
| `bd version` | Show version |
| `bd config` | Manage configuration |
| `bd doctor` | Check system health |
| `bd hooks` | Manage git hooks |

### Workflows

| Command | Description |
|---------|-------------|
| `bd pour` | Instantiate formula as molecule |
| `bd wisp` | Create ephemeral wisp |
| `bd mol` | Manage molecules |
| `bd pin` | Pin work to agent |
| `bd hook` | Show pinned work |

## Quick Reference

### Creating Issues

```bash
# Basic
bd create "Title" -t task -p 2

# With description
bd create "Title" --description="Details here" -t bug -p 1

# With labels
bd create "Title" -l "backend,urgent"

# As child of epic
bd create "Subtask" --parent bd-42

# With discovered-from link
bd create "Found bug" --deps discovered-from:bd-42

# JSON output
bd create "Title" --json
```

### Querying Issues

```bash
# All open issues
bd list --status open

# High priority bugs
bd list --status open --priority 0,1 --type bug

# With specific labels
bd list --label-any urgent,critical

# JSON output
bd list --json
```

### Working with Dependencies

```bash
# Add: bd-2 depends on bd-1
bd dep add bd-2 bd-1

# View tree
bd dep tree bd-2

# Find cycles
bd dep cycles

# What's ready to work?
bd ready

# What's blocked?
bd blocked
```

### Syncing

```bash
# Push changes to Dolt remote
bd dolt push

# Pull changes from Dolt remote
bd dolt pull

# Export to file
bd export -o backup.jsonl
```

## See Also

- [Essential Commands](/cli-reference/essential)
- [Issue Commands](/cli-reference/issues)
- [Dependency Commands](/cli-reference/dependencies)
- [Label Commands](/cli-reference/labels)
- [Sync Commands](/cli-reference/sync)

</document>

<document path="docs/cli-reference/dependencies.md">


# Dependency Commands

Commands for managing issue dependencies.

## bd dep add

Add a dependency between issues.

```bash
bd dep add <dependent> <dependency> [flags]
```

**Semantics:** `<dependent>` depends on `<dependency>` (dependency blocks dependent).

**Flags:**
```bash
--type    Dependency type (blocks|related|discovered-from)
--json    JSON output
```

**Examples:**
```bash
# bd-2 depends on bd-1 (bd-1 blocks bd-2)
bd dep add bd-2 bd-1

# Soft relationship
bd dep add bd-2 bd-1 --type related

# JSON output
bd dep add bd-2 bd-1 --json
```

## bd dep remove

Remove a dependency.

```bash
bd dep remove <dependent> <dependency> [flags]
```

**Examples:**
```bash
bd dep remove bd-2 bd-1
bd dep remove bd-2 bd-1 --json
```

## bd dep tree

Display dependency tree.

```bash
bd dep tree <id> [flags]
```

**Flags:**
```bash
--depth    Maximum depth to display
--json     JSON output
```

**Examples:**
```bash
bd dep tree bd-42
bd dep tree bd-42 --depth 3
bd dep tree bd-42 --json
```

**Output:**
```
Dependency tree for bd-42:

> bd-42: Add authentication [P2] (open)
  > bd-41: Create API [P2] (open)
    > bd-40: Set up database [P1] (closed)
```

## bd dep cycles

Detect circular dependencies.

```bash
bd dep cycles [flags]
```

**Flags:**
```bash
--json    JSON output
```

**Examples:**
```bash
bd dep cycles
bd dep cycles --json
```

## bd ready

Show issues with no blockers.

```bash
bd ready [flags]
```

**Flags:**
```bash
--priority    Filter by priority
--type        Filter by type
--label       Filter by label
--json        JSON output
```

**Examples:**
```bash
bd ready
bd ready --priority 1
bd ready --type bug
bd ready --json
```

**Output:**
```
Ready work (3 issues with no blockers):

1. [P1] bd-40: Set up database
2. [P2] bd-45: Write tests
3. [P3] bd-46: Update docs
```

## bd blocked

Show blocked issues and their blockers.

```bash
bd blocked [flags]
```

**Flags:**
```bash
--json    JSON output
```

**Examples:**
```bash
bd blocked
bd blocked --json
```

**Output:**
```
Blocked issues (2 issues):

bd-42: Add authentication
  Blocked by: bd-41 (open)

bd-41: Create API
  Blocked by: bd-40 (in_progress)
```

## bd relate

Create a soft relationship between issues.

```bash
bd relate <id1> <id2> [flags]
```

**Examples:**
```bash
bd relate bd-42 bd-43
bd relate bd-42 bd-43 --json
```

## bd duplicate

Mark an issue as duplicate.

```bash
bd duplicate <id> --of <canonical> [flags]
```

**Examples:**
```bash
bd duplicate bd-43 --of bd-42
bd duplicate bd-43 --of bd-42 --json
```

## bd supersede

Mark an issue as superseding another.

```bash
bd supersede <old> --with <new> [flags]
```

**Examples:**
```bash
bd supersede bd-42 --with bd-50
bd supersede bd-42 --with bd-50 --json
```

## Understanding Dependencies

### Blocking vs Non-blocking

| Type | Blocks Ready Queue | Use Case |
|------|-------------------|----------|
| `blocks` | Yes | Hard dependency |
| `parent-child` | No | Epic/subtask hierarchy |
| `discovered-from` | No | Track origin |
| `related` | No | Soft link |
| `duplicates` | No | Mark duplicate |
| `supersedes` | No | Version chain |

### Dependency Direction

```bash
# bd-2 depends on bd-1
# Meaning: bd-1 must complete before bd-2 can start
bd dep add bd-2 bd-1

# After bd-1 closes:
bd close bd-1
bd ready  # bd-2 now appears
```

### Avoiding Cycles

```bash
# Check before adding complex dependencies
bd dep cycles

# If cycle detected, remove one dependency
bd dep remove bd-A bd-B
```

</document>

<document path="docs/cli-reference/essential.md">


# Essential Commands

The most important commands for daily use.

## bd create

Create a new issue.

```bash
bd create <title> [flags]
```

**Flags:**
| Flag | Short | Description |
|------|-------|-------------|
| `--type` | `-t` | Issue type: bug, feature, task, epic, chore |
| `--priority` | `-p` | Priority: 0-4 (0=critical, 4=backlog) |
| `--description` | `-d` | Detailed description |
| `--labels` | `-l` | Comma-separated labels |
| `--parent` | | Parent issue ID (for hierarchical) |
| `--deps` | | Dependencies (e.g., `discovered-from:bd-42`) |
| `--json` | | JSON output |

**Examples:**
```bash
bd create "Fix login bug" -t bug -p 1
bd create "Add dark mode" -t feature -p 2 --description="User requested"
bd create "Subtask" --parent bd-42 -p 2
bd create "Found during work" --deps discovered-from:bd-42 --json
```

## bd list

List issues with filters.

```bash
bd list [flags]
```

**Flags:**
| Flag | Description |
|------|-------------|
| `--status` | Filter by status: open, in_progress, closed |
| `--priority` | Filter by priority (comma-separated) |
| `--type` | Filter by type (comma-separated) |
| `--label-any` | Issues with any of these labels |
| `--label-all` | Issues with all of these labels |
| `--json` | JSON output |

**Examples:**
```bash
bd list --status open
bd list --priority 0,1 --type bug
bd list --label-any urgent,critical --json
```

## bd show

Show issue details.

```bash
bd show <id> [flags]
```

**Examples:**
```bash
bd show bd-42
bd show bd-42 --json
bd show bd-42 bd-43 bd-44  # Multiple issues
```

## bd update

Update issue fields.

```bash
bd update <id> [flags]
```

**Flags:**
| Flag | Description |
|------|-------------|
| `--status` | New status |
| `--priority` | New priority |
| `--title` | New title |
| `--description` | New description |
| `--add-label` | Add label |
| `--remove-label` | Remove label |
| `--json` | JSON output |

**Examples:**
```bash
bd update bd-42 --claim
bd update bd-42 --priority 0 --add-label urgent
bd update bd-42 --title "Updated title" --json
```

## bd close

Close an issue.

```bash
bd close <id> [flags]
```

**Flags:**
| Flag | Description |
|------|-------------|
| `--reason` | Closure reason |
| `--json` | JSON output |

**Examples:**
```bash
bd close bd-42
bd close bd-42 --reason "Fixed in PR #123"
bd close bd-42 --json
```

## bd ready

Show issues ready to work on (no blockers).

```bash
bd ready [flags]
```

**Flags:**
| Flag | Description |
|------|-------------|
| `--priority` | Filter by priority |
| `--type` | Filter by type |
| `--json` | JSON output |

**Examples:**
```bash
bd ready
bd ready --priority 1
bd ready --json
```

## bd blocked

Show blocked issues and their blockers.

```bash
bd blocked [flags]
```

**Examples:**
```bash
bd blocked
bd blocked --json
```

## bd dolt push

Push changes to a Dolt remote.

```bash
bd dolt push [flags]
```

Performs:
1. Dolt commit (snapshot current database state)
2. Push to Dolt remote

**Examples:**
```bash
bd dolt push
```

## bd dolt pull

Pull changes from a Dolt remote.

```bash
bd dolt pull [flags]
```

**Examples:**
```bash
bd dolt pull
```

## bd info

Show system information.

```bash
bd info [flags]
```

**Flags:**
| Flag | Description |
|------|-------------|
| `--whats-new` | Show recent version changes |
| `--schema` | Show database schema |
| `--json` | JSON output |

**Examples:**
```bash
bd info
bd info --whats-new
bd info --json
```

## bd stats

Show project statistics.

```bash
bd stats [flags]
```

**Examples:**
```bash
bd stats
bd stats --json
```

</document>

<document path="docs/cli-reference/issues.md">


# Issue Commands

Commands for managing issues.

## bd create

Create a new issue.

```bash
bd create <title> [flags]
```

**All flags:**
```bash
--type, -t        Issue type (bug|feature|task|epic|chore)
--priority, -p    Priority 0-4
--description, -d Detailed description
--design          Design notes
--acceptance      Acceptance criteria
--notes           Additional notes
--labels, -l      Comma-separated labels
--parent          Parent issue ID
--deps            Dependencies (type:id format)
--assignee        Assigned user
--json            JSON output
```

**Examples:**
```bash
# Bug with high priority
bd create "Login fails with special chars" -t bug -p 1

# Feature with description
bd create "Add export to PDF" -t feature -p 2 \
  --description="Users want to export reports as PDF files"

# Feature with design, acceptance, and notes
bd create "Implement user authentication" -t feature -p 1 \
  --description="Add JWT-based authentication" \
  --design="Use bcrypt for password hashing, JWT for sessions" \
  --acceptance="All tests pass, security audit complete" \
  --notes="Consider rate limiting for login attempts"

# Task with labels
bd create "Update CI config" -t task -l "ci,infrastructure"

# Epic with children
bd create "Auth System" -t epic -p 1
bd create "Design login UI" --parent bd-42
bd create "Implement backend" --parent bd-42

# Discovered issue
bd create "Found SQL injection" -t bug -p 0 \
  --deps discovered-from:bd-42 --json
```

## bd show

Display issue details.

```bash
bd show <id>... [flags]
```

**Flags:**
```bash
--full        Show all fields including comments
--json        JSON output
```

**Examples:**
```bash
bd show bd-42
bd show bd-42 --full
bd show bd-42 bd-43 bd-44 --json
```

## bd update

Update issue fields.

```bash
bd update <id> [flags]
```

**All flags:**
```bash
--status          New status (open|in_progress|closed)
--priority        New priority (0-4)
--title           New title
--description     New description
--type            New type
--add-label       Add label(s)
--remove-label    Remove label(s)
--assignee        New assignee
--json            JSON output
```

**Examples:**
```bash
# Start work
bd update bd-42 --claim

# Escalate priority
bd update bd-42 --priority 0 --add-label urgent

# Change title and description
bd update bd-42 --title "New title" --description="Updated description"

# Multiple changes
bd update bd-42 --claim --priority 1 --add-label "in-review" --json
```

## bd close

Close an issue.

```bash
bd close <id> [flags]
```

**Flags:**
```bash
--reason    Closure reason (stored in comment)
--json      JSON output
```

**Examples:**
```bash
bd close bd-42
bd close bd-42 --reason "Fixed in commit abc123"
bd close bd-42 --reason "Duplicate of bd-43" --json
```

## bd reopen

Reopen a closed issue.

```bash
bd reopen <id> [flags]
```

**Examples:**
```bash
bd reopen bd-42
bd reopen bd-42 --json
```

## bd delete

Delete an issue.

```bash
bd delete <id> [flags]
```

**Flags:**
```bash
--force, -f    Skip confirmation
--json         JSON output
```

**Examples:**
```bash
bd delete bd-42
bd delete bd-42 -f --json
```

**Note:** Deletions are tracked in the Dolt database for sync.

## bd search

Search issues by text.

```bash
bd search <query> [flags]
```

**Flags:**
```bash
--status    Filter by status
--type      Filter by type
--json      JSON output
```

**Examples:**
```bash
bd search "authentication"
bd search "login bug" --status open
bd search "API" --type feature --json
```

## bd duplicates

Find and manage duplicate issues.

```bash
bd duplicates [flags]
```

**Flags:**
```bash
--auto-merge    Automatically merge all duplicates
--dry-run       Preview without changes
--json          JSON output
```

**Examples:**
```bash
bd duplicates
bd duplicates --auto-merge
bd duplicates --dry-run --json
```

## bd merge

Merge duplicate issues.

```bash
bd merge <source>... --into <target> [flags]
```

**Flags:**
```bash
--into      Target issue to merge into
--dry-run   Preview without changes
--json      JSON output
```

**Examples:**
```bash
bd merge bd-42 bd-43 --into bd-41
bd merge bd-42 bd-43 --into bd-41 --dry-run --json
```

</document>

<document path="docs/cli-reference/labels.md">


# Labels & Comments

Commands for managing labels and comments.

## Labels

### Adding Labels

```bash
# During creation
bd create "Task" -l "backend,urgent"

# To existing issue
bd update bd-42 --add-label urgent
bd update bd-42 --add-label "backend,security"
```

### Removing Labels

```bash
bd update bd-42 --remove-label urgent
```

### Listing Labels

```bash
# All labels in use
bd label list
bd label list --json

# Issues with specific labels
bd list --label-any urgent,critical
bd list --label-all backend,security
```

### Label Conventions

Suggested label categories:

| Category | Examples | Purpose |
|----------|----------|---------|
| Type | `bug`, `feature`, `docs` | Issue classification |
| Priority | `urgent`, `critical` | Urgency markers |
| Area | `backend`, `frontend`, `api` | Code area |
| Status | `blocked`, `needs-review` | Workflow state |
| Size | `small`, `medium`, `large` | Effort estimate |

## Comments

### Adding Comments

```bash
bd comment add bd-42 "Working on this now"
bd comment add bd-42 --message "Found the bug in auth.go:45"
```

### Listing Comments

```bash
bd comment list bd-42
bd comment list bd-42 --json
```

### Viewing with Issue

```bash
bd show bd-42 --full  # Includes comments
```

## Filtering by Labels

### Any Match (OR)

```bash
# Issues with urgent OR critical
bd list --label-any urgent,critical
```

### All Match (AND)

```bash
# Issues with BOTH backend AND security
bd list --label-all backend,security
```

### Combined Filters

```bash
# Open bugs with urgent label
bd list --status open --type bug --label-any urgent --json
```

## Bulk Operations

### Add Label to Multiple Issues

```bash
# Using shell
for id in bd-42 bd-43 bd-44; do
  bd update $id --add-label "sprint-1"
done
```

### Find and Label

```bash
# Label all open bugs as needs-triage
bd list --status open --type bug --json | \
  jq -r '.[].id' | \
  xargs -I {} bd update {} --add-label needs-triage
```

## Best Practices

1. **Keep labels lowercase** - `backend` not `Backend`
2. **Use hyphens for multi-word** - `needs-review` not `needs_review`
3. **Be consistent** - Establish team conventions
4. **Don't over-label** - 2-4 labels per issue is typical
5. **Review periodically** - Remove unused labels

</document>

<document path="docs/cli-reference/sync.md">


# Sync & Export Commands

Commands for synchronizing with Dolt.

## bd dolt push

Push changes to a Dolt remote.

```bash
bd dolt push [flags]
```

**What it does:**
1. Dolt commit (snapshot current database state)
2. Push commits to Dolt remote

**Examples:**
```bash
bd dolt push
```

**When to use:**
- End of work session
- Before switching machines
- After significant changes

## bd dolt pull

Pull changes from a Dolt remote.

```bash
bd dolt pull [flags]
```

**What it does:**
1. Fetches commits from Dolt remote
2. Merges into local database

**Examples:**
```bash
bd dolt pull
```

**When to use:**
- Start of work session
- After switching machines
- Before creating new issues (to avoid duplicates)

## bd export

Export database to JSONL format (for backup and migration).

```bash
bd export [flags]
```

**Flags:**
```bash
--output, -o    Output file (default: stdout)
--dry-run       Preview without writing
--json          JSON output
```

**Examples:**
```bash
bd export
bd export -o backup.jsonl
bd export --dry-run
```

**When to use:** `bd export` is for backup and data migration, not day-to-day sync. Dolt handles sync natively via `bd dolt push`/`bd dolt pull`.

## bd migrate

Migrate database schema.

```bash
bd migrate [flags]
```

**Flags:**
```bash
--inspect    Show migration plan (for agents)
--dry-run    Preview without changes
--cleanup    Remove old files after migration
--yes        Skip confirmation
--json       JSON output
```

**Examples:**
```bash
bd migrate --inspect --json
bd migrate --dry-run
bd migrate
bd migrate --cleanup --yes
```

## bd hooks

Manage git hooks.

```bash
bd hooks <subcommand> [flags]
```

**Subcommands:**
| Command | Description |
|---------|-------------|
| `install` | Install git hooks |
| `uninstall` | Remove git hooks |
| `status` | Check hook status |

**Examples:**
```bash
bd hooks install
bd hooks status
bd hooks uninstall
```

## Auto-Sync Behavior

### With Dolt Server Mode (Default)

When the Dolt server is running, sync is handled automatically:
- Dolt auto-commit tracks changes
- Dolt-native replication handles remote sync

Start the Dolt server with `bd dolt start`.

### Embedded Mode (No Server)

In CI/CD pipelines and ephemeral environments, no server is needed:
- Changes written directly to the database
- Must manually push to remote

```bash
bd create "CI-generated task"
bd dolt push  # Manual push needed
```

## Conflict Resolution

Dolt handles conflict resolution at the database level using its built-in
merge capabilities. When conflicts arise during `bd dolt pull`, Dolt identifies
conflicting rows and allows resolution through SQL.

```bash
# Check for conflicts after pull
bd doctor --fix
```

## Deletion Tracking

Deletions are tracked in the Dolt database:

```bash
# Delete issue
bd delete bd-42

# View deletions
bd deleted
bd deleted --since=30d

# Deletions propagate via Dolt push
bd dolt push
```

## Best Practices

1. **Always push at session end** - `bd dolt push`
2. **Always pull at session start** - `bd dolt pull`
3. **Install git hooks** - `bd hooks install`
4. **Check sync status** - `bd info` shows sync state

</document>

<document path="docs/workflows/index.md">


# Workflows

Beads provides powerful workflow primitives for complex, multi-step processes.

## Chemistry Metaphor

Beads uses a molecular chemistry metaphor for workflow phases:

| Phase | Command | Synced | Use Case |
|-------|---------|--------|----------|
| **Proto** (solid) | `bd cook` | N/A | Compiled template, reusable |
| **Mol** (liquid) | `bd mol pour` | Yes | Persistent work with audit trail |
| **Wisp** (vapor) | `bd mol wisp` | No | Ephemeral operations |

## Core Concepts

### Formulas

Declarative workflow templates in TOML or JSON. Support variables, conditional steps, loops, inheritance, and composition.

```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"]
```

### Cooking

`bd cook` compiles a formula into a resolved proto. Two modes: compile-time (keeps `{{var}}` placeholders for planning) and runtime (substitutes all variables for final output).

### Molecules

Work graphs with parent-child relationships:
- Created by instantiating formulas with `bd mol 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:
- Created with `bd mol wisp`
- Stored locally with `Ephemeral=true`
- Lifecycle: squash (promote), burn (discard), or GC (auto-clean)

### Swarms

Parallel execution across an epic's dependency graph:
- Analyze epic structure for parallelism: `bd swarm validate`
- Create coordinated swarm from epic: `bd swarm create`
- Monitor progress across waves: `bd swarm status`

## Workflow Commands

| Command | Description |
|---------|-------------|
| `bd cook` | Compile formula into proto |
| `bd mol pour` | Instantiate formula as persistent molecule |
| `bd mol wisp` | Create ephemeral wisp from formula |
| `bd mol list` | List molecules |
| `bd mol squash` | Promote wisp to persistent molecule |
| `bd mol burn` | Delete wisp without trace |
| `bd mol wisp gc` | Garbage collect old wisps |
| `bd mol bond` | Bond formulas together with phase control |
| `bd swarm validate` | Analyze epic for parallel execution |
| `bd swarm create` | Create swarm from epic |
| `bd swarm status` | Show swarm progress |
| `bd swarm list` | List all swarm molecules |
| `bd formula list` | List available formulas |

## Simple Example

```bash
# Create a release workflow
bd mol pour release --var version=1.0.0

# View the molecule
bd dep tree bd-xyz

# Work through steps
bd update bd-xyz.1 --claim
bd close bd-xyz.1
# Next step becomes ready...
```

## Navigation

- [Molecules](/workflows/molecules) - Work graphs and execution
- [Formulas](/workflows/formulas) - Declarative templates (types, variables, inheritance, loops, conditions)
- [Gates](/workflows/gates) - Async coordination
- [Wisps](/workflows/wisps) - Ephemeral operations (squash, burn, GC lifecycle)

</document>

<document path="docs/workflows/formulas.md">


# Formulas

Formulas are declarative workflow templates.

## Formula Format

Formulas can be written in TOML (preferred) or JSON:

### TOML Format

```toml
formula = "feature-workflow"
description = "Standard feature development workflow"
version = 1
type = "workflow"

[vars.feature_name]
description = "Name of the feature"
required = true

[[steps]]
id = "design"
title = "Design {{feature_name}}"
type = "human"
description = "Create design document"

[[steps]]
id = "implement"
title = "Implement {{feature_name}}"
needs = ["design"]

[[steps]]
id = "review"
title = "Code review"
needs = ["implement"]
type = "human"

[[steps]]
id = "merge"
title = "Merge to main"
needs = ["review"]
```

### JSON Format

```json
{
  "formula": "feature-workflow",
  "description": "Standard feature development workflow",
  "version": 1,
  "type": "workflow",
  "vars": {
    "feature_name": {
      "description": "Name of the feature",
      "required": true
    }
  },
  "steps": [
    {
      "id": "design",
      "title": "Design {{feature_name}}",
      "type": "human"
    },
    {
      "id": "implement",
      "title": "Implement {{feature_name}}",
      "needs": ["design"]
    }
  ]
}
```

## Formula Types

| Type | Description |
|------|-------------|
| `workflow` | Standard step sequence |
| `expansion` | Template for expansion operator |
| `aspect` | Cross-cutting concerns |
| `convoy` | Multi-agent coordination (parallel workers) |

### Convoy Formulas

Convoy formulas coordinate multiple agents working in parallel. Use them for code review with multiple reviewers, design review sessions, or any workflow requiring parallel human or agent coordination.

```toml
formula = "multi-reviewer"
description = "Parallel code review with multiple reviewers"
version = 1
type = "convoy"

[vars.reviewers]
description = "Comma-separated reviewer names"
required = true

[[steps]]
id = "review-setup"
title = "Prepare review artifacts"

[[steps]]
id = "collect"
title = "Collect reviews"
needs = ["review-setup"]
waits_for = "all-children"
```

## Variables

Define variables with defaults and constraints:

```toml
[vars.version]
description = "Release version"
required = true
pattern = "^\\d+\\.\\d+\\.\\d+$"

[vars.environment]
description = "Target environment"
default = "staging"
enum = ["staging", "production"]
```

Use variables in steps:

```toml
[[steps]]
title = "Deploy {{version}} to {{environment}}"
```

## Step Types

| Type | Description |
|------|-------------|
| `task` | Normal work step (default) |
| `human` | Requires human action |
| `gate` | Async coordination point |

## Dependencies

### Sequential

```toml
[[steps]]
id = "step1"
title = "First step"

[[steps]]
id = "step2"
title = "Second step"
needs = ["step1"]
```

### Parallel then Join

```toml
[[steps]]
id = "test-unit"
title = "Unit tests"

[[steps]]
id = "test-integration"
title = "Integration tests"

[[steps]]
id = "deploy"
title = "Deploy"
needs = ["test-unit", "test-integration"]  # Waits for both
```

## Conditional Steps

Steps can be made conditional based on a variable:

```toml
[vars.run_security_scan]
description = "Whether to run security scan"
default = "true"

[[steps]]
id = "security-scan"
title = "Run security scan"
condition = "{{run_security_scan}}"

[[steps]]
id = "deploy"
title = "Deploy to production"
condition = "{{environment}} == production"
```

Condition formats:
- `"{{var}}"` - truthy (non-empty, non-false)
- `"!{{var}}"` - negated
- `"{{var}} == value"` - equality
- `"{{var}} != value"` - inequality

Conditions are evaluated at cook/pour time. Steps that don't match are removed from the workflow.

## Loops and Iteration

Steps can iterate using the `loop` field:

### Fixed Count

```toml
[[steps]]
id = "retry"
title = "Attempt {{i}}"

[steps.loop]
count = 3
var = "i"

[[steps.loop.body]]
id = "try-{{i}}"
title = "Attempt {{i}}"
```

### Range

```toml
[[steps]]
id = "phases"
title = "Phase iteration"

[steps.loop]
range = "1..5"
var = "phase_num"

[[steps.loop.body]]
id = "phase-{{phase_num}}"
title = "Execute phase {{phase_num}}"
```

Range supports expressions: `"1..2^{disks}"`, `"{start}..{count}"`.

### Until (Conditional)

```toml
[steps.loop]
until = "step.status == 'complete'"
max = 10
var = "attempt"

[[steps.loop.body]]
id = "attempt-{{attempt}}"
title = "Attempt {{attempt}}"
```

The `max` field is required for `until` loops to prevent unbounded iteration.

## Runtime Expansion (on_complete)

Steps can trigger dynamic work when they complete using `on_complete` with `for_each`:

```toml
[[steps]]
id = "survey"
title = "Survey available workers"

[steps.on_complete]
for_each = "output.workers"
bond = "worker-arm"
parallel = true

[steps.on_complete.vars]
worker_name = "{item.name}"
rig = "{item.rig}"
```

This creates a new molecule from the `worker-arm` formula for each item in the `output.workers` array. Use `sequential = true` instead of `parallel` to run them one at a time.

## Formula Inheritance

Formulas can inherit from parent formulas using `extends`:

```toml
formula = "secure-release"
description = "Release with security audit"
version = 1
type = "workflow"
extends = ["release"]

# Inherits all vars and steps from "release"
# Add new steps or override existing ones by ID:
[[steps]]
id = "security-audit"
title = "Security audit"
needs = ["test"]

# Override parent step
[[steps]]
id = "publish"
title = "Publish release (with audit)"
needs = ["tag", "security-audit"]
```

Child formulas inherit all vars, steps, and compose rules from parents. Child definitions with the same ID override parent definitions.

## Cooking Formulas

`bd cook` compiles a formula into a resolved proto. Two modes:

### Compile-time (default)

Produces a proto with `{{variable}}` placeholders intact. Useful for modeling, estimation, and planning.

```bash
bd cook feature-workflow                    # Template with placeholders
bd cook feature-workflow --dry-run          # Preview steps
```

### Runtime

Produces a fully-resolved proto with variables substituted. Requires all variables to have values.

```bash
bd cook feature-workflow --var feature_name=auth      # Substitute vars
bd cook feature-workflow --mode=runtime --var name=x  # Explicit runtime
```

For most workflows, prefer using `bd pour` or `bd mol wisp` directly - they cook the formula inline.

## Gates

Add gates for async coordination:

```toml
[[steps]]
id = "approval"
title = "Manager approval"
type = "human"

[steps.gate]
type = "human"
approvers = ["manager"]

[[steps]]
id = "deploy"
title = "Deploy to production"
needs = ["approval"]
```

Gate types: `human`, `timer`, `gh:run` (GitHub Actions), `gh:pr` (pull request).

## Aspects (Cross-cutting)

Apply transformations to matching steps:

```toml
formula = "security-scan"
type = "aspect"

[[advice]]
target = "*.deploy"  # Match all deploy steps

[advice.before]
id = "security-scan-{step.id}"
title = "Security scan before {step.title}"
```

Aspects support `before`, `after`, and `around` advice. Apply aspects to a formula via `compose.aspects`:

```toml
[compose]
aspects = ["security-scan", "logging"]
```

## Formula Locations

Formulas are searched in order:
1. `.beads/formulas/` (project-level)
2. `~/.beads/formulas/` (user-level)

## Using Formulas

```bash
# List available formulas
bd formula list

# Cook (compile) a formula
bd cook <formula-name> [--var key=value]

# Pour formula into molecule (persistent)
bd mol pour <formula-name> --var key=value

# Create wisp from formula (ephemeral)
bd mol wisp <formula-name> --var key=value

# Preview what would be created
bd mol pour <formula-name> --dry-run
```

## Creating Custom Formulas

1. Create file: `.beads/formulas/my-workflow.formula.toml`
2. Define structure (see examples above)
3. Use with: `bd mol pour my-workflow`

## Example: Release Formula

```toml
formula = "release"
description = "Standard release workflow"
version = 1

[vars.version]
required = true
pattern = "^\\d+\\.\\d+\\.\\d+$"

[[steps]]
id = "bump-version"
title = "Bump version to {{version}}"

[[steps]]
id = "changelog"
title = "Update CHANGELOG"
needs = ["bump-version"]

[[steps]]
id = "test"
title = "Run full test suite"
needs = ["changelog"]

[[steps]]
id = "build"
title = "Build release artifacts"
needs = ["test"]

[[steps]]
id = "tag"
title = "Create git tag v{{version}}"
needs = ["build"]

[[steps]]
id = "publish"
title = "Publish release"
needs = ["tag"]
type = "human"
```

</document>

<document path="docs/workflows/gates.md">


# Gates

Gates are async coordination primitives for workflow orchestration.

## What are Gates?

Gates block step progression until a condition is met:
- Human approval
- Timer expiration
- External event (GitHub PR, CI, etc.)

## Gate Types

### Human Gate

Wait for human approval:

```toml
[[steps]]
id = "deploy-approval"
title = "Approval for production deploy"
type = "human"

[steps.gate]
type = "human"
approvers = ["team-lead", "security"]
require_all = false  # Any approver can approve
```

### Timer Gate

Wait for a duration:

```toml
[[steps]]
id = "cooldown"
title = "Wait for cooldown period"

[steps.gate]
type = "timer"
duration = "24h"
```

Durations: `30m`, `2h`, `24h`, `7d`

### GitHub Gate

Wait for GitHub events:

```toml
[[steps]]
id = "wait-for-ci"
title = "Wait for CI to pass"

[steps.gate]
type = "github"
event = "check_suite"
status = "success"
```

```toml
[[steps]]
id = "wait-for-merge"
title = "Wait for PR merge"

[steps.gate]
type = "github"
event = "pull_request"
action = "closed"
merged = true
```

## Gate States

| State | Description |
|-------|-------------|
| `pending` | Waiting for condition |
| `open` | Condition met, can proceed |
| `closed` | Step completed |

## Using Gates in Workflows

### Approval Flow

```toml
formula = "production-deploy"

[[steps]]
id = "build"
title = "Build production artifacts"

[[steps]]
id = "staging"
title = "Deploy to staging"
needs = ["build"]

[[steps]]
id = "qa-approval"
title = "QA sign-off"
needs = ["staging"]
type = "human"

[steps.gate]
type = "human"
approvers = ["qa-team"]

[[steps]]
id = "production"
title = "Deploy to production"
needs = ["qa-approval"]
```

### Scheduled Release

```toml
formula = "scheduled-release"

[[steps]]
id = "prepare"
title = "Prepare release"

[[steps]]
id = "wait-window"
title = "Wait for release window"
needs = ["prepare"]

[steps.gate]
type = "timer"
duration = "2h"

[[steps]]
id = "deploy"
title = "Deploy release"
needs = ["wait-window"]
```

### CI Integration

```toml
formula = "ci-gated-deploy"

[[steps]]
id = "create-pr"
title = "Create pull request"

[[steps]]
id = "wait-ci"
title = "Wait for CI"
needs = ["create-pr"]

[steps.gate]
type = "github"
event = "check_suite"
status = "success"

[[steps]]
id = "merge"
title = "Merge PR"
needs = ["wait-ci"]
type = "human"
```

## Gate Operations

### Check Gate Status

```bash
bd show bd-xyz.3  # Shows gate state
bd show bd-xyz.3 --json | jq '.gate'
```

### Manual Gate Override

For human gates:

```bash
bd gate approve bd-xyz.3 --approver "team-lead"
```

### Skip Gate (Emergency)

```bash
bd gate skip bd-xyz.3 --reason "Emergency deploy"
```

## waits-for Dependency

The `waits-for` dependency type creates fan-in patterns:

```toml
[[steps]]
id = "test-a"
title = "Test suite A"

[[steps]]
id = "test-b"
title = "Test suite B"

[[steps]]
id = "integration"
title = "Integration tests"
waits_for = ["test-a", "test-b"]  # Fan-in: waits for all
```

## Best Practices

1. **Use human gates for critical decisions** - Don't auto-approve production
2. **Add timeout to timer gates** - Prevent indefinite blocking
3. **Document gate requirements** - Make approvers clear
4. **Use CI gates for quality** - Block on test failures

</document>

<document path="docs/workflows/molecules.md">


# Molecules

Molecules are work graphs created from formulas.

## What is a Molecule?

A molecule is a persistent instance of a formula:
- Contains steps with dependencies
- Tracked in `.beads/` (syncs with git)
- Steps map to issues with parent-child relationships

## Creating Molecules

### From Formula

```bash
# Pour a formula into a molecule
bd pour <formula-name> [--var key=value]
```

**Example:**
```bash
bd pour release --var version=1.0.0
```

This creates:
- Parent issue: `bd-xyz` (the molecule root)
- Child issues: `bd-xyz.1`, `bd-xyz.2`, etc. (the steps)

### Listing Molecules

```bash
bd mol list
bd mol list --json
```

### Viewing a Molecule

```bash
bd mol show <molecule-id>
bd dep tree <molecule-id>  # Shows full hierarchy
```

## Working with Molecules

### Step Dependencies

Steps have `needs` dependencies:

```toml
[[steps]]
id = "implement"
title = "Implement feature"
needs = ["design"]  # Must complete design first
```

The `bd ready` command respects these:

```bash
bd ready  # Only shows steps with completed dependencies
```

### Progressing Through Steps

```bash
# Start a step
bd update bd-xyz.1 --claim

# Complete a step
bd close bd-xyz.1 --reason "Done"

# Check what's ready next
bd ready
```

### Viewing Progress

```bash
# See blocked steps
bd blocked

# See molecule stats
bd stats
```

## Molecule Lifecycle

```
Formula (template)
    ↓ bd pour
Molecule (instance)
    ↓ work steps
Completed Molecule
    ↓ optional cleanup
Archived
```

## Advanced Features

### Bond Points

Formulas can define bond points for composition:

```toml
[compose]
[[compose.bond_points]]
id = "entry"
step = "design"
position = "before"
```

### Hooks

Execute actions on step completion:

```toml
[[steps]]
id = "build"
title = "Build project"

[steps.on_complete]
run = "make build"
```

### Pinning Work

Assign molecules to agents:

```bash
# Pin to current agent
bd pin bd-xyz --start

# Check what's pinned
bd hook
```

## Example Workflow

```bash
# 1. Create molecule from formula
bd pour feature-workflow --var name="dark-mode"

# 2. View structure
bd dep tree bd-xyz

# 3. Start first step
bd update bd-xyz.1 --claim

# 4. Complete and progress
bd close bd-xyz.1
bd ready  # Shows next steps

# 5. Continue until complete
```

## See Also

- [Formulas](/workflows/formulas) - Creating templates
- [Gates](/workflows/gates) - Async coordination
- [Wisps](/workflows/wisps) - Ephemeral workflows

</document>

<document path="docs/workflows/wisps.md">


# Wisps

Wisps are ephemeral workflows that don't sync to git.

## What are Wisps?

Wisps are "vapor phase" molecules - issues stored with `Ephemeral=true` in the main database. They are local-only and not synced via Dolt push/pull.

## Use Cases

| Scenario | Why Wisp? |
|----------|-----------|
| Release workflows | One-time execution, no audit trail needed |
| Operational loops | Recurring cycles that auto-clean up |
| Health checks | Diagnostics that shouldn't clutter history |
| Local experiments | Quick throwaway work |
| Agent coordination | Local-only parallel coordination |

## Creating Wisps

```bash
# Create wisp from formula
bd mol wisp <formula> [--var key=value]

# Examples
bd mol wisp quick-check
bd mol wisp release --var version=1.0.0
```

Formulas can recommend wisp usage with `phase = "vapor"` in the formula definition. If you use `bd mol pour` on a vapor-phase formula, you'll get a warning suggesting `bd mol wisp` instead.

## Wisp Lifecycle

```
Formula (template)
    | bd mol wisp
    v
Wisp (ephemeral, Ephemeral=true)
    | normal bd operations
    v
Completed Wisp
    |
    +---> bd mol squash  (promote to persistent molecule)
    +---> bd mol burn    (delete without trace)
    +---> bd mol wisp gc (garbage collect old wisps)
```

### Squash (Promote to Persistent)

Convert a wisp into a regular persistent molecule. Clears the `Ephemeral` flag so the issue syncs to git. Use when ephemeral work turns out to be worth preserving.

```bash
bd mol squash <wisp-id>
```

### Burn (Delete Without Trace)

Delete a wisp and all its children without creating a digest or summary. Use for discarding failed or abandoned ephemeral work.

```bash
bd mol burn <wisp-id>
```

### Garbage Collection

Clean up old, orphaned, or completed wisps automatically:

```bash
# List all wisps (flags old ones > 24h)
bd mol wisp list

# Garbage collect orphaned wisps
bd mol wisp gc
```

Wisps older than 24 hours are flagged as "old" in list output.

## Wisp Commands

```bash
bd mol wisp <formula>       # Create wisp from formula
bd mol wisp list             # List all wisps
bd mol wisp list --json      # List in JSON format
bd mol wisp gc               # Garbage collect old wisps
bd mol squash <wisp-id>      # Promote to persistent
bd mol burn <wisp-id>        # Delete without digest
```

## Wisp vs Molecule

| Aspect | Molecule (pour) | Wisp |
|--------|-----------------|------|
| Phase | Liquid | Vapor |
| Persistence | Permanent, syncs via Dolt | Ephemeral, local-only |
| Use case | Tracked work, audit trail | Temporary ops, one-time runs |
| Cleanup | Manual close/archive | Squash, burn, or GC |

## Phase Control

Use `bd mol bond` to control phase when bonding formulas together:

```bash
# Force liquid (persistent molecule)
bd mol bond <formula> <target> --pour

# Force vapor (ephemeral wisp)
bd mol bond <formula> <target> --wisp
```

## Best Practices

1. **Default to wisp for operational work** - releases, checks, diagnostics
2. **Use pour for tracked work** - features, bugs, anything worth preserving
3. **Squash if work becomes valuable** - promote ephemeral to persistent
4. **Burn failed experiments** - clean up without cluttering history
5. **Run GC periodically** - `bd mol wisp gc` keeps the database lean

</document>

<document path="docs/multi-agent/index.md">


# Multi-Agent Coordination

Beads supports coordination between multiple AI agents and repositories.

## Overview

Multi-agent features enable:
- **Routing** - Automatic issue routing to correct repositories
- **Cross-repo dependencies** - Dependencies across repository boundaries
- **Agent coordination** - Work assignment and handoff between agents

## Key Concepts

### Routes

Routes define which repository handles which issues:

```jsonl
{"pattern": "frontend/*", "target": "frontend-repo"}
{"pattern": "backend/*", "target": "backend-repo"}
{"pattern": "*", "target": "main-repo"}
```

### Work Assignment

Pin work to specific agents:

```bash
bd pin bd-42 --for agent-1 --start
bd hook --agent agent-1  # Show pinned work
```

### Cross-repo Dependencies

Track dependencies across repositories:

```bash
bd dep add bd-42 external:other-repo/bd-100
```

## Architecture

```
┌─────────────────┐
│   Main Repo     │
│   (coordinator) │
└────────┬────────┘
         │ routes
    ┌────┴────┐
    │         │
┌───▼───┐ ┌───▼───┐
│Frontend│ │Backend│
│ Repo   │ │ Repo  │
└────────┘ └────────┘
```

## Getting Started

1. **Single repo**: Standard beads workflow
2. **Multi-repo**: Configure routes and cross-repo deps
3. **Multi-agent**: Add work assignment and handoff

## Navigation

- [Routing](/multi-agent/routing) - Auto-routing configuration
- [Coordination](/multi-agent/coordination) - Agent coordination patterns

</document>

<document path="docs/multi-agent/coordination.md">


# Agent Coordination

Patterns for coordinating work between multiple AI agents.

## Work Assignment

### Pinning Work

Assign work to a specific agent:

```bash
# Pin issue to agent
bd pin bd-42 --for agent-1

# Pin and start work
bd pin bd-42 --for agent-1 --start

# Unpin work
bd unpin bd-42
```

### Checking Pinned Work

```bash
# What's on my hook?
bd hook

# What's on agent-1's hook?
bd hook --agent agent-1

# JSON output
bd hook --json
```

## Handoff Patterns

### Sequential Handoff

Agent A completes work, hands off to Agent B:

```bash
# Agent A
bd close bd-42 --reason "Ready for review"
bd pin bd-42 --for agent-b

# Agent B picks up
bd hook  # Sees bd-42
bd update bd-42 --claim
```

### Parallel Work

Multiple agents work on different issues:

```bash
# Coordinator
bd pin bd-42 --for agent-a --start
bd pin bd-43 --for agent-b --start
bd pin bd-44 --for agent-c --start

# Each agent works independently
# Coordinator monitors progress
bd list --status in_progress --json
```

### Fan-Out / Fan-In

Split work, then merge:

```bash
# Fan-out
bd create "Part A" --parent bd-epic
bd create "Part B" --parent bd-epic
bd create "Part C" --parent bd-epic

bd pin bd-epic.1 --for agent-a
bd pin bd-epic.2 --for agent-b
bd pin bd-epic.3 --for agent-c

# Fan-in: wait for all parts
bd dep add bd-merge bd-epic.1 bd-epic.2 bd-epic.3
```

## Agent Discovery

Find available agents:

```bash
# List known agents (if using agent registry)
bd agents list

# Check agent status
bd agents status agent-1
```

## Conflict Prevention

### File Reservations

Prevent concurrent edits:

```bash
# Reserve files before editing
bd reserve auth.go --for agent-1

# Check reservations
bd reservations list

# Release when done
bd reserve --release auth.go
```

### Issue Locking

```bash
# Lock issue for exclusive work
bd lock bd-42 --for agent-1

# Unlock when done
bd unlock bd-42
```

## Communication Patterns

### Via Comments

```bash
# Agent A leaves note
bd comment add bd-42 "Completed API, needs frontend integration"

# Agent B reads
bd show bd-42 --full
```

### Via Labels

```bash
# Mark for review
bd update bd-42 --add-label "needs-review"

# Agent B filters
bd list --label-any needs-review
```

## Best Practices

1. **Clear ownership** - Always pin work to specific agent
2. **Document handoffs** - Use comments to explain context
3. **Use labels for status** - `needs-review`, `blocked`, `ready`
4. **Avoid conflicts** - Use reservations for shared files
5. **Monitor progress** - Regular status checks

</document>

<document path="docs/multi-agent/routing.md">


# Multi-Repo Routing

Automatic issue routing across repositories.

## Overview

Routing enables:
- Issues created in one repo routed to another
- Pattern-based routing rules
- Fallback to default repository

## Configuration

Create `.beads/routes.jsonl`:

```jsonl
{"pattern": "frontend/**", "target": "frontend-repo", "priority": 10}
{"pattern": "backend/**", "target": "backend-repo", "priority": 10}
{"pattern": "docs/**", "target": "docs-repo", "priority": 5}
{"pattern": "*", "target": "main-repo", "priority": 0}
```

## Route Fields

| Field | Description |
|-------|-------------|
| `pattern` | Glob pattern to match |
| `target` | Target repository |
| `priority` | Higher = checked first |

## Pattern Matching

Patterns match against:
- Issue title
- Labels
- Explicit path prefix

**Examples:**
```jsonl
{"pattern": "frontend/*", "target": "frontend"}
{"pattern": "*api*", "target": "backend"}
{"pattern": "label:docs", "target": "docs-repo"}
```

## Commands

```bash
# Show routing table
bd routes list
bd routes list --json

# Test routing
bd routes test "Fix frontend button"
bd routes test --label frontend

# Add route
bd routes add "frontend/**" --target frontend-repo --priority 10

# Remove route
bd routes remove "frontend/**"
```

## Auto-Routing

When creating issues, beads checks routes:

```bash
bd create "Fix frontend button alignment" -t bug
# Auto-routed to frontend-repo based on title match
```

Override with explicit target:

```bash
bd create "Fix button" --repo backend-repo
```

## Cross-Repo Dependencies

Track dependencies across repos:

```bash
# In frontend-repo
bd dep add bd-42 external:backend-repo/bd-100

# View cross-repo deps
bd dep tree bd-42 --cross-repo
```

## Hydration

Pull related issues from other repos:

```bash
# Hydrate issues from related repos
bd hydrate

# Preview hydration
bd hydrate --dry-run

# Hydrate specific repo
bd hydrate --from backend-repo
```

## Best Practices

1. **Use specific patterns** - Avoid overly broad matches
2. **Set priorities** - Ensure specific patterns match first
3. **Default fallback** - Always have a `*` pattern with lowest priority
4. **Test routes** - Use `bd routes test` before committing

</document>

<document path="docs/integrations/aider.md">


# Aider Integration

How to use beads with Aider.

## Setup

### Quick Setup

```bash
bd setup aider
```

This creates/updates `.aider.conf.yml` with beads context.

### Verify Setup

```bash
bd setup aider --check
```

## Configuration

The setup adds to `.aider.conf.yml`:

```yaml
# Beads integration — bd prime provides issue context
auto-commits: false
```

## Workflow

### Start Session

```bash
# Aider will have access to issues via .aider.conf.yml
aider

# Or manually inject context
bd prime | aider --message-file -
```

### During Work

Use bd commands alongside aider:

```bash
# In another terminal or after exiting aider
bd create "Found bug during work" --deps discovered-from:bd-42 --json
bd update bd-42 --claim
bd ready
```

### End Session

```bash
bd dolt push
```

## Best Practices

1. **Keep issues visible** - Use `bd prime` to inject issue context
2. **Push regularly** - Run `bd dolt push` after significant changes
3. **Use discovered-from** - Track issues found during work
4. **Document context** - Include descriptions in issues

## Example Workflow

```bash
# 1. Check ready work
bd ready

# 2. Start aider with issue context
aider --message "Working on bd-42: Fix auth bug"

# 3. Work in aider...

# 4. Create discovered issues
bd create "Found related bug" --deps discovered-from:bd-42 --json

# 5. Complete and push
bd close bd-42 --reason "Fixed"
bd dolt push
```

## Troubleshooting

### Config not loading

```bash
# Check config exists
cat .aider.conf.yml

# Regenerate
bd setup aider
```

### Issues not visible

```bash
# Use bd prime to inject issue context
bd prime | aider --message-file -

# Or check database health
bd doctor
```

## See Also

- [Claude Code](/integrations/claude-code)
- [IDE Setup](/getting-started/ide-setup)

</document>

<document path="docs/integrations/claude-code.md">


# Claude Code Integration

How to use beads with Claude Code.

## Setup

### Quick Setup

```bash
bd setup claude
```

This installs:
- **SessionStart hook** - Runs `bd prime` on session start
- **PreCompact hook** - Runs `bd dolt push` before context compaction

### Manual Setup

Add to your Claude Code hooks configuration:

```json
{
  "hooks": {
    "SessionStart": ["bd prime"],
    "PreCompact": ["bd dolt push"]
  }
}
```

### Verify Setup

```bash
bd setup claude --check
```

## How It Works

1. **Session starts** → `bd prime` injects ~1-2k tokens of context
2. **You work** → Use `bd` CLI commands directly
3. **Session compacts** → `bd dolt push` saves work to Dolt remote
4. **Session ends** → Changes synced via git

## Essential Commands for Agents

### Creating Issues

```bash
# Always include description for context
bd create "Fix authentication bug" \
  --description="Login fails with special characters in password" \
  -t bug -p 1 --json

# Link discovered issues
bd create "Found SQL injection" \
  --description="User input not sanitized in query builder" \
  --deps discovered-from:bd-42 --json
```

### Working on Issues

```bash
# Find ready work
bd ready --json

# Start work
bd update bd-42 --claim --json

# Complete work
bd close bd-42 --reason "Fixed in commit abc123" --json
```

### Querying

```bash
# List open issues
bd list --status open --json

# Show issue details
bd show bd-42 --json

# Check blocked issues
bd blocked --json
```

### Syncing

```bash
# ALWAYS run at session end
bd dolt push
```

## Best Practices

### Always Use `--json`

```bash
bd list --json          # Parse programmatically
bd create "Task" --json # Get issue ID from output
bd show bd-42 --json    # Structured data
```

### Always Include Descriptions

```bash
# Good
bd create "Fix auth bug" \
  --description="Login fails when password contains quotes" \
  -t bug -p 1 --json

# Bad - no context for future work
bd create "Fix auth bug" -t bug -p 1 --json
```

### Link Related Work

```bash
# When you discover issues during work
bd create "Found related bug" \
  --deps discovered-from:bd-current --json
```

### Push Before Session End

```bash
# ALWAYS run before ending
bd dolt push
```

## Plugin (Optional)

For enhanced UX with slash commands:

```bash
# In Claude Code
/plugin marketplace add steveyegge/beads
/plugin install beads
# Restart Claude Code
```

Adds slash commands:
- `/beads:ready` - Show ready work
- `/beads:create` - Create issue
- `/beads:show` - Show issue
- `/beads:update` - Update issue
- `/beads:close` - Close issue

## Troubleshooting

### Context not injected

```bash
# Check hook setup
bd setup claude --check

# Manually prime
bd prime
```

### Changes not syncing

```bash
# Force push
bd dolt push

# Check system health
bd doctor
```

### Database not found

```bash
# Initialize beads
bd init --quiet
```

## See Also

- [MCP Server](/integrations/mcp-server) - For MCP-only environments
- [IDE Setup](/getting-started/ide-setup) - Other editors

</document>

<document path="docs/integrations/github-copilot.md">


# GitHub Copilot Integration

How to use beads with GitHub Copilot in VS Code.

## Setup

### Quick Setup

1. Install beads-mcp:
   ```bash
   uv tool install beads-mcp
   ```

2. Create `.vscode/mcp.json` in your project:
   ```json
   {
     "servers": {
       "beads": {
         "command": "beads-mcp"
       }
     }
   }
   ```

   **For all projects:** Add to VS Code user-level MCP config:

   | Platform | Path |
   |----------|------|
   | macOS | `~/Library/Application Support/Code/User/mcp.json` |
   | Linux | `~/.config/Code/User/mcp.json` |
   | Windows | `%APPDATA%\Code\User\mcp.json` |

   ```json
   {
     "servers": {
       "beads": {
         "command": "beads-mcp",
         "args": []
       }
     }
   }
   ```

3. Initialize beads:
   ```bash
   bd init --quiet
   ```

4. Reload VS Code

### Verify Setup

Ask Copilot Chat: "What beads issues are ready to work on?"

## Using Natural Language

With MCP configured, interact naturally:

```
You: Create a bug for the login timeout
Copilot: Created bd-42: Login timeout bug

You: What issues are ready?
Copilot: 3 issues ready: bd-42, bd-99, bd-17

You: Close bd-42, it's fixed
Copilot: Closed bd-42
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `beads_ready` | List unblocked issues |
| `beads_create` | Create new issue |
| `beads_show` | Show issue details |
| `beads_update` | Update issue |
| `beads_close` | Close issue |
| `beads_dolt_push` | Push to Dolt remote |
| `beads_dep_add` | Add dependency |
| `beads_dep_tree` | Show dependency tree |

## Copilot Instructions

Optionally add `.github/copilot-instructions.md`:

```markdown
## Issue Tracking

This project uses **bd (beads)** for issue tracking.
Run `bd prime` for workflow context.

Quick reference:
- `bd ready` - Find unblocked work
- `bd create "Title" --type task --priority 2` - Create issue
- `bd close <id>` - Complete work
- `bd dolt push` - Push changes to Dolt remote
```

## Troubleshooting

### Tools not appearing

1. Check VS Code 1.96+
2. Verify mcp.json syntax is valid JSON
3. Reload VS Code window
4. Check Output panel for MCP errors

### "beads-mcp not found"

```bash
# Check installation
which beads-mcp

# Reinstall if needed
uv tool install beads-mcp --force
```

### No database found

```bash
bd init --quiet
```

## FAQ

### Do I need to clone beads?

**No.** Beads is a system-wide CLI tool. Install once, use everywhere. The `.beads/` directory in your project only contains the issue database.

### What about git hooks?

Git hooks are optional. They auto-sync issues but you can skip them during `bd init` and manually run `bd dolt push` / `bd dolt pull` instead.

## See Also

- [MCP Server](/integrations/mcp-server) - Detailed MCP configuration
- [Installation](/getting-started/installation) - Full install guide
- [Detailed Copilot Guide](https://github.com/steveyegge/beads/blob/main/docs/COPILOT_INTEGRATION.md) - Comprehensive documentation

</document>

<document path="docs/integrations/junie.md">


# Junie Integration

How to use beads with Junie (JetBrains AI Agent).

## Setup

### Quick Setup

```bash
bd setup junie
```

This creates:
- **`.junie/guidelines.md`** - Agent instructions for beads workflow
- **`.junie/mcp/mcp.json`** - MCP server configuration

### Verify Setup

```bash
bd setup junie --check
```

## How It Works

1. **Session starts** → Junie reads `.junie/guidelines.md` for workflow context
2. **MCP tools available** → Junie can use beads MCP tools directly
3. **You work** → Use `bd` CLI commands or MCP tools
4. **Session ends** → Run `bd dolt push` to push changes to Dolt remote

## Configuration Files

### Guidelines (`.junie/guidelines.md`)

Contains workflow instructions that Junie reads automatically:
- Core workflow rules
- Command reference
- Issue types and priorities
- MCP tool documentation

### MCP Config (`.junie/mcp/mcp.json`)

Configures the beads MCP server:

```json
{
  "mcpServers": {
    "beads": {
      "command": "bd",
      "args": ["mcp"]
    }
  }
}
```

## MCP Tools

With MCP configured, Junie can use these tools directly:

| Tool | Description |
| --- | --- |
| `mcp_beads_ready` | Find tasks ready for work |
| `mcp_beads_list` | List issues with filters |
| `mcp_beads_show` | Show issue details |
| `mcp_beads_create` | Create new issues |
| `mcp_beads_update` | Update issue status/priority |
| `mcp_beads_close` | Close completed issues |
| `mcp_beads_dep` | Manage dependencies |
| `mcp_beads_blocked` | Show blocked issues |
| `mcp_beads_stats` | Get issue statistics |

## CLI Commands

You can also use the `bd` CLI directly:

### Creating Issues

```bash
# Always include description for context
bd create "Fix authentication bug" \
  --description="Login fails with special characters in password" \
  -t bug -p 1 --json

# Link discovered issues
bd create "Found SQL injection" \
  --description="User input not sanitized in query builder" \
  --deps discovered-from:bd-42 --json
```

### Working on Issues

```bash
# Find ready work
bd ready --json

# Start work
bd update bd-42 --claim --json

# Complete work
bd close bd-42 --reason "Fixed in commit abc123" --json
```

### Querying

```bash
# List open issues
bd list --status open --json

# Show issue details
bd show bd-42 --json

# Check blocked issues
bd blocked --json
```

### Syncing

```bash
# ALWAYS run at session end
bd dolt push
```

## Best Practices

### Always Use `--json`

```bash
bd list --json          # Parse programmatically
bd create "Task" --json # Get issue ID from output
bd show bd-42 --json    # Structured data
```

### Always Include Descriptions

```bash
# Good
bd create "Fix auth bug" \
  --description="Login fails when password contains quotes" \
  -t bug -p 1 --json

# Bad - no context for future work
bd create "Fix auth bug" -t bug -p 1 --json
```

### Link Related Work

```bash
# When you discover issues during work
bd create "Found related bug" \
  --deps discovered-from:bd-current --json
```

### Push Before Session End

```bash
# ALWAYS run before ending
bd dolt push
```

## Troubleshooting

### Guidelines not loaded

```bash
# Check setup
bd setup junie --check

# Reinstall if needed
bd setup junie
```

### MCP tools not available

```bash
# Verify MCP config exists
cat .junie/mcp/mcp.json

# Test MCP server
bd mcp --help
```

### Changes not syncing

```bash
# Force push
bd dolt push

# Check system health
bd doctor
```

### Database not found

```bash
# Initialize beads
bd init --quiet
```

## Removing Integration

```bash
bd setup junie --remove
```

This removes:
- `.junie/guidelines.md`
- `.junie/mcp/mcp.json`
- Empty `.junie/mcp/` and `.junie/` directories

## See Also

- [MCP Server](/integrations/mcp-server) - MCP server details
- [Claude Code](/integrations/claude-code) - Similar hook-based integration
- [IDE Setup](/getting-started/ide-setup) - Other editors

</document>

<document path="docs/integrations/mcp-server.md">


# MCP Server

Use beads in MCP-only environments.

## When to Use MCP

Use MCP server when CLI is unavailable:
- Claude Desktop (no shell access)
- Sourcegraph Amp without shell
- Other MCP-only environments

**Prefer CLI + hooks** when shell is available - it's more context efficient.

## Installation

### Using uv (Recommended)

```bash
uv tool install beads-mcp
```

### Using pip

```bash
pip install beads-mcp
```

## Configuration

### Claude Desktop (macOS)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```

### Claude Desktop (Windows)

Add to `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```

### Sourcegraph Amp

Add to MCP settings:

```json
{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}
```

### VS Code / GitHub Copilot

Create `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}
```

**For all projects:** Add to VS Code user-level MCP config:

| Platform | Path |
|----------|------|
| macOS | `~/Library/Application Support/Code/User/mcp.json` |
| Linux | `~/.config/Code/User/mcp.json` |
| Windows | `%APPDATA%\Code\User\mcp.json` |

```json
{
  "servers": {
    "beads": {
      "command": "beads-mcp",
      "args": []
    }
  }
}
```

**Note:** Requires VS Code 1.96+ with MCP support enabled.

See [GitHub Copilot Integration](/integrations/github-copilot) for complete setup guide.

## Available Tools

The MCP server exposes these tools:

| Tool | Description |
|------|-------------|
| `beads_create` | Create new issue |
| `beads_list` | List issues |
| `beads_show` | Show issue details |
| `beads_update` | Update issue |
| `beads_close` | Close issue |
| `beads_ready` | Show ready work |
| `beads_sync` | Sync to git |
| `beads_dep_add` | Add dependency |
| `beads_dep_tree` | Show dependency tree |

## Usage

Once configured, use naturally:

```
Create an issue for fixing the login bug with priority 1
```

The MCP server translates to appropriate `bd` commands.

## Trade-offs

| Aspect | CLI + Hooks | MCP Server |
|--------|-------------|------------|
| Context overhead | ~1-2k tokens | 10-50k tokens |
| Latency | Direct calls | MCP protocol |
| Setup | Hooks config | MCP config |
| Availability | Shell required | MCP environments |

## Troubleshooting

### Server won't start

Check if `beads-mcp` is in PATH:

```bash
which beads-mcp
```

If not found:

```bash
# Reinstall
pip uninstall beads-mcp
pip install beads-mcp
```

### Tools not appearing

1. Restart Claude Desktop
2. Check MCP config JSON syntax
3. Verify server path

### Permission errors

```bash
# Check directory permissions
ls -la .beads/

# Initialize if needed
bd init --quiet
```

## See Also

- [Claude Code](/integrations/claude-code) - CLI integration
- [Installation](/getting-started/installation) - Full install guide

</document>

<document path="docs/recovery/index.md">


# Recovery Overview

This section provides step-by-step recovery procedures for common Beads issues. Each runbook follows a consistent format: Symptoms, Diagnosis, Solution (5 steps max), and Prevention.

## Common Issues

| Issue | Symptoms | Runbook |
|-------|----------|---------|
| Database Corruption | SQLite 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) |

## Quick Diagnostic

Before diving into specific runbooks, try these quick checks:

```bash
# Check Beads status
bd status

# Verify Dolt server is running
bd doctor

# Check for blocked issues
bd blocked
```

:::tip
Most issues can be diagnosed with `bd status`. Start there before following specific runbooks.
:::

## Getting Help

If these runbooks don't resolve your issue:

1. Check the [FAQ](/reference/faq)
2. Search [existing issues](https://github.com/steveyegge/beads/issues)
3. Open a new issue with diagnostic output

</document>

<document path="docs/recovery/circular-dependencies.md">


# Circular Dependencies Recovery

This runbook helps you detect and break circular dependency cycles in your issues.

## Symptoms

- "circular dependency detected" errors
- `bd blocked` shows unexpected results
- Issues that should be ready appear blocked

## Diagnosis

```bash
# Check for blocked issues
bd blocked

# View dependencies for a specific issue
bd show <issue-id>

# List all dependencies
bd dep tree
```

## Solution

**Step 1:** Identify the cycle
```bash
bd blocked --verbose
```

**Step 2:** Map the dependency chain
```bash
bd show <issue-a>
bd show <issue-b>
# Follow the chain until you return to <issue-a>
```

**Step 3:** Determine which dependency to remove
Consider: Which dependency is least critical to the workflow?

**Step 4:** Remove the problematic dependency
```bash
bd dep remove <dependent-issue> <blocking-issue>
```

**Step 5:** Verify the cycle is broken
```bash
bd blocked
bd ready
```

## Prevention

- Think "X needs Y" not "X before Y" when adding dependencies
- Use `bd blocked` after adding dependencies to check for cycles
- Keep dependency chains shallow when possible

</document>

<document path="docs/recovery/database-corruption.md">


# Database Corruption Recovery

This runbook helps you recover from database corruption in Beads.

## Symptoms

- Error messages during `bd` commands
- "database is locked" errors that persist
- Missing issues that should exist
- Inconsistent database state

## Diagnosis

```bash
# Check database integrity
bd doctor

# Check Dolt server health
bd dolt show
```

## Solution

**Step 1:** Stop the Dolt server
```bash
bd dolt stop
```

**Step 2:** Back up current state
```bash
cp -r .beads .beads.backup
```

**Step 3:** Preview what doctor would fix
```bash
bd doctor --dry-run
```

**Step 4:** Rebuild database
```bash
bd doctor --fix
```

**Step 5:** Verify recovery
```bash
bd doctor
bd list
```

**Step 6:** Restart the Dolt server
```bash
dolt sql-server
```

## Prevention

- Let the Dolt server handle synchronization
- Use `bd dolt stop` before system shutdown
- Run `bd doctor` periodically to catch issues early

</document>

<document path="docs/recovery/merge-conflicts.md">


# Merge Conflicts Recovery

This runbook helps you resolve merge conflicts that occur during Dolt sync operations.

## Symptoms

- `bd dolt pull` fails with conflict errors
- Different issue states between clones

## Diagnosis

```bash
# Check database health
bd doctor

# Preview what fixes would be applied
bd doctor --dry-run
```

## Solution

**Step 1:** Back up current state
```bash
cp -r .beads .beads.backup
```

**Step 2:** Check for conflicts
```bash
bd doctor
```

**Step 3:** Fix to reconcile
```bash
bd doctor --fix
```

**Step 4:** Verify state
```bash
bd list
bd stats
```

**Step 5:** Push resolved state
```bash
bd dolt push
```

## Prevention

- Sync before and after work sessions using `bd dolt pull` / `bd dolt push`
- Avoid concurrent modifications from multiple clones without the Dolt server running

</document>

<document path="docs/recovery/sync-failures.md">


# Sync Failures Recovery

This runbook helps you recover from Dolt sync failures.

## Symptoms

- `bd dolt push` or `bd dolt pull` hangs or times out
- Network-related error messages
- "failed to push" or "failed to pull" errors
- Dolt server not responding

## Diagnosis

```bash
# Check Dolt server health
bd doctor
bd dolt show

# View Dolt server logs
tail -50 .beads/dolt/sql-server.log
```

## Solution

**Step 1:** Stop the Dolt server
```bash
bd dolt stop
```

**Step 2:** Check for lock files
```bash
ls -la .beads/*.lock
# Remove stale locks if Dolt server is definitely stopped
rm -f .beads/*.lock
```

**Step 3:** Back up and preview fixes
```bash
cp -r .beads .beads.backup
bd doctor --dry-run
```

**Step 4:** Apply fixes if needed
```bash
bd doctor --fix
```

**Step 5:** Restart the Dolt server
```bash
dolt sql-server
```

**Step 6:** Verify sync works
```bash
bd dolt push
bd doctor
```

## Common Causes

| Cause | Solution |
|-------|----------|
| Network timeout | Retry with better connection |
| Stale lock file | Remove lock after stopping Dolt server |
| Corrupted state | Back up, then `bd doctor --fix` |
| Merge conflicts | See [Merge Conflicts](/recovery/merge-conflicts) |

## Prevention

- Ensure stable network before sync
- Let sync complete before closing terminal
- Use `bd dolt stop` before system shutdown

</document>

<document path="docs/reference/advanced.md">


# Advanced Features

Advanced beads functionality.

## Issue Rename

Rename issues while preserving references:

```bash
bd rename bd-42 bd-new-id
bd rename bd-42 bd-new-id --dry-run  # Preview
```

Updates:
- All dependencies pointing to old ID
- All references in other issues
- Comments and descriptions

## Issue Merge

Merge duplicate issues:

```bash
bd merge bd-42 bd-43 --into bd-41
bd merge bd-42 bd-43 --into bd-41 --dry-run
```

What gets merged:
- Dependencies → target
- Text references updated across all issues
- Source issues closed with merge reason

## Database Compaction

Reduce database size by compacting old issues:

```bash
# View compaction statistics
bd admin compact --stats

# Preview candidates (30+ days closed)
bd admin compact --analyze --json

# Apply agent-generated summary
bd admin compact --apply --id bd-42 --summary summary.txt

# Immediate deletion (CAUTION!)
bd admin cleanup --force
```

**When to compact:**
- Database > 10MB with old closed issues
- After major milestones
- Before archiving project phase

## Restore from History

View deleted or compacted issues from git:

```bash
bd restore bd-42 --show
bd restore bd-42 --to-file issue.json
```

## Database Inspection

```bash
# Schema info
bd info --schema --json

# Raw database query (advanced — requires dolt sql-server running)
bd dolt sql "SELECT * FROM issues LIMIT 5"
```

## Custom Tables

Extend the database with custom tables:

```go
// In Go code using beads as library
storage.UnderlyingDB().Exec(`
  CREATE TABLE IF NOT EXISTS custom_table (...)
`)
```

See [EXTENDING.md](https://github.com/steveyegge/beads/blob/main/docs/EXTENDING.md).

## Event System

Subscribe to beads events:

```bash
# View recent events
bd events list --since 1h

# Watch events in real-time
bd events watch
```

Events:
- `issue.created`
- `issue.updated`
- `issue.closed`
- `dependency.added`
- `sync.completed`

## Batch Operations

### Create Multiple

```bash
# Bootstrap a new database from JSONL
bd init --from-jsonl issues.jsonl
```

### Update Multiple

```bash
bd list --status open --priority 4 --json | \
  jq -r '.[].id' | \
  xargs -I {} bd update {} --priority 3
```

### Close Multiple

```bash
bd list --label "sprint-1" --status open --json | \
  jq -r '.[].id' | \
  xargs -I {} bd close {} --reason "Sprint complete"
```

## API Access

Use beads as a Go library:

```go
import "github.com/steveyegge/beads/internal/storage/embeddeddolt"

store, _ := embeddeddolt.New(ctx, ".beads", "beads", "main")
defer store.Close()
issue, _ := store.GetIssue(ctx, "bd-a1b2")
```

## Performance Tuning

### Large Databases

```bash
# Enable WAL mode
bd config set database.wal_mode true

# Increase cache
bd config set database.cache_size 10000
```

### Many Concurrent Agents

Beads uses Dolt server mode to handle concurrent access from multiple agents.
The server manages transaction isolation automatically.

```bash
# Start the Dolt server
bd dolt start

# Check server health
bd doctor
```

### CI/CD Optimization

In CI/CD environments, beads uses embedded mode by default (no server required):

```bash
# Just run commands directly — no special flags needed
bd list
```

</document>

<document path="docs/reference/configuration.md">


# Configuration

Complete configuration reference for beads.

## Configuration Locations

1. **Project config**: `.beads/config.toml` (highest priority)
2. **User config**: `~/.beads/config.toml`
3. **Environment variables**: `BEADS_*`
4. **Command-line flags**: (highest priority)

## Managing Configuration

```bash
# Get config value
bd config get import.orphan_handling

# Set config value
bd config set import.orphan_handling allow

# List all config
bd config list

# Reset to default
bd config reset import.orphan_handling
```

## Configuration Options

### Database

```toml
[database]
# Embedded mode (default): data stored in .beads/embeddeddolt/
# Server mode: connects to dolt sql-server (bd init --server)
```

### ID Generation

```toml
[id]
prefix = "bd"                 # Issue ID prefix
hash_length = 4               # Hash length in IDs
```

**Issue ID mode** controls whether new issues get hash-based or sequential IDs:

```bash
# Use sequential IDs: bd-1, bd-2, bd-3, ...
bd config set issue_id_mode counter

# Use hash-based IDs (default): bd-a3f2, bd-7f3a8, ...
bd config set issue_id_mode hash
```

| Mode | Example ID | Best for |
|------|-----------|----------|
| `hash` (default) | `bd-a3f2` | Multi-agent, multi-branch workflows |
| `counter` | `bd-1` | Single-writer, project-management UIs |

Counter IDs are sequential and human-friendly. Hash IDs are collision-free across concurrent
branches. See [CONFIG.md](https://github.com/gastownhall/beads/blob/main/docs/CONFIG.md) for migration guidance and full details.

### Import

```toml
[import]
orphan_handling = "allow"     # allow|resurrect|skip|strict
dedupe_on_import = false      # Run duplicate detection after import
```

| Mode | Behavior |
|------|----------|
| `allow` | Import orphans without validation (default) |
| `resurrect` | Restore deleted parents as tombstones |
| `skip` | Skip orphaned children with warning |
| `strict` | Fail if parent missing |

### Export

```toml
[export]
path = ".beads/issues.jsonl"  # Default export file path (for bd export command)
```

### Git

```toml
[git]
auto_commit = true            # Auto-commit on sync
auto_push = true              # Auto-push on sync
commit_message = "bd: auto-commit"  # Default commit message
```

### Hooks

```toml
[hooks]
pre_commit = true             # Enable pre-commit hook
post_merge = true             # Enable post-merge hook
pre_push = true               # Enable pre-push hook
```

### Deletions

```toml
[deletions]
retention_days = 30           # Keep deletion records for N days
prune_on_sync = true          # Auto-prune old records
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `BEADS_DB` | Database path |
| `BEADS_LOG_LEVEL` | Log level |
| `BEADS_CONFIG` | Config file path |

## Per-Command Override

```bash
# Override database
bd --db /tmp/test.db list
```

## Example Configuration

`.beads/config.toml`:

```toml
[id]
prefix = "myproject"
hash_length = 6

[import]
orphan_handling = "resurrect"
dedupe_on_import = true

[git]
auto_commit = true
auto_push = true

[deletions]
retention_days = 90
```

## Viewing Active Configuration

```bash
bd info --json | jq '.config'
```

</document>

<document path="docs/reference/faq.md">


# Frequently Asked Questions

## General

### Why beads instead of GitHub Issues or Jira?

Beads was designed specifically for AI-supervised coding workflows:
- **Hash-based IDs** prevent collisions with concurrent agents
- **Dolt-backed storage** enables branch-based workflows
- **Dependency-aware** ready queue for automated work selection
- **Formula system** for declarative workflow templates

### What does "beads" stand for?

Nothing specific - it's a metaphor for linked work items (like beads on a string).

### Is beads production-ready?

Yes, beads is used in production for AI-assisted development. The API is stable with semantic versioning.

## Architecture

### Why Dolt instead of plain SQLite?

- **Dolt** provides a version-controlled SQL database with built-in replication
- Git-like branching, diffing, and merging at the database level
- No need for a separate sync format -- Dolt handles it natively

### Why hash-based IDs instead of sequential?

Sequential IDs (`#1`, `#2`) break when:
- Multiple agents create issues simultaneously
- Different branches have independent numbering
- Forks diverge and merge

Hash-based IDs are globally unique without coordination.

### How does the Dolt server work?

Beads uses Dolt server mode for concurrent access:
- Transaction isolation for multiple agents
- SQL-based queries for performance
- Automatic retry on conflicts

In CI/CD or single-agent environments, beads uses embedded mode automatically (no server required).

## Usage

### How do I sync issues?

```bash
# Push changes to Dolt remote:
bd dolt push

# Pull changes from Dolt remote:
bd dolt pull
```

### How do I handle merge conflicts?

Dolt handles merge conflicts at the database level. If conflicts arise during pull:
```bash
bd doctor --fix
bd dolt push
```

### Can multiple agents work on the same repo?

Yes! That's what beads was designed for:
- Hash IDs prevent collisions
- Pin work to specific agents
- Track who's working on what

### How do I use beads in CI/CD?

```bash
# Just run commands directly — beads uses embedded mode in CI
bd list
```

## Workflows

### What are formulas?

Declarative workflow templates in TOML or JSON. Pour them to create molecules (instances).

### What are gates?

Async coordination primitives:
- Human gates wait for approval
- Timer gates wait for duration
- GitHub gates wait for CI/PR events

### What's the difference between molecules and wisps?

- **Molecules** persist in `.beads/` and sync with git
- **Wisps** are ephemeral in `.beads-wisp/` and don't sync

## Integration

### Should I use CLI or MCP?

**Use CLI + hooks** when shell is available (Claude Code, Cursor, etc.):
- Lower context overhead (~1-2k vs 10-50k tokens)
- Faster execution
- Universal across editors

**Use MCP** when CLI unavailable (Claude Desktop).

### How do I integrate with my editor?

```bash
bd setup claude   # Claude Code
bd setup cursor   # Cursor
bd setup aider    # Aider
```

### Can beads import from GitHub Issues?

Yes — see the [GitHub integration documentation](https://github.com/steveyegge/beads/blob/main/docs/GITHUB_IMPORT.md) for details.

## Troubleshooting

### Why is the Dolt server not starting?

```bash
# Check server status
bd doctor

# Check server logs
cat .beads/dolt/sql-server.log

# Restart the server
bd dolt stop
bd dolt start
```

### Why aren't my changes syncing?

```bash
# Force push to Dolt remote
bd dolt push

# Check hooks
bd hooks status
```

### How do I report a bug?

1. Check existing issues: https://github.com/steveyegge/beads/issues
2. Include: `bd version`, `bd info --json`, reproduction steps
3. File at: https://github.com/steveyegge/beads/issues/new

</document>

<document path="docs/reference/git-integration.md">


# Git Integration

How beads integrates with git.

## Overview

Beads uses git for:
- **Project hosting** - Your code repository also hosts beads configuration
- **Hooks** - Auto-sync on git operations

Data storage and sync are handled by Dolt (a version-controlled SQL database).

## File Structure

```
.beads/
├── config.toml        # Project config (git-tracked)
├── metadata.json      # Backend metadata (git-tracked)
└── dolt/              # Dolt database and server data (gitignored)
```

## Git Hooks

### Installation

```bash
bd hooks install
```

Installs:
- **pre-commit** - Triggers Dolt commit
- **post-merge** - Triggers Dolt sync after pull
- **pre-push** - Ensures Dolt sync before push

### Status

```bash
bd hooks status
```

### Uninstall

```bash
bd hooks uninstall
```

## Conflict Resolution

Dolt handles merge conflicts at the database level using its built-in
merge capabilities. When conflicts arise during sync, Dolt identifies
conflicting rows and allows resolution through SQL.

```bash
# Check for and fix conflicts
bd doctor --fix
```

## Protected Branches

Dolt stores data under `refs/dolt/data`, separate from Git refs. This means beads data doesn't conflict with protected Git branches — no special branch flag is needed.

## Git Worktrees

Beads works in git worktrees using embedded mode:

```bash
# In worktree — just run commands directly
bd create "Task"
bd list
```

## Branch Workflows

### Feature Branch

```bash
git checkout -b feature-x
bd create "Feature X" -t feature
# Work...
bd dolt push
git push
```

### Fork Workflow

```bash
# In fork
bd init --contributor
# Work in separate planning repo...
bd dolt push
```

### Team Workflow

```bash
bd init --team
# All team members share the Dolt database
bd dolt pull   # Pull latest changes from Dolt remote
bd dolt push   # Push your changes to Dolt remote
```

### Duplicate Detection

After merging branches:

```bash
bd duplicates --auto-merge
```

## Best Practices

1. **Install hooks** - `bd hooks install`
2. **Push regularly** - `bd dolt push` at session end
3. **Pull before work** - `bd dolt pull` to get latest issues
4. **Worktrees use embedded mode automatically**

</document>

<document path="docs/reference/troubleshooting.md">


# Troubleshooting

Common issues and solutions.

## Installation Issues

### `bd: command not found`

```bash
# Check if installed
which bd
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd

# Add Go bin to PATH
export PATH="$PATH:$(go env GOPATH)/bin"

# Or reinstall
go install github.com/steveyegge/beads/cmd/bd@latest
```

### `zsh: killed bd` on macOS

CGO/SQLite compatibility issue:

```bash
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
```

### Permission denied

```bash
chmod +x $(which bd)
```

## Database Issues

### Database not found

```bash
# Initialize beads
bd init --quiet

# Or specify database
bd --db .beads/beads.db list
```

### Database locked

```bash
# Stop the Dolt server if running
bd dolt stop

# Try again
bd list
```

### Corrupted database

```bash
# Check and fix database
bd doctor --fix

# Or pull from Dolt remote
bd dolt pull

# Or restore from a backup
bd backup restore [path] --force
```

## Dolt Server Issues

### Server not starting

```bash
# Check server health
bd doctor

# Check server logs
cat .beads/dolt/sql-server.log

# Restart the server
bd dolt stop
bd dolt start
```

### Version mismatch

After upgrading bd:

```bash
bd dolt stop
bd dolt start
```

## Sync Issues

### Changes not syncing

```bash
# Force push to Dolt remote
bd dolt push

# Check hooks
bd hooks status
```

### Recovery from backup

```bash
# Restore from a Dolt backup
bd backup restore [path] --force

# Or pull from Dolt remote
bd dolt pull
```

### Merge conflicts

```bash
# Check for and fix Dolt conflicts
bd doctor --fix

# Re-push
bd dolt push
```

## Git Hook Issues

### Hooks not running

```bash
# Check if installed
ls -la .git/hooks/

# Reinstall
bd hooks install
```

### Hook errors

```bash
# Check hook script
cat .git/hooks/pre-commit

# Run manually
.git/hooks/pre-commit
```

## Dependency Issues

### Circular dependencies

```bash
# Detect cycles
bd dep cycles

# Remove one dependency
bd dep remove bd-A bd-B
```

### Missing dependencies

```bash
# Check orphan handling
bd config get import.orphan_handling

# Allow orphans
bd config set import.orphan_handling allow
```

## Performance Issues

### Slow queries

```bash
# Check database size
ls -lh .beads/beads.db

# Compact if large
bd admin compact --analyze
```

### High memory usage

```bash
# Reduce cache
bd config set database.cache_size 1000
```

## Getting Help

### Debug output

```bash
bd --verbose list
```

### Logs

```bash
cat .beads/dolt/sql-server.log
```

### System info

```bash
bd info --json
```

### File an issue

```bash
# Include this info
bd version
bd info --json
uname -a
```

Report at: https://github.com/steveyegge/beads/issues

</document>

---

# End of Documentation

For updates and contributions, visit: https://github.com/gastownhall/beads
