From 69e33099b8b259dd1e1760f34c8a9bfefff86f42 Mon Sep 17 00:00:00 2001 From: Chris Sells Date: Sun, 12 Jul 2026 11:06:57 -0700 Subject: [PATCH] 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) --- docs/architecture/dolt.md | 17 +++++++++-------- docs/architecture/storage-backends.md | 5 +++-- docs/community-tools.md | 1 + docs/core-concepts/adaptive-ids.md | 3 ++- docs/core-concepts/dependencies.md | 9 +++++---- docs/core-concepts/graph-links.md | 1 + docs/core-concepts/hash-ids.md | 1 + docs/core-concepts/issues.md | 1 + docs/core-concepts/labels.md | 5 +++-- docs/core-concepts/metadata.md | 1 + docs/core-concepts/sync-concepts.md | 1 + docs/docs.json | 16 ++++++++++++++++ docs/getting-started/ide-setup.md | 1 + docs/getting-started/installation.md | 3 ++- docs/getting-started/quickstart.md | 3 ++- docs/getting-started/sync-setup.md | 9 +++++---- docs/getting-started/upgrading.md | 1 + docs/index.md | 1 + docs/integrations/aider.md | 1 + docs/integrations/azure-devops.md | 1 + docs/integrations/claude-code-plugin.md | 1 + docs/integrations/claude-code.md | 1 + docs/integrations/codex.md | 1 + docs/integrations/cody.md | 1 + docs/integrations/copilot-cli.md | 3 ++- docs/integrations/cursor.md | 1 + docs/integrations/factory.md | 1 + docs/integrations/gemini.md | 1 + docs/integrations/github-copilot.md | 1 + docs/integrations/index.md | 1 + docs/integrations/junie.md | 1 + docs/integrations/kilocode.md | 1 + docs/integrations/mcp-server.md | 1 + docs/integrations/mux.md | 1 + docs/integrations/opencode.md | 1 + docs/integrations/windsurf.md | 1 + docs/multi-agent/coordination.md | 1 + docs/multi-agent/federation.md | 3 ++- docs/multi-agent/index.md | 1 + docs/multi-agent/multi-repo-migration.md | 7 ++++--- docs/multi-agent/routing.md | 1 + docs/recovery/init-safety.md | 1 + docs/recovery/uninstalling.md | 1 + docs/reference/advanced.md | 1 + docs/reference/antivirus.md | 1 + docs/reference/configuration.md | 1 + docs/reference/faq.md | 8 ++++---- docs/reference/git-integration.md | 1 + docs/reference/json-schema.md | 1 + docs/reference/observability.md | 1 + docs/reference/protected-branches.md | 7 ++++--- docs/reference/troubleshooting.md | 1 + docs/reference/worktrees.md | 7 ++++--- docs/related-projects.md | 3 ++- docs/workflows/formulas.md | 1 + docs/workflows/molecules.md | 1 + docs/workflows/todo.md | 1 + 57 files changed, 110 insertions(+), 39 deletions(-) diff --git a/docs/architecture/dolt.md b/docs/architecture/dolt.md index 723a5148b..9bb7fde98 100644 --- a/docs/architecture/dolt.md +++ b/docs/architecture/dolt.md @@ -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 diff --git a/docs/architecture/storage-backends.md b/docs/architecture/storage-backends.md index d0b430f9c..ce7a6102c 100644 --- a/docs/architecture/storage-backends.md +++ b/docs/architecture/storage-backends.md @@ -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. diff --git a/docs/community-tools.md b/docs/community-tools.md index b8d2dc0cb..6270c631f 100644 --- a/docs/community-tools.md +++ b/docs/community-tools.md @@ -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. diff --git a/docs/core-concepts/adaptive-ids.md b/docs/core-concepts/adaptive-ids.md index ab6df79db..1d7b801f9 100644 --- a/docs/core-concepts/adaptive-ids.md +++ b/docs/core-concepts/adaptive-ids.md @@ -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 diff --git a/docs/core-concepts/dependencies.md b/docs/core-concepts/dependencies.md index 3017e8a06..f164c370a 100644 --- a/docs/core-concepts/dependencies.md +++ b/docs/core-concepts/dependencies.md @@ -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 diff --git a/docs/core-concepts/graph-links.md b/docs/core-concepts/graph-links.md index 430c6d52a..0f48ce38d 100644 --- a/docs/core-concepts/graph-links.md +++ b/docs/core-concepts/graph-links.md @@ -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. diff --git a/docs/core-concepts/hash-ids.md b/docs/core-concepts/hash-ids.md index 7b98a4835..92b2267ff 100644 --- a/docs/core-concepts/hash-ids.md +++ b/docs/core-concepts/hash-ids.md @@ -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. diff --git a/docs/core-concepts/issues.md b/docs/core-concepts/issues.md index 98aa8dfea..a7f811386 100644 --- a/docs/core-concepts/issues.md +++ b/docs/core-concepts/issues.md @@ -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. diff --git a/docs/core-concepts/labels.md b/docs/core-concepts/labels.md index 42253e706..24cd8afbe 100644 --- a/docs/core-concepts/labels.md +++ b/docs/core-concepts/labels.md @@ -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 diff --git a/docs/core-concepts/metadata.md b/docs/core-concepts/metadata.md index 8d2968d2e..5dd86dce8 100644 --- a/docs/core-concepts/metadata.md +++ b/docs/core-concepts/metadata.md @@ -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. diff --git a/docs/core-concepts/sync-concepts.md b/docs/core-concepts/sync-concepts.md index 476fdfb68..1823060dc 100644 --- a/docs/core-concepts/sync-concepts.md +++ b/docs/core-concepts/sync-concepts.md @@ -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 diff --git a/docs/docs.json b/docs/docs.json index aca94fb01..7058fe353 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -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": { diff --git a/docs/getting-started/ide-setup.md b/docs/getting-started/ide-setup.md index 3406fb2c7..ebddc082d 100644 --- a/docs/getting-started/ide-setup.md +++ b/docs/getting-started/ide-setup.md @@ -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. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index b415873bb..b89437148 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -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 diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index dcf8b8935..caaf03bb3 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -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 diff --git a/docs/getting-started/sync-setup.md b/docs/getting-started/sync-setup.md index 8d88ba558..039685947 100644 --- a/docs/getting-started/sync-setup.md +++ b/docs/getting-started/sync-setup.md @@ -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 diff --git a/docs/getting-started/upgrading.md b/docs/getting-started/upgrading.md index 41c3c64a1..ec59a3089 100644 --- a/docs/getting-started/upgrading.md +++ b/docs/getting-started/upgrading.md @@ -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. diff --git a/docs/index.md b/docs/index.md index f39ff51f6..13d6d6e2a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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. diff --git a/docs/integrations/aider.md b/docs/integrations/aider.md index d6cf12bd3..c30e72e7a 100644 --- a/docs/integrations/aider.md +++ b/docs/integrations/aider.md @@ -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. diff --git a/docs/integrations/azure-devops.md b/docs/integrations/azure-devops.md index baf4813d2..75aefc05c 100644 --- a/docs/integrations/azure-devops.md +++ b/docs/integrations/azure-devops.md @@ -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 diff --git a/docs/integrations/claude-code-plugin.md b/docs/integrations/claude-code-plugin.md index 67aa6c5a9..7112f7d40 100644 --- a/docs/integrations/claude-code-plugin.md +++ b/docs/integrations/claude-code-plugin.md @@ -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. diff --git a/docs/integrations/claude-code.md b/docs/integrations/claude-code.md index 460dd20af..1678215b5 100644 --- a/docs/integrations/claude-code.md +++ b/docs/integrations/claude-code.md @@ -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. diff --git a/docs/integrations/codex.md b/docs/integrations/codex.md index f46d603e9..569b9a643 100644 --- a/docs/integrations/codex.md +++ b/docs/integrations/codex.md @@ -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. diff --git a/docs/integrations/cody.md b/docs/integrations/cody.md index 33b0f16cb..7a737b697 100644 --- a/docs/integrations/cody.md +++ b/docs/integrations/cody.md @@ -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. diff --git a/docs/integrations/copilot-cli.md b/docs/integrations/copilot-cli.md index d8212fd8f..bc9c4aa92 100644 --- a/docs/integrations/copilot-cli.md +++ b/docs/integrations/copilot-cli.md @@ -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 diff --git a/docs/integrations/cursor.md b/docs/integrations/cursor.md index 2fa4764a1..16a68d674 100644 --- a/docs/integrations/cursor.md +++ b/docs/integrations/cursor.md @@ -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. diff --git a/docs/integrations/factory.md b/docs/integrations/factory.md index f7301732e..5cffce8a8 100644 --- a/docs/integrations/factory.md +++ b/docs/integrations/factory.md @@ -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. diff --git a/docs/integrations/gemini.md b/docs/integrations/gemini.md index 712453b03..49e310970 100644 --- a/docs/integrations/gemini.md +++ b/docs/integrations/gemini.md @@ -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. diff --git a/docs/integrations/github-copilot.md b/docs/integrations/github-copilot.md index a0c377eb2..0ba03ffcd 100644 --- a/docs/integrations/github-copilot.md +++ b/docs/integrations/github-copilot.md @@ -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. diff --git a/docs/integrations/index.md b/docs/integrations/index.md index 8f143de15..d040540e8 100644 --- a/docs/integrations/index.md +++ b/docs/integrations/index.md @@ -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: diff --git a/docs/integrations/junie.md b/docs/integrations/junie.md index 7968a1005..18d90c185 100644 --- a/docs/integrations/junie.md +++ b/docs/integrations/junie.md @@ -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). diff --git a/docs/integrations/kilocode.md b/docs/integrations/kilocode.md index 813d708e4..2730dc699 100644 --- a/docs/integrations/kilocode.md +++ b/docs/integrations/kilocode.md @@ -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. diff --git a/docs/integrations/mcp-server.md b/docs/integrations/mcp-server.md index eda8b8879..dfc4f7897 100644 --- a/docs/integrations/mcp-server.md +++ b/docs/integrations/mcp-server.md @@ -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. diff --git a/docs/integrations/mux.md b/docs/integrations/mux.md index aca4c10ba..6e6ee66dd 100644 --- a/docs/integrations/mux.md +++ b/docs/integrations/mux.md @@ -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. diff --git a/docs/integrations/opencode.md b/docs/integrations/opencode.md index 3ba072864..93135d4df 100644 --- a/docs/integrations/opencode.md +++ b/docs/integrations/opencode.md @@ -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. diff --git a/docs/integrations/windsurf.md b/docs/integrations/windsurf.md index 85e05c22c..224f3e57a 100644 --- a/docs/integrations/windsurf.md +++ b/docs/integrations/windsurf.md @@ -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. diff --git a/docs/multi-agent/coordination.md b/docs/multi-agent/coordination.md index 890b1748c..89b78dd5c 100644 --- a/docs/multi-agent/coordination.md +++ b/docs/multi-agent/coordination.md @@ -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. diff --git a/docs/multi-agent/federation.md b/docs/multi-agent/federation.md index fdeae30eb..107abb369 100644 --- a/docs/multi-agent/federation.md +++ b/docs/multi-agent/federation.md @@ -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` diff --git a/docs/multi-agent/index.md b/docs/multi-agent/index.md index 0f9fd1676..c0f05d0e5 100644 --- a/docs/multi-agent/index.md +++ b/docs/multi-agent/index.md @@ -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. diff --git a/docs/multi-agent/multi-repo-migration.md b/docs/multi-agent/multi-repo-migration.md index e0cf317fa..82d67103d 100644 --- a/docs/multi-agent/multi-repo-migration.md +++ b/docs/multi-agent/multi-repo-migration.md @@ -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 diff --git a/docs/multi-agent/routing.md b/docs/multi-agent/routing.md index 6a2da06ce..fe85d9684 100644 --- a/docs/multi-agent/routing.md +++ b/docs/multi-agent/routing.md @@ -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 diff --git a/docs/recovery/init-safety.md b/docs/recovery/init-safety.md index 388842045..412f625bb 100644 --- a/docs/recovery/init-safety.md +++ b/docs/recovery/init-safety.md @@ -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 diff --git a/docs/recovery/uninstalling.md b/docs/recovery/uninstalling.md index b3185f970..c3cb73af3 100644 --- a/docs/recovery/uninstalling.md +++ b/docs/recovery/uninstalling.md @@ -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` diff --git a/docs/reference/advanced.md b/docs/reference/advanced.md index f8e4d80e7..ee9bed9dc 100644 --- a/docs/reference/advanced.md +++ b/docs/reference/advanced.md @@ -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. diff --git a/docs/reference/antivirus.md b/docs/reference/antivirus.md index 5b20ab8a3..e63aa6109 100644 --- a/docs/reference/antivirus.md +++ b/docs/reference/antivirus.md @@ -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 diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 01eb18604..eab6620ad 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -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. diff --git a/docs/reference/faq.md b/docs/reference/faq.md index 3cc420029..670145e6e 100644 --- a/docs/reference/faq.md +++ b/docs/reference/faq.md @@ -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::` 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 ` 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 `. 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 push ` 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 diff --git a/docs/reference/git-integration.md b/docs/reference/git-integration.md index 0f2980b3c..dd6409cd4 100644 --- a/docs/reference/git-integration.md +++ b/docs/reference/git-integration.md @@ -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. diff --git a/docs/reference/json-schema.md b/docs/reference/json-schema.md index f4492be1a..7b3030b0d 100644 --- a/docs/reference/json-schema.md +++ b/docs/reference/json-schema.md @@ -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 diff --git a/docs/reference/observability.md b/docs/reference/observability.md index 535490628..68a2b9d1e 100644 --- a/docs/reference/observability.md +++ b/docs/reference/observability.md @@ -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. diff --git a/docs/reference/protected-branches.md b/docs/reference/protected-branches.md index 1086e79e4..0496f5387 100644 --- a/docs/reference/protected-branches.md +++ b/docs/reference/protected-branches.md @@ -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 diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index 1cfd663b6..505548439 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -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 diff --git a/docs/reference/worktrees.md b/docs/reference/worktrees.md index 8d4d59ca2..6fd87b340 100644 --- a/docs/reference/worktrees.md +++ b/docs/reference/worktrees.md @@ -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 diff --git a/docs/related-projects.md b/docs/related-projects.md index b9b42dcd3..234b15350 100644 --- a/docs/related-projects.md +++ b/docs/related-projects.md @@ -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. diff --git a/docs/workflows/formulas.md b/docs/workflows/formulas.md index 4d38a050a..d44b8b85d 100644 --- a/docs/workflows/formulas.md +++ b/docs/workflows/formulas.md @@ -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. diff --git a/docs/workflows/molecules.md b/docs/workflows/molecules.md index 60d5c6df4..060386f1b 100644 --- a/docs/workflows/molecules.md +++ b/docs/workflows/molecules.md @@ -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 diff --git a/docs/workflows/todo.md b/docs/workflows/todo.md index 9f86621ca..69d57bb0c 100644 --- a/docs/workflows/todo.md +++ b/docs/workflows/todo.md @@ -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.