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:
parent
6455ada0cb
commit
69e33099b8
57 changed files with 110 additions and 39 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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": {
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue