docs: loss-check merge legacy docs/ originals into the site pages

Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.

The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).

Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.

Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).

Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
This commit is contained in:
Chris Sells 2026-07-10 18:47:23 -07:00
commit 5c2fe0d496
39 changed files with 2600 additions and 7116 deletions

View file

@ -2,7 +2,16 @@
title: GitHub Copilot
---
How to use beads with GitHub Copilot in VS Code.
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.
This page covers **Copilot Chat in VS Code via MCP**. For the terminal-based Copilot CLI plugin installed by `bd setup copilot`, see [Copilot CLI](/integrations/copilot-cli).
## Prerequisites
- VS Code 1.96+ with the GitHub Copilot extension
- A GitHub Copilot subscription (Individual, Business, or Enterprise)
- The beads CLI installed ([installation guide](/getting-started/installation))
- Python 3.10+ or the `uv` package manager
## Setup
@ -10,7 +19,12 @@ How to use beads with GitHub Copilot in VS Code.
1. Install beads-mcp:
```bash
# Using uv (recommended)
uv tool install beads-mcp
# Or using pip / pipx
pip install beads-mcp
pipx install beads-mcp
```
2. Create `.vscode/mcp.json` in your project:
@ -48,6 +62,8 @@ How to use beads with GitHub Copilot in VS Code.
bd init --quiet
```
This creates a `.beads/` directory with the issue database.
4. Reload VS Code
### Verify Setup
@ -65,22 +81,36 @@ Copilot: Created bd-42: Login timeout bug
You: What issues are ready?
Copilot: 3 issues ready: bd-42, bd-99, bd-17
You: Close bd-42, it's fixed
Copilot: Closed bd-42
You: Claim bd-42, I'll take it
Copilot: Claimed bd-42 and started work
You: I found a related bug - the session token isn't refreshed.
File it, linked to bd-42.
Copilot: Created bd-103: Session token not refreshed
Linked as discovered-from bd-42
You: Close bd-42 with reason "Fixed timeout handling"
Copilot: Closed bd-42: Fixed timeout handling
```
Syncing stays on the CLI: run `bd dolt push` at the end of a session. There is no MCP push tool.
## MCP Tools
| Tool | Description |
|------|-------------|
| `beads_ready` | List unblocked issues |
| `beads_create` | Create new issue |
| `beads_show` | Show issue details |
| `beads_update` | Update issue |
| `beads_close` | Close issue |
| `beads_dolt_push` | Push to Dolt remote |
| `beads_dep_add` | Add dependency |
| `beads_dep_tree` | Show dependency tree |
| Tool | Description | You say |
|------|-------------|---------|
| `ready` | List unblocked issues | "What can I work on?" |
| `list` | List issues with filters | "Show all open bugs" |
| `show` | Show issue details, including dependencies and dependents | "Show bd-42 details" |
| `create` | Create new issue | "Create a task for refactoring" |
| `claim` | Atomically claim an issue (assignee + in_progress) | "I'll take bd-42" |
| `update` | Update issue fields | "Set bd-42 to priority 1" |
| `close` | Close an issue | "Complete bd-42" |
| `dep` | Add dependency | "bd-99 blocks bd-42" |
| `blocked` | Show blocked issues and their blockers | "What's blocking my work?" |
| `stats` | Issue counts and average lead time | "How's the backlog?" |
The server also exposes `reopen`, `comment`, `comments`, `note`, `context`, and `admin`; call `discover_tools` for the full catalog.
## Copilot Instructions
@ -96,9 +126,18 @@ Quick reference:
- `bd ready` - Find unblocked work
- `bd create "Title" --type task --priority 2` - Create issue
- `bd close <id>` - Complete work
- `bd dolt push` - Push changes to Dolt remote
- `bd dolt push` - Push changes to Dolt remote (run at session end)
```
## CLI vs MCP
| Approach | Best for | Trade-off |
|----------|----------|-----------|
| **MCP (Copilot Chat)** | Natural language, discovery | Higher token overhead |
| **CLI (terminal)** | Scripting, precision, speed | Requires shell access |
Both work against the same database - use MCP for conversational work, the CLI for quick commands. See [MCP Server](/integrations/mcp-server) for the full trade-off discussion.
## Troubleshooting
### Tools not appearing
@ -113,6 +152,13 @@ Quick reference:
```bash
# Check installation
which beads-mcp
beads-mcp --version
# uv installs to ~/.local/bin - make sure it's on PATH
export PATH="$HOME/.local/bin:$PATH"
# If installed with pip, find it
pip show beads-mcp | grep Location
# Reinstall if needed
uv tool install beads-mcp --force
@ -124,6 +170,18 @@ uv tool install beads-mcp --force
bd init --quiet
```
### Changes not persisting
Push to the Dolt remote at the end of your session, from the terminal:
```bash
bd dolt push
```
### Organization policies blocking MCP
For Copilot Business/Enterprise, your organization must enable the "MCP servers in Copilot" policy. Contact your admin if MCP tools don't appear despite a correct config.
## FAQ
### Do I need to clone beads?
@ -132,10 +190,20 @@ bd init --quiet
### What about git hooks?
Git hooks are optional. They refresh exports and legacy fallback checks, while issue sync uses `bd dolt push` / `bd dolt pull`.
Git hooks are optional. They refresh exports and legacy fallback checks, while issue sync uses `bd dolt push` / `bd dolt pull`. They never modify your source code; skip them with `bd init --skip-hooks`.
### Can I use beads without Copilot?
Yes. The same database works from the terminal, [Claude Code](/integrations/claude-code), [Cursor](/integrations/cursor), [Aider](/integrations/aider), and any editor with MCP or shell access.
### Does this work with Copilot in other editors?
This page covers VS Code. For JetBrains IDEs, check whether your IDE supports MCP; the config location differs. For Neovim, use the CLI directly. For the terminal, see [Copilot CLI](/integrations/copilot-cli).
## See Also
- [MCP Server](/integrations/mcp-server) - Detailed MCP configuration
- [Copilot CLI](/integrations/copilot-cli) - Terminal-based Copilot integration
- [Quickstart](/getting-started/quickstart) - bd command basics
- [Installation](/getting-started/installation) - Full install guide
- [Detailed Copilot Guide](https://github.com/gastownhall/beads/blob/main/docs/COPILOT_INTEGRATION.md) - Comprehensive documentation
- [Agent Instructions](https://github.com/gastownhall/beads/blob/main/AGENT_INSTRUCTIONS.md) - Full agent workflow reference