docs: port user docs into the Mintlify site tree under docs/
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
This commit is contained in:
parent
0e017821f4
commit
a86a2c5dfc
77 changed files with 7683 additions and 1908 deletions
141
docs/integrations/github-copilot.md
Normal file
141
docs/integrations/github-copilot.md
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
---
|
||||
title: GitHub Copilot
|
||||
---
|
||||
|
||||
How to use beads with GitHub Copilot in VS Code.
|
||||
|
||||
## Setup
|
||||
|
||||
### Quick Setup
|
||||
|
||||
1. Install beads-mcp:
|
||||
```bash
|
||||
uv tool install beads-mcp
|
||||
```
|
||||
|
||||
2. Create `.vscode/mcp.json` in your project:
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**For all projects:** Add to VS Code user-level MCP config:
|
||||
|
||||
| Platform | Path |
|
||||
|----------|------|
|
||||
| macOS | `~/Library/Application Support/Code/User/mcp.json` |
|
||||
| Linux | `~/.config/Code/User/mcp.json` |
|
||||
| Windows | `%APPDATA%\Code\User\mcp.json` |
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp",
|
||||
"args": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Initialize beads:
|
||||
```bash
|
||||
bd init --quiet
|
||||
```
|
||||
|
||||
4. Reload VS Code
|
||||
|
||||
### Verify Setup
|
||||
|
||||
Ask Copilot Chat: "What beads issues are ready to work on?"
|
||||
|
||||
## Using Natural Language
|
||||
|
||||
With MCP configured, interact naturally:
|
||||
|
||||
```
|
||||
You: Create a bug for the login timeout
|
||||
Copilot: Created bd-42: Login timeout bug
|
||||
|
||||
You: What issues are ready?
|
||||
Copilot: 3 issues ready: bd-42, bd-99, bd-17
|
||||
|
||||
You: Close bd-42, it's fixed
|
||||
Copilot: Closed bd-42
|
||||
```
|
||||
|
||||
## MCP Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `beads_ready` | List unblocked issues |
|
||||
| `beads_create` | Create new issue |
|
||||
| `beads_show` | Show issue details |
|
||||
| `beads_update` | Update issue |
|
||||
| `beads_close` | Close issue |
|
||||
| `beads_dolt_push` | Push to Dolt remote |
|
||||
| `beads_dep_add` | Add dependency |
|
||||
| `beads_dep_tree` | Show dependency tree |
|
||||
|
||||
## Copilot Instructions
|
||||
|
||||
Optionally add `.github/copilot-instructions.md`:
|
||||
|
||||
```markdown
|
||||
## Issue Tracking
|
||||
|
||||
This project uses **bd (beads)** for issue tracking.
|
||||
Run `bd prime` for workflow context.
|
||||
|
||||
Quick reference:
|
||||
- `bd ready` - Find unblocked work
|
||||
- `bd create "Title" --type task --priority 2` - Create issue
|
||||
- `bd close <id>` - Complete work
|
||||
- `bd dolt push` - Push changes to Dolt remote
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Tools not appearing
|
||||
|
||||
1. Check VS Code 1.96+
|
||||
2. Verify mcp.json syntax is valid JSON
|
||||
3. Reload VS Code window
|
||||
4. Check Output panel for MCP errors
|
||||
|
||||
### "beads-mcp not found"
|
||||
|
||||
```bash
|
||||
# Check installation
|
||||
which beads-mcp
|
||||
|
||||
# Reinstall if needed
|
||||
uv tool install beads-mcp --force
|
||||
```
|
||||
|
||||
### No database found
|
||||
|
||||
```bash
|
||||
bd init --quiet
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
### Do I need to clone beads?
|
||||
|
||||
**No.** Beads is a system-wide CLI tool. Install once, use everywhere. The `.beads/` directory in your project only contains the issue database.
|
||||
|
||||
### What about git hooks?
|
||||
|
||||
Git hooks are optional. They refresh exports and legacy fallback checks, while issue sync uses `bd dolt push` / `bd dolt pull`.
|
||||
|
||||
## See Also
|
||||
|
||||
- [MCP Server](/integrations/mcp-server) - Detailed MCP configuration
|
||||
- [Installation](/getting-started/installation) - Full install guide
|
||||
- [Detailed Copilot Guide](https://github.com/gastownhall/beads/blob/main/docs/COPILOT_INTEGRATION.md) - Comprehensive documentation
|
||||
Loading…
Add table
Add a link
Reference in a new issue