docs: apply PR #4722 review feedback to user docs

- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
  IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
  correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
  body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
  route spaces (1.0.0, 1.0.4, 1.0.5)
This commit is contained in:
Chris Sells 2026-07-12 11:06:57 -07:00
commit 69e33099b8
57 changed files with 110 additions and 39 deletions

View file

@ -1,5 +1,6 @@
---
title: Dolt Backend for Beads
description: "How beads uses Dolt for versioned issue storage: embedded vs server mode, remotes, sync, and backups"
---
Beads uses Dolt as its storage backend. Dolt provides a version-controlled SQL database with cell-level merge, native branching, and two deployment modes.
@ -250,7 +251,7 @@ Federation lets independent Dolt-backed workspaces ("towns") sync issues
directly with each other via `bd federation add-peer`/`sync`/`status`,
without a central hub. Credentials are AES-256 encrypted and stored locally.
See [FEDERATION.md](/multi-agent/federation) for the full setup guide, including
See [Federation Setup Guide](/multi-agent/federation) for the full setup guide, including
peer configuration, sovereignty tiers, sync/status/topology details, and
troubleshooting.
@ -786,10 +787,10 @@ rm .beads/*.backup-*.db
## See Also
- [SYNC_CONCEPTS.md](/core-concepts/sync-concepts) - The conceptual model behind cross-machine sync (Dolt source of truth, wire format, anti-patterns)
- [SYNC_SETUP.md](/getting-started/sync-setup) - Setting up sync across multiple computers
- [FEDERATION.md](/multi-agent/federation) - Peer-to-peer federation setup
- [CONFIG.md](/reference/configuration) - Full configuration reference
- [DEPENDENCIES.md](/core-concepts/dependencies) - Dependencies and gates
- [GIT_INTEGRATION.md](/reference/git-integration) - Git worktrees and protected branches
- [TROUBLESHOOTING.md](/reference/troubleshooting) - General troubleshooting
- [Sync Concepts](/core-concepts/sync-concepts) - The conceptual model behind cross-machine sync (Dolt source of truth, wire format, anti-patterns)
- [Sync Setup Guide](/getting-started/sync-setup) - Setting up sync across multiple computers
- [Federation Setup Guide](/multi-agent/federation) - Peer-to-peer federation setup
- [Configuration](/reference/configuration) - Full configuration reference
- [Dependencies and Gates](/core-concepts/dependencies) - Dependencies and gates
- [Git Integration](/reference/git-integration) - Git worktrees and protected branches
- [Troubleshooting](/reference/troubleshooting) - General troubleshooting

View file

@ -1,5 +1,6 @@
---
title: Storage Backends
description: Running bd on Dolt, Postgres, MySQL, or SQLite, and what version-control features each backend keeps
---
Beads uses Dolt as its default storage backend, and Dolt remains the reference implementation. You can also point `bd` at Postgres, MySQL, or SQLite — every backend implements the full issue-tracking core, and the only thing you give up off Dolt is version control.
@ -94,7 +95,7 @@ The backend is chosen once, at `bd init` time, and recorded in `.beads/metadata.
bd init --prefix myproj
```
Nothing changes. See [DOLT.md](/architecture/dolt) for embedded vs. server mode.
Nothing changes. See [Dolt Backend for Beads](/architecture/dolt) for embedded vs. server mode.
### SQLite
@ -275,4 +276,4 @@ BEADS_MYSQL_TEST_URL="user:pass@tcp(127.0.0.1:3306)/" \
Adding a new backend is one declarative profile entry in `test/conformance/profiles.go` plus a store-factory arm; both tiers pick it up automatically.
See [DOLT.md](/architecture/dolt) for the default backend, [CONFIG.md](/reference/configuration) for configuration, and [TROUBLESHOOTING.md](/reference/troubleshooting) if a connection misbehaves.
See [Dolt Backend for Beads](/architecture/dolt) for the default backend, [Configuration](/reference/configuration) for configuration, and [Troubleshooting](/reference/troubleshooting) if a connection misbehaves.

View file

@ -1,5 +1,6 @@
---
title: Community Tools
description: Community-built UIs, editor extensions, and integrations that work with the bd CLI, ranked by maturity
---
A curated list of community-built UIs, extensions, and integrations for Beads. Ranked by activity and maturity.

View file

@ -1,5 +1,6 @@
---
title: Adaptive ID Length
description: How hash ID length scales with database size to stay short while avoiding collisions
---
Beads uses adaptive hash ID lengths that automatically scale based on database size, optimizing for readability in small databases while preventing collisions as databases grow.
@ -209,7 +210,7 @@ bd config set issue_id_mode hash
- **Hash IDs** (this document): Collision-free across parallel branches and agents; IDs are less predictable but always unique.
- **Counter IDs**: Human-friendly and sequential; require care in multi-branch workflows where counters can diverge.
See [CONFIG.md](/reference/configuration) for full documentation on `issue_id_mode=counter`, including migration
See [Configuration](/reference/configuration) for full documentation on `issue_id_mode=counter`, including migration
guidance and per-prefix counter isolation.
## Related

View file

@ -1,5 +1,6 @@
---
title: Dependencies and Gates
description: Ordering work with blocking and non-blocking dependencies, and gates that wait on PRs, CI, or timers
---
Beads includes a full dependency system for ordering work and a gate system
@ -322,7 +323,7 @@ bd ready # Only "Design" is ready
## See Also
- [Quick Start](/getting-started/quickstart) — First steps with dependencies
- [MOLECULES.md](/workflows/molecules) — Molecule workflows using gates and dependencies
- [MULTI_REPO_AGENTS.md](/multi-agent/coordination) — Cross-repo dependency patterns
- [DOLT.md](/architecture/dolt) — Dolt backend configuration
- [CLI_REFERENCE.md](/cli-reference/index) — Full command reference
- [Molecules](/workflows/molecules) — Molecule workflows using gates and dependencies
- [Agent Coordination](/multi-agent/coordination) — Cross-repo dependency patterns
- [Dolt Backend for Beads](/architecture/dolt) — Dolt backend configuration
- [CLI Reference](/cli-reference/index) — Full command reference

View file

@ -1,5 +1,6 @@
---
title: Graph Links in Beads
description: "Non-blocking links between issues: replies-to threads, relates-to, duplicates, and supersedes chains"
---
Beads supports several types of links between issues to create a knowledge graph. These links enable rich querying and traversal beyond simple blocking dependencies.

View file

@ -1,5 +1,6 @@
---
title: Hash-based IDs
description: Why beads uses collision-resistant hash IDs like bd-a1b2 so agents and branches never clash
---
Understanding beads' collision-resistant ID system.

View file

@ -1,5 +1,6 @@
---
title: "Issues & Dependencies"
description: "The issue model: fields, types, priorities, and the dependencies that decide what work is ready"
---
Understanding the issue model in beads.

View file

@ -1,5 +1,6 @@
---
title: Labels
description: Flexible tagging for cross-cutting concerns, filtering, and caching operational state on issues
---
Labels provide flexible, multi-dimensional categorization for issues beyond the structured fields (status, priority, type). Use labels for cross-cutting concerns, technical metadata, and contextual tagging without schema changes.
@ -747,7 +748,7 @@ The `set-state` command atomically:
2. Removes the old dimension label if present
3. Adds the new dimension:value label (cache)
See [CLI_REFERENCE.md](/cli-reference/set-state) for full command reference.
See [bd set-state](/cli-reference/set-state) for full command reference.
## Troubleshooting
@ -788,4 +789,4 @@ bd doctor
- [README.md](https://github.com/gastownhall/beads/blob/main/README.md) - Main documentation
- [AGENTS.md](https://github.com/gastownhall/beads/blob/main/AGENTS.md) - AI agent integration guide
- [ADVANCED.md](/reference/advanced) - Advanced features and configuration
- [Advanced Features](/reference/advanced) - Advanced features and configuration

View file

@ -1,5 +1,6 @@
---
title: Issue Metadata
description: Storing arbitrary JSON on issues as the extension point for integrations and execution hints
---
The `metadata` field on issues accepts arbitrary JSON. Any valid JSON value is stored as-is.

View file

@ -1,5 +1,6 @@
---
title: Sync Concepts
description: Why Dolt is the source of truth for sync and how the JSONL export differs from bd dolt push and pull
---
Beads issue data lives in Dolt. The local Dolt database is the source of truth

View file

@ -194,6 +194,22 @@
{
"source": "/CLI_REFERENCE",
"destination": "/cli-reference/index"
},
{
"source": "/next/:slug*",
"destination": "/:slug*"
},
{
"source": "/1.0.0/:slug*",
"destination": "/:slug*"
},
{
"source": "/1.0.4/:slug*",
"destination": "/:slug*"
},
{
"source": "/1.0.5/:slug*",
"destination": "/:slug*"
}
],
"navigation": {

View file

@ -1,5 +1,6 @@
---
title: IDE Setup
description: Configure bd setup recipes, hooks, and instruction files for Claude Code, Cursor, Gemini, Copilot, and other coding agents
---
Configure your IDE or coding agent for optimal beads integration.

View file

@ -1,5 +1,6 @@
---
title: Installation
description: Install the bd CLI, Claude Code plugin, and MCP server on macOS, Linux, Windows, and FreeBSD via Homebrew, npm, or go install
---
Complete installation guide for all platforms.
@ -71,7 +72,7 @@ The `-g` enables beads globally. To enable project-specific versions, omit it.
Mise's Go backend follows the same caveats as `go install`; prefer the release backend above.
### Quick Install Script (All Platforms)
### Quick Install Script (macOS/Linux/FreeBSD)
```bash
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

View file

@ -1,5 +1,6 @@
---
title: Quick Start
description: Initialize beads, create issues with dependencies, find ready work, and sync with your team in a few minutes
---
Get up and running with Beads in a few minutes.
@ -262,7 +263,7 @@ bd dolt pull
When a teammate clones the repo, `bd bootstrap` auto-detects the existing database on `refs/dolt/data`, clones it, and wires `origin` for future `bd dolt push` / `bd dolt pull`.
See [`bd dolt`](/cli-reference/dolt) for CLI details. For remote configuration and federation, see the repository docs [DOLT.md](https://github.com/gastownhall/beads/blob/main/docs/DOLT.md) and [FEDERATION-SETUP.md](https://github.com/gastownhall/beads/blob/main/FEDERATION-SETUP.md).
See [`bd dolt`](/cli-reference/dolt) for CLI details. For remote configuration, see [Dolt architecture](/architecture/dolt); for federation, see [federation](/multi-agent/federation).
## Optional: Notion sync

View file

@ -1,5 +1,6 @@
---
title: Sync Setup Guide
description: "Set up Dolt sync so issue data follows you across machines: remotes, bootstrapping a clone, and day-to-day push and pull"
---
Set up beads with Dolt sync so your issues follow you across computers.
@ -10,7 +11,7 @@ You need two tools installed on every machine:
| Tool | Minimum Version | Install |
|------|-----------------|---------|
| **bd** (beads CLI) | 0.59.0+ | See [INSTALLING.md](/getting-started/installation) |
| **bd** (beads CLI) | 0.59.0+ | See [Installation](/getting-started/installation) |
| **Dolt** | 2.1.10+ | `brew install dolt` or [dolt install script](https://github.com/dolthub/dolt/releases/latest/download/install.sh) |
Verify both are installed:
@ -278,10 +279,10 @@ bd dolt start
## See Also
- [SYNC_CONCEPTS.md](/core-concepts/sync-concepts) — The conceptual model behind this setup (why Dolt is the source of truth, what JSONL is for)
- [Sync Concepts](/core-concepts/sync-concepts) — The conceptual model behind this setup (why Dolt is the source of truth, what JSONL is for)
- [Quick Start](/getting-started/quickstart) — Getting started with beads
- [DOLT.md](/architecture/dolt) — Dolt backend details, server modes, federation, remote types, and sync modes
- [INSTALLING.md](/getting-started/installation) — Installation for all platforms
- [Dolt Backend for Beads](/architecture/dolt) — Dolt backend details, server modes, federation, remote types, and sync modes
- [Installation](/getting-started/installation) — Installation for all platforms
## Attribution

View file

@ -1,5 +1,6 @@
---
title: Upgrading
description: Upgrade the bd binary, refresh git hooks, run schema migrations, and handle remote-backed and cross-era databases
---
How to upgrade bd and keep your projects in sync.

View file

@ -1,5 +1,6 @@
---
title: Introduction
description: Dependency-aware, Dolt-backed issue tracker built for AI coding agents that survive context loss
---
**Beads** (`bd`) is a Dolt-powered issue tracker designed for AI-supervised coding workflows.

View file

@ -1,5 +1,6 @@
---
title: Aider
description: Set up beads with Aider's human-in-the-loop workflow, where the AI suggests bd commands you approve with /run
---
How to use beads with Aider.

View file

@ -1,5 +1,6 @@
---
title: Azure DevOps (ADO) Integration Configuration
description: Configuration reference for bd ado sync, which bidirectionally syncs beads issues with Azure DevOps work items
---
Last reviewed: 2026-05-08

View file

@ -1,5 +1,6 @@
---
title: Beads Claude Code Plugin
description: Install the beads Claude Code plugin for /beads slash commands, a bundled skill, and session lifecycle hooks
---
AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with slash commands, a bundled skill, and lifecycle hooks.

View file

@ -1,5 +1,6 @@
---
title: Claude Code
description: Wire beads into Claude Code with a SessionStart hook that primes context, using the CLI instead of MCP
---
How to use beads with Claude Code.

View file

@ -1,5 +1,6 @@
---
title: Codex
description: Set up beads for Codex with the beads skill, a managed AGENTS.md section, and native hooks that survive compaction
---
Use Beads with Codex through the `beads` skill, managed `AGENTS.md` guidance, and native Codex hooks.

View file

@ -1,5 +1,6 @@
---
title: Sourcegraph Cody
description: Add beads workflow guidance to Sourcegraph Cody through a .cody/rules/beads.md project rules file
---
Use Beads with Sourcegraph Cody through a project rules file.

View file

@ -1,10 +1,11 @@
---
title: GitHub Copilot CLI Integration Design
description: Design rationale and setup for the Copilot CLI integration, which uses a plugin manifest plus repository instructions
---
This document explains design decisions for GitHub Copilot CLI integration in beads.
For **VS Code + MCP**, see [COPILOT_INTEGRATION.md](/integrations/github-copilot).
For **VS Code + MCP**, see [GitHub Copilot](/integrations/github-copilot).
## Integration Approach

View file

@ -1,5 +1,6 @@
---
title: Cursor
description: Set up beads for Cursor with an always-applied rules file, an agent skill, and hooks that restore context after compaction
---
Use Beads with Cursor through a project rules file **and** agent lifecycle hooks.

View file

@ -1,5 +1,6 @@
---
title: Factory.ai Droid
description: Set up beads for Factory.ai Droid through a managed Beads section in AGENTS.md
---
Use Beads with Factory.ai Droid through managed `AGENTS.md` guidance.

View file

@ -1,5 +1,6 @@
---
title: Gemini CLI
description: Set up beads for Gemini CLI with SessionStart hooks that run bd prime and GEMINI.md workflow guidance
---
Use Beads with Gemini CLI through SessionStart hooks and `GEMINI.md` guidance.

View file

@ -1,5 +1,6 @@
---
title: GitHub Copilot
description: Use beads from Copilot Chat in VS Code via the beads-mcp server to track issues in natural language
---
Beads gives Copilot a persistent, structured memory for tracking work: with the MCP server configured, you create, update, and track issues in natural language without leaving the editor.

View file

@ -1,5 +1,6 @@
---
title: Integrations
description: Browse every beads editor and agent integration, from bd setup recipes to MCP-based clients
---
Beads integration pages are based on two sources of support in the repository:

View file

@ -1,5 +1,6 @@
---
title: Junie
description: Set up beads for Junie, the JetBrains AI agent, with a guidelines file and an MCP server configuration
---
How to use beads with Junie (JetBrains AI Agent).

View file

@ -1,5 +1,6 @@
---
title: Kilo Code
description: Set up beads for Kilo Code by writing a .kilocode/rules/beads.md project rules file
---
Use Beads with Kilo Code through a project rules file.

View file

@ -1,5 +1,6 @@
---
title: MCP Server
description: Run the beads-mcp server for MCP-only environments like Claude Desktop where the bd CLI is unavailable
---
Use beads in MCP-only environments.

View file

@ -1,5 +1,6 @@
---
title: Mux
description: Set up beads for Mux with a managed AGENTS.md section, optional layered instruction files, and Mux hooks
---
Use Beads with Mux through `AGENTS.md`, optional layered Mux instruction files, and Mux hooks.

View file

@ -1,5 +1,6 @@
---
title: OpenCode
description: Give OpenCode beads workflow context via a managed Beads section in AGENTS.md
---
Use Beads with OpenCode through managed `AGENTS.md` guidance.

View file

@ -1,5 +1,6 @@
---
title: Windsurf
description: Enable beads in Windsurf through a .windsurf/rules/beads.md rules file with workflow guidance
---
Use Beads with Windsurf through a project rules file.

View file

@ -1,5 +1,6 @@
---
title: Agent Coordination
description: Assign and claim beads, hand off work, and serialize conflict-prone work with merge slots across multiple agents
---
Patterns for coordinating work between multiple AI agents.

View file

@ -1,5 +1,6 @@
---
title: Federation Setup Guide
description: Configure peer-to-peer sync of beads databases across workspaces with Dolt remotes, sovereignty tiers, and topologies
---
Federation enables peer-to-peer synchronization of beads databases between
@ -216,7 +217,7 @@ bd doctor --deep
## Reference
- Configuration: See [CONFIG.md](/reference/configuration) for all federation settings
- Configuration: See [Configuration](/reference/configuration) for all federation settings
- Source: `cmd/bd/federation.go`
- Storage interfaces: `internal/storage/versioned.go`
- Dolt implementation: `internal/storage/dolt/store.go`

View file

@ -1,5 +1,6 @@
---
title: Multi-Agent
description: Coordinate beads across multiple agents and repositories with routing, cross-repo dependencies, and work handoff
---
Beads supports coordination between multiple AI agents and repositories.

View file

@ -1,5 +1,6 @@
---
title: Multi-Repo Migration Guide
description: Adopt multi-repo routing for OSS contributor, team, multi-phase, and multi-persona workflows with separate planning repos
---
This guide helps you adopt beads' multi-repo workflow for OSS contributions, team collaboration, and multi-phase development.
@ -398,7 +399,7 @@ bd list --json
**Problem:** Multiple repos with conflicting changes.
**Solution:** Dolt handles merge conflicts natively with cell-level merge. See [TROUBLESHOOTING.md](/reference/troubleshooting#merge-conflicts) for details.
**Solution:** Dolt handles merge conflicts natively with cell-level merge. See [Troubleshooting](/reference/troubleshooting#merge-conflicts) for details.
### Discovered issues in wrong repository
@ -475,8 +476,8 @@ bd create "Issue" -p 1
## Next Steps
- **CLI Reference:** See [README.md](https://github.com/gastownhall/beads/blob/main/README.md) for command details
- **Configuration Guide:** See [CONFIG.md](/reference/configuration) for all config options
- **Troubleshooting:** See [TROUBLESHOOTING.md](/reference/troubleshooting)
- **Configuration Guide:** See [Configuration](/reference/configuration) for all config options
- **Troubleshooting:** See [Troubleshooting](/reference/troubleshooting)
- **Multi-Repo Internals:** See [ROUTING.md#multi-repo-hydration](/multi-agent/routing#multi-repo-hydration)
## Related Issues

View file

@ -1,5 +1,6 @@
---
title: Multi-Repo Routing
description: How bd create decides which repository each new bead lands in, with role detection and multi-repo hydration
---
One agent often works across more than one repository: an OSS fork plus a

View file

@ -1,5 +1,6 @@
---
title: Recovery Playbooks
description: Step-by-step recovery for bd init and bd dolt push/pull refusals, including the primary-key fork playbook
---
Last reviewed: 2026-06-09

View file

@ -1,5 +1,6 @@
---
title: Uninstalling
description: Remove beads from a repository with bd reset, uninstall git hooks, and delete the bd binary after backing up issue data
---
This guide explains how to remove beads from a repository or remove the `bd`

View file

@ -1,5 +1,6 @@
---
title: Advanced Features
description: Advanced bd operations for renaming issues and prefixes, merging duplicates, compaction, database redirects, and performance tuning.
---
Advanced beads functionality.

View file

@ -1,5 +1,6 @@
---
title: Antivirus False Positives
description: Why antivirus tools flag the bd binary as a false positive, and how to verify checksums, add exclusions, and report it.
---
## Overview

View file

@ -1,5 +1,6 @@
---
title: Configuration
description: Complete reference for bd configuration across config.yaml and database-stored settings, with precedence, secrets, auto-commit, backup, and integrations.
---
Complete configuration reference for beads.

View file

@ -149,7 +149,7 @@ cd ~/project1 && bd init --prefix proj1
cd ~/project2 && bd init --prefix proj2
```
Each project gets its own `.beads/` directory and database, and `bd` auto-discovers the right one by walking up from your current directory (like git). Issues cannot reference issues in other projects; if you need cross-project tracking, initialize beads in a parent directory that contains both.
Each project gets its own `.beads/` directory and database, and `bd` auto-discovers the right one by walking up from your current directory (like git). To link work across projects, hydrate the other repo into your database (`bd repo add`, then `bd repo sync`) and add normal dependencies, or depend on another project's capability with an `external:<project>:<capability>` target — see [cross-repo routing](/multi-agent/routing).
In server mode, each project runs its own Dolt server by default. On machines with many projects you can opt into a single shared server (`bd init --shared-server`, or `export BEADS_DOLT_SHARED_SERVER=1`) that serves every project from `~/.beads/shared-server/`. See [Dolt architecture](/architecture/dolt).
@ -222,19 +222,19 @@ bd setup aider # Aider
### Can beads import from GitHub Issues?
Yes — `bd github pull` imports issues and `bd github sync` keeps beads and GitHub in sync bidirectionally. See the [bd github reference](/cli-reference/github).
Yes — `bd github sync --pull-only` imports issues in bulk (`bd github pull <refs>` cherry-picks specific ones), and `bd github sync` keeps beads and GitHub in sync bidirectionally. See the [bd github reference](/cli-reference/github).
## Migration
### How do I migrate from GitHub Issues, Jira, or Linear?
Beads has built-in bidirectional sync for all three — `bd github`, `bd jira`, and `bd linear` each provide `pull`, `push`, and `sync` (GitLab, Azure DevOps, and Notion are covered by `bd gitlab`, `bd ado`, and `bd notion`). Configure credentials with `bd config set` per the [CLI reference](/cli-reference/index), then pull.
Beads has built-in bidirectional sync for all three — `bd github`, `bd jira`, and `bd linear` each provide `sync` for bulk moves, plus `pull`/`push` for specific issues by ID (GitLab, Azure DevOps, and Notion are covered by `bd gitlab`, `bd ado`, and `bd notion`). Configure credentials with `bd config set` per the [CLI reference](/cli-reference/index), then run the sync in the pull direction: `bd github sync --pull-only`, `bd jira sync --pull`, or `bd linear sync --pull`.
For any other tracker: export from it (usually CSV or JSON), convert to beads' JSONL format, and run `bd import <file>`. See [examples](https://github.com/gastownhall/beads/tree/main/examples) for scripting patterns.
### Can I export back out of beads?
For GitHub, Jira, and Linear, use the same integrations in the push direction (`bd github push`, `bd jira push`, `bd linear push`). For anything else, `bd export -o issues.jsonl` produces JSONL you can convert with a script and feed to the target system's API.
For GitHub, Jira, and Linear, use the same integrations in the push direction — `bd github sync --push-only`, `bd jira sync --push`, or `bd linear sync --push` for everything, or `bd <tracker> push <ids>` for specific beads. For anything else, `bd export -o issues.jsonl` produces JSONL you can convert with a script and feed to the target system's API.
## Performance

View file

@ -1,5 +1,6 @@
---
title: Git Integration
description: How bd uses git for hosting and hooks, including hook installation, external hook managers, worktrees, and branch workflows.
---
How beads integrates with git.

View file

@ -1,5 +1,6 @@
---
title: JSON Output Schema Contract
description: The stable JSON output contract for bd --json commands, covering the schema_version envelope, per-command fields, and consumer guidelines.
---
Last reviewed: 2026-05-08

View file

@ -1,5 +1,6 @@
---
title: Observability (OpenTelemetry)
description: Exporting bd metrics and traces over OpenTelemetry (OTLP), with a local VictoriaMetrics and Grafana stack, env vars, and a metric reference.
---
Beads exports metrics via OTLP HTTP. Telemetry is **disabled by default** — zero overhead when no variable is set.

View file

@ -1,5 +1,6 @@
---
title: Protected Branches
description: Why beads needs no protected-branch workaround since Dolt stores issue data outside Git refs, plus team workflow and legacy sync-branch cleanup.
---
Beads does not need a protected-branch workaround in current releases.
@ -117,6 +118,6 @@ bd hooks install
## See Also
- [WORKTREES.md](/reference/worktrees) - Git worktree behavior
- [GIT_INTEGRATION.md](/reference/git-integration) - general Git integration guide
- [RECOVERY.md](/recovery/init-safety) - recovery playbooks
- [Git Worktrees Guide](/reference/worktrees) - Git worktree behavior
- [Git Integration](/reference/git-integration) - general Git integration guide
- [Recovery Playbooks](/recovery/init-safety) - recovery playbooks

View file

@ -1,5 +1,6 @@
---
title: Troubleshooting
description: Fixes for common bd problems across installation, the database and Dolt server, sync, git hooks, dependencies, and platform-specific issues.
---
Common issues and solutions. For step-by-step runbooks, see the

View file

@ -1,5 +1,6 @@
---
title: Git Worktrees Guide
description: Using beads from Git worktrees, which share one .beads workspace, plus external BEADS_DIR setups and legacy sync-branch cleanup.
---
Beads works from normal Git worktrees without a separate sync branch. Current
@ -128,6 +129,6 @@ working the same issue concurrently.
## See Also
- [PROTECTED_BRANCHES.md](/reference/protected-branches) - protected branch behavior
- [GIT_INTEGRATION.md](/reference/git-integration) - general Git integration guide
- [MULTI_REPO_MIGRATION.md](/multi-agent/multi-repo-migration) - multi-workspace patterns
- [Protected Branches](/reference/protected-branches) - protected branch behavior
- [Git Integration](/reference/git-integration) - general Git integration guide
- [Multi-Repo Migration Guide](/multi-agent/multi-repo-migration) - multi-workspace patterns

View file

@ -1,10 +1,11 @@
---
title: Related Projects
description: Adjacent, independent projects that solve neighboring problems and compose well with beads
---
Adjacent or complementary tools that solve different problems in the
same neighborhood as Beads. These are not Beads integrations (see
[COMMUNITY_TOOLS.md](/community-tools) for those) — they are
[Community Tools](/community-tools) for those) — they are
independent projects whose users may also find Beads useful, or vice
versa.

View file

@ -1,5 +1,6 @@
---
title: Formulas
description: Writing declarative TOML or JSON workflow templates with steps, variables, dependencies, gates, and aspects, then cooking them into protos.
---
Formulas are declarative workflow templates.

View file

@ -1,5 +1,6 @@
---
title: Molecules
description: Molecules are epics whose children flow through bd ready as ordered steps; covers creating, executing, bonding, and the molecule lifecycle.
---
Molecules are work graphs: epics whose children flow through `bd ready` as

View file

@ -1,5 +1,6 @@
---
title: TODO Command
description: The bd todo command for managing lightweight TODO items as ordinary task-type issues, with add, list, and done shortcuts.
---
The `bd todo` command provides a lightweight interface for managing TODO items as task-type issues.