feat: add llms.txt standard support for AI agent discoverability (#784)
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml from joyshmitz's PR. Fixed workflow to trigger on main branch instead of docs/docusaurus-site. Features: - Docusaurus documentation site with llms.txt support - Environment-variable driven config (defaults to steveyegge org) - Automated llms-full.txt generation from docs - GitHub Pages deployment workflow Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
This commit is contained in:
Steve Yegge
156
website/docs/getting-started/ide-setup.md
Normal file
156
website/docs/getting-started/ide-setup.md
Normal file
@@ -0,0 +1,156 @@
|
||||
---
|
||||
id: ide-setup
|
||||
title: IDE Setup
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# IDE Setup for AI Agents
|
||||
|
||||
Configure your IDE for optimal beads integration.
|
||||
|
||||
## Claude Code
|
||||
|
||||
The recommended approach for Claude Code:
|
||||
|
||||
```bash
|
||||
# Setup Claude Code integration
|
||||
bd setup claude
|
||||
```
|
||||
|
||||
This installs:
|
||||
- **SessionStart hook** - Runs `bd prime` when Claude Code starts
|
||||
- **PreCompact hook** - Ensures `bd sync` before context compaction
|
||||
|
||||
**How it works:**
|
||||
1. SessionStart hook runs `bd prime` automatically
|
||||
2. `bd prime` injects ~1-2k tokens of workflow context
|
||||
3. You use `bd` CLI commands directly
|
||||
4. Git hooks auto-sync the database
|
||||
|
||||
**Verify installation:**
|
||||
```bash
|
||||
bd setup claude --check
|
||||
```
|
||||
|
||||
### Manual Setup
|
||||
|
||||
If you prefer manual configuration, add to your Claude Code hooks:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": ["bd prime"],
|
||||
"PreCompact": ["bd sync"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Cursor IDE
|
||||
|
||||
```bash
|
||||
# Setup Cursor integration
|
||||
bd setup cursor
|
||||
```
|
||||
|
||||
This creates `.cursor/rules/beads.mdc` with beads-aware rules.
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
bd setup cursor --check
|
||||
```
|
||||
|
||||
## Aider
|
||||
|
||||
```bash
|
||||
# Setup Aider integration
|
||||
bd setup aider
|
||||
```
|
||||
|
||||
This creates/updates `.aider.conf.yml` with beads context.
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
bd setup aider --check
|
||||
```
|
||||
|
||||
## Context Injection with `bd prime`
|
||||
|
||||
All integrations use `bd prime` to inject context:
|
||||
|
||||
```bash
|
||||
bd prime
|
||||
```
|
||||
|
||||
This outputs a compact (~1-2k tokens) workflow reference including:
|
||||
- Available commands
|
||||
- Current project status
|
||||
- Workflow patterns
|
||||
- Best practices
|
||||
|
||||
**Why context efficiency matters:**
|
||||
- Compute cost scales with tokens
|
||||
- Latency increases with context size
|
||||
- Models attend better to smaller, focused contexts
|
||||
|
||||
## MCP Server (Alternative)
|
||||
|
||||
For MCP-only environments (Claude Desktop, no shell access):
|
||||
|
||||
```bash
|
||||
# Install MCP server
|
||||
pip install beads-mcp
|
||||
```
|
||||
|
||||
Add to Claude Desktop config:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Trade-offs:**
|
||||
- Works in MCP-only environments
|
||||
- Higher context overhead (10-50k tokens for tool schemas)
|
||||
- Additional latency from MCP protocol
|
||||
|
||||
See [MCP Server](/integrations/mcp-server) for detailed configuration.
|
||||
|
||||
## Git Hooks
|
||||
|
||||
Ensure git hooks are installed for auto-sync:
|
||||
|
||||
```bash
|
||||
bd hooks install
|
||||
```
|
||||
|
||||
This installs:
|
||||
- **pre-commit** - Validates changes before commit
|
||||
- **post-merge** - Imports changes after pull
|
||||
- **pre-push** - Ensures sync before push
|
||||
|
||||
**Check hook status:**
|
||||
```bash
|
||||
bd info # Shows warnings if hooks are outdated
|
||||
```
|
||||
|
||||
## Verifying Your Setup
|
||||
|
||||
Run a complete health check:
|
||||
|
||||
```bash
|
||||
# Check version
|
||||
bd version
|
||||
|
||||
# Check daemon
|
||||
bd info
|
||||
|
||||
# Check hooks
|
||||
bd hooks status
|
||||
|
||||
# Check editor integration
|
||||
bd setup claude --check # or cursor, aider
|
||||
```
|
||||
209
website/docs/getting-started/installation.md
Normal file
209
website/docs/getting-started/installation.md
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
id: installation
|
||||
title: Installation
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Installing bd
|
||||
|
||||
Complete installation guide for all platforms.
|
||||
|
||||
## Quick Install (Recommended)
|
||||
|
||||
### Homebrew (macOS/Linux)
|
||||
|
||||
```bash
|
||||
brew tap steveyegge/beads
|
||||
brew install bd
|
||||
```
|
||||
|
||||
**Why Homebrew?**
|
||||
- Simple one-command install
|
||||
- Automatic updates via `brew upgrade`
|
||||
- No need to install Go
|
||||
- Handles PATH setup automatically
|
||||
|
||||
### Quick Install Script (All Platforms)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
The installer will:
|
||||
- Detect your platform (macOS/Linux, amd64/arm64)
|
||||
- Install via `go install` if Go is available
|
||||
- Fall back to building from source if needed
|
||||
- Guide you through PATH setup if necessary
|
||||
|
||||
## Platform-Specific Installation
|
||||
|
||||
### macOS
|
||||
|
||||
**Via Homebrew** (recommended):
|
||||
```bash
|
||||
brew tap steveyegge/beads
|
||||
brew install bd
|
||||
```
|
||||
|
||||
**Via go install**:
|
||||
```bash
|
||||
go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
**From source**:
|
||||
```bash
|
||||
git clone https://github.com/steveyegge/beads
|
||||
cd beads
|
||||
go build -o bd ./cmd/bd
|
||||
sudo mv bd /usr/local/bin/
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
**Via Homebrew** (works on Linux too):
|
||||
```bash
|
||||
brew tap steveyegge/beads
|
||||
brew install bd
|
||||
```
|
||||
|
||||
**Arch Linux** (AUR):
|
||||
```bash
|
||||
# Install from AUR
|
||||
yay -S beads-git
|
||||
# or
|
||||
paru -S beads-git
|
||||
```
|
||||
|
||||
**Via go install**:
|
||||
```bash
|
||||
go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
### Windows 11
|
||||
|
||||
Beads ships with native Windows support—no MSYS or MinGW required.
|
||||
|
||||
**Prerequisites:**
|
||||
- [Go 1.24+](https://go.dev/dl/) installed (add `%USERPROFILE%\go\bin` to your `PATH`)
|
||||
- Git for Windows
|
||||
|
||||
**Via PowerShell script**:
|
||||
```pwsh
|
||||
irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
|
||||
```
|
||||
|
||||
**Via go install**:
|
||||
```pwsh
|
||||
go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
## IDE and Editor Integrations
|
||||
|
||||
### CLI + Hooks (Recommended)
|
||||
|
||||
The recommended approach for Claude Code, Cursor, Windsurf, and other editors with shell access:
|
||||
|
||||
```bash
|
||||
# 1. Install bd CLI (see Quick Install above)
|
||||
brew install bd
|
||||
|
||||
# 2. Initialize in your project
|
||||
cd your-project
|
||||
bd init --quiet
|
||||
|
||||
# 3. Setup editor integration (choose one)
|
||||
bd setup claude # Claude Code - installs SessionStart/PreCompact hooks
|
||||
bd setup cursor # Cursor IDE - creates .cursor/rules/beads.mdc
|
||||
bd setup aider # Aider - creates .aider.conf.yml
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
- Editor hooks/rules inject `bd prime` automatically on session start
|
||||
- `bd prime` provides ~1-2k tokens of workflow context
|
||||
- You use `bd` CLI commands directly
|
||||
- Git hooks (installed by `bd init`) auto-sync the database
|
||||
|
||||
**Why this is recommended:**
|
||||
- **Context efficient** - ~1-2k tokens vs 10-50k for MCP tool schemas
|
||||
- **Lower latency** - Direct CLI calls, no MCP protocol overhead
|
||||
- **Universal** - Works with any editor that has shell access
|
||||
|
||||
### MCP Server (Alternative)
|
||||
|
||||
Use MCP only when CLI is unavailable (Claude Desktop, Sourcegraph Amp without shell):
|
||||
|
||||
```bash
|
||||
# Using uv (recommended)
|
||||
uv tool install beads-mcp
|
||||
|
||||
# Or using pip
|
||||
pip install beads-mcp
|
||||
```
|
||||
|
||||
**Configuration for Claude Desktop** (macOS):
|
||||
|
||||
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Verifying Installation
|
||||
|
||||
After installing, verify bd is working:
|
||||
|
||||
```bash
|
||||
bd version
|
||||
bd help
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `bd: command not found`
|
||||
|
||||
bd is not in your PATH:
|
||||
|
||||
```bash
|
||||
# Check if installed
|
||||
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
|
||||
|
||||
# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc)
|
||||
export PATH="$PATH:$(go env GOPATH)/bin"
|
||||
```
|
||||
|
||||
### `zsh: killed bd` or crashes on macOS
|
||||
|
||||
This is typically caused by CGO/SQLite compatibility issues:
|
||||
|
||||
```bash
|
||||
# Build with CGO enabled
|
||||
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
## Updating bd
|
||||
|
||||
### Homebrew
|
||||
|
||||
```bash
|
||||
brew upgrade bd
|
||||
```
|
||||
|
||||
### go install
|
||||
|
||||
```bash
|
||||
go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
After installation:
|
||||
|
||||
1. **Initialize a project**: `cd your-project && bd init`
|
||||
2. **Learn the basics**: See [Quick Start](/getting-started/quickstart)
|
||||
3. **Configure your agent**: See [IDE Setup](/getting-started/ide-setup)
|
||||
155
website/docs/getting-started/quickstart.md
Normal file
155
website/docs/getting-started/quickstart.md
Normal file
@@ -0,0 +1,155 @@
|
||||
---
|
||||
id: quickstart
|
||||
title: Quick Start
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Beads Quick Start
|
||||
|
||||
Get up and running with Beads in 2 minutes.
|
||||
|
||||
## Initialize
|
||||
|
||||
First time in a repository:
|
||||
|
||||
```bash
|
||||
# Basic setup
|
||||
bd init
|
||||
|
||||
# For AI agents (non-interactive)
|
||||
bd init --quiet
|
||||
|
||||
# OSS contributor (fork workflow)
|
||||
bd init --contributor
|
||||
|
||||
# Team member (branch workflow)
|
||||
bd init --team
|
||||
|
||||
# Protected main branch (GitHub/GitLab)
|
||||
bd init --branch beads-sync
|
||||
```
|
||||
|
||||
The wizard will:
|
||||
- Create `.beads/` directory and database
|
||||
- Import existing issues from git (if any)
|
||||
- Prompt to install git hooks (recommended)
|
||||
- Prompt to configure git merge driver (recommended)
|
||||
- Auto-start daemon for sync
|
||||
|
||||
## Your First Issues
|
||||
|
||||
```bash
|
||||
# Create a few issues
|
||||
bd create "Set up database" -p 1 -t task
|
||||
bd create "Create API" -p 2 -t feature
|
||||
bd create "Add authentication" -p 2 -t feature
|
||||
|
||||
# List them
|
||||
bd list
|
||||
```
|
||||
|
||||
**Note:** Issue IDs are hash-based (e.g., `bd-a1b2`, `bd-f14c`) to prevent collisions when multiple agents/branches work concurrently.
|
||||
|
||||
## Hierarchical Issues (Epics)
|
||||
|
||||
For large features, use hierarchical IDs to organize work:
|
||||
|
||||
```bash
|
||||
# Create epic (generates parent hash ID)
|
||||
bd create "Auth System" -t epic -p 1
|
||||
# Returns: bd-a3f8e9
|
||||
|
||||
# Create child tasks (automatically get .1, .2, .3 suffixes)
|
||||
bd create "Design login UI" -p 1 # bd-a3f8e9.1
|
||||
bd create "Backend validation" -p 1 # bd-a3f8e9.2
|
||||
bd create "Integration tests" -p 1 # bd-a3f8e9.3
|
||||
|
||||
# View hierarchy
|
||||
bd dep tree bd-a3f8e9
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Dependency tree for bd-a3f8e9:
|
||||
|
||||
> bd-a3f8e9: Auth System [epic] [P1] (open)
|
||||
> bd-a3f8e9.1: Design login UI [P1] (open)
|
||||
> bd-a3f8e9.2: Backend validation [P1] (open)
|
||||
> bd-a3f8e9.3: Integration tests [P1] (open)
|
||||
```
|
||||
|
||||
## Add Dependencies
|
||||
|
||||
```bash
|
||||
# API depends on database
|
||||
bd dep add bd-2 bd-1
|
||||
|
||||
# Auth depends on API
|
||||
bd dep add bd-3 bd-2
|
||||
|
||||
# View the tree
|
||||
bd dep tree bd-3
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Dependency tree for bd-3:
|
||||
|
||||
> bd-3: Add authentication [P2] (open)
|
||||
> bd-2: Create API [P2] (open)
|
||||
> bd-1: Set up database [P1] (open)
|
||||
```
|
||||
|
||||
## Find Ready Work
|
||||
|
||||
```bash
|
||||
bd ready
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Ready work (1 issues with no blockers):
|
||||
|
||||
1. [P1] bd-1: Set up database
|
||||
```
|
||||
|
||||
Only bd-1 is ready because bd-2 and bd-3 are blocked!
|
||||
|
||||
## Work the Queue
|
||||
|
||||
```bash
|
||||
# Start working on bd-1
|
||||
bd update bd-1 --status in_progress
|
||||
|
||||
# Complete it
|
||||
bd close bd-1 --reason "Database setup complete"
|
||||
|
||||
# Check ready work again
|
||||
bd ready
|
||||
```
|
||||
|
||||
Now bd-2 is ready!
|
||||
|
||||
## Track Progress
|
||||
|
||||
```bash
|
||||
# See blocked issues
|
||||
bd blocked
|
||||
|
||||
# View statistics
|
||||
bd stats
|
||||
```
|
||||
|
||||
## Database Location
|
||||
|
||||
By default, the database is in `.beads/beads.db` (gitignored).
|
||||
|
||||
The JSONL file `.beads/issues.jsonl` is git-tracked and syncs automatically.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Add labels: `bd create "Task" -l "backend,urgent"`
|
||||
- Filter ready work: `bd ready --priority 1`
|
||||
- Search issues: `bd list --status open`
|
||||
- Detect cycles: `bd dep cycles`
|
||||
- See [CLI Reference](/cli-reference) for all commands
|
||||
126
website/docs/getting-started/upgrading.md
Normal file
126
website/docs/getting-started/upgrading.md
Normal file
@@ -0,0 +1,126 @@
|
||||
---
|
||||
id: upgrading
|
||||
title: Upgrading
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Upgrading bd
|
||||
|
||||
How to upgrade bd and keep your projects in sync.
|
||||
|
||||
## Checking for Updates
|
||||
|
||||
```bash
|
||||
# Current version
|
||||
bd version
|
||||
|
||||
# What's new in recent versions
|
||||
bd info --whats-new
|
||||
bd info --whats-new --json # Machine-readable
|
||||
```
|
||||
|
||||
## Upgrading
|
||||
|
||||
### Homebrew
|
||||
|
||||
```bash
|
||||
brew upgrade bd
|
||||
```
|
||||
|
||||
### go install
|
||||
|
||||
```bash
|
||||
go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
cd beads
|
||||
git pull
|
||||
go build -o bd ./cmd/bd
|
||||
sudo mv bd /usr/local/bin/
|
||||
```
|
||||
|
||||
## After Upgrading
|
||||
|
||||
**Important:** After upgrading, update your hooks and restart daemons:
|
||||
|
||||
```bash
|
||||
# 1. Check what changed
|
||||
bd info --whats-new
|
||||
|
||||
# 2. Update git hooks to match new version
|
||||
bd hooks install
|
||||
|
||||
# 3. Restart all daemons
|
||||
bd daemons killall
|
||||
|
||||
# 4. Check for any outdated hooks
|
||||
bd info # Shows warnings if hooks are outdated
|
||||
```
|
||||
|
||||
**Why update hooks?** Git hooks are versioned with bd. Outdated hooks may miss new auto-sync features or bug fixes.
|
||||
|
||||
## Database Migrations
|
||||
|
||||
After major upgrades, check for database migrations:
|
||||
|
||||
```bash
|
||||
# Inspect migration plan (AI agents)
|
||||
bd migrate --inspect --json
|
||||
|
||||
# Preview migration changes
|
||||
bd migrate --dry-run
|
||||
|
||||
# Apply migrations
|
||||
bd migrate
|
||||
|
||||
# Migrate and clean up old files
|
||||
bd migrate --cleanup --yes
|
||||
```
|
||||
|
||||
## Daemon Version Mismatches
|
||||
|
||||
If you see daemon version mismatch warnings:
|
||||
|
||||
```bash
|
||||
# List all running daemons
|
||||
bd daemons list --json
|
||||
|
||||
# Check for version mismatches
|
||||
bd daemons health --json
|
||||
|
||||
# Restart all daemons with new version
|
||||
bd daemons killall --json
|
||||
```
|
||||
|
||||
## Troubleshooting Upgrades
|
||||
|
||||
### Old daemon still running
|
||||
|
||||
```bash
|
||||
bd daemons killall
|
||||
```
|
||||
|
||||
### Hooks out of date
|
||||
|
||||
```bash
|
||||
bd hooks install
|
||||
```
|
||||
|
||||
### Database schema changed
|
||||
|
||||
```bash
|
||||
bd migrate --dry-run
|
||||
bd migrate
|
||||
```
|
||||
|
||||
### Import errors after upgrade
|
||||
|
||||
Check the import configuration:
|
||||
|
||||
```bash
|
||||
bd config get import.orphan_handling
|
||||
bd import -i .beads/issues.jsonl --orphan-handling allow
|
||||
```
|
||||
Reference in New Issue
Block a user