docs: document bd setup command

Add comprehensive documentation for the bd setup command which was
largely undocumented (GH#518):

- CLI_REFERENCE.md: Add new "Editor Integration" section documenting
  bd setup claude/cursor/aider commands with all flags
- INSTALLING.md: Fix incorrect reference to "bd hooks install" for
  editor integration - should be "bd setup <editor>"
- CLAUDE_INTEGRATION.md: Add Installation section with bd setup claude
  examples

Fixes: GH#518

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.beads/.gitignore

@@ -30,3 +30,5 @@ beads.right.meta.json
 !issues.jsonl
 !metadata.json
 !config.json
+deletions.jsonl
+deletions.jsonl.migrated

.beads/BD_GUIDE.md

@@ -1,4 +1,4 @@
-<!-- Auto-generated by bd v0.29.0 - DO NOT EDIT MANUALLY -->
+<!-- Auto-generated by bd v0.24.2 - DO NOT EDIT MANUALLY -->
 <!-- Run 'bd onboard --output .beads/BD_GUIDE.md' to regenerate -->
 
 # BD (Beads) Guide for AI Agents
@@ -33,7 +33,6 @@ bd ready --json
 ```bash
 bd create "Issue title" -t bug|feature|task -p 0-4 --json
 bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
-bd create "Subtask" --parent <epic-id> --json  # Hierarchical subtask (gets ID like epic-id.1)
 ```
 
 **Claim and update:**
@@ -133,11 +132,6 @@ history/
 - ✅ Preserves planning history for archeological research
 - ✅ Reduces noise when browsing the project
 
-### CLI Help
-
-Run `bd <command> --help` to see all available flags for any command.
-For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.
-
 ### Important Rules
 
 - ✅ Use bd for ALL task tracking
@@ -145,7 +139,6 @@ For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.
 - ✅ Link discovered work with `discovered-from` dependencies
 - ✅ Check `bd ready` before asking "what should I work on?"
 - ✅ Store AI planning docs in `history/` directory
-- ✅ Run `bd <cmd> --help` to discover available flags
 - ❌ Do NOT create markdown TODO lists
 - ❌ Do NOT use external issue trackers
 - ❌ Do NOT duplicate tracking systems
@@ -155,11 +148,11 @@ For more details, see README.md and QUICKSTART.md.
 
 ---
 
-# GitHub Copilot Instructions
+# GitHub Copilot Instructions for Beads
 
-## Issue Tracking with bd
+## Project Overview
 
-This project uses **bd (beads)** for issue tracking - a Git-backed tracker designed for AI-supervised coding workflows.
+**beads** (command: `bd`) is a Git-backed issue tracker designed for AI-supervised coding workflows. We dogfood our own tool for all task tracking.
 
 **Key Features:**
 - Dependency-aware issue tracking
@@ -168,7 +161,37 @@ This project uses **bd (beads)** for issue tracking - a Git-backed tracker desig
 - Built-in daemon for background operations
 - MCP server integration for Claude and other AI assistants
 
-**CRITICAL**: Use bd for ALL task tracking. Do NOT create markdown TODO lists.
+## Tech Stack
+
+- **Language**: Go 1.21+
+- **Storage**: SQLite (internal/storage/sqlite/)
+- **CLI Framework**: Cobra
+- **Testing**: Go standard testing + table-driven tests
+- **CI/CD**: GitHub Actions
+- **MCP Server**: Python (integrations/beads-mcp/)
+
+## Coding Guidelines
+
+### Testing
+- Always write tests for new features
+- Use `BEADS_DB=/tmp/test.db` to avoid polluting production database
+- Run `go test -short ./...` before committing
+- Never create test issues in production DB (use temporary DB)
+
+### Code Style
+- Run `golangci-lint run ./...` before committing
+- Follow existing patterns in `cmd/bd/` for new commands
+- Add `--json` flag to all commands for programmatic use
+- Update docs when changing behavior
+
+### Git Workflow
+- Always commit `.beads/issues.jsonl` with code changes
+- Run `bd sync` at end of work sessions
+- Install git hooks: `bd hooks install` (ensures DB ↔ JSONL consistency)
+
+## Issue Tracking with bd
+
+**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists.
 
 ### Essential Commands
 
@@ -179,7 +202,6 @@ bd stale --days 30 --json          # Forgotten issues
 
 # Create and manage
 bd create "Title" -t bug|feature|task -p 0-4 --json
-bd create "Subtask" --parent <epic-id> --json  # Hierarchical subtask
 bd update <id> --status in_progress --json
 bd close <id> --reason "Done" --json
 
@@ -208,35 +230,60 @@ bd sync  # Force immediate export/commit/push
 - `3` - Low (polish, optimization)
 - `4` - Backlog (future ideas)
 
-### Git Workflow
+## Project Structure
 
-- Always commit `.beads/issues.jsonl` with code changes
+```
-- Run `bd sync` at end of work sessions
+beads/
-- Install git hooks: `bd hooks install` (ensures DB ↔ JSONL consistency)
+├── cmd/bd/              # CLI commands (add new commands here)
+├── internal/
+│   ├── types/           # Core data types
+│   └── storage/         # Storage layer
+│       └── sqlite/      # SQLite implementation
+├── integrations/
+│   └── beads-mcp/       # MCP server (Python)
+├── examples/            # Integration examples
+├── docs/                # Documentation
+└── .beads/
+    ├── beads.db         # SQLite database (DO NOT COMMIT)
+    └── issues.jsonl     # Git-synced issue storage
+```
+
+## Available Resources
 
 ### MCP Server (Recommended)
-
+Use the beads MCP server for native function calls instead of shell commands:
-For MCP-compatible clients (Claude Desktop, etc.), install the beads MCP server:
 - Install: `pip install beads-mcp`
 - Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc.
+- See `integrations/beads-mcp/README.md`
 
-## CLI Help
+### Scripts
+- `./scripts/bump-version.sh <version> --commit` - Update all version files atomically
+- `./scripts/release.sh <version>` - Complete release workflow
+- `./scripts/update-homebrew.sh <version>` - Update Homebrew formula
 
-Run `bd <command> --help` to see all available flags for any command.
+### Key Documentation
-For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.
+- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features)
+- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases
+- **README.md** - User-facing documentation
+- **docs/CLI_REFERENCE.md** - Complete command reference
 
 ## Important Rules
 
 - ✅ Use bd for ALL task tracking
 - ✅ Always use `--json` flag for programmatic use
 - ✅ Run `bd sync` at end of sessions
-- ✅ Run `bd <cmd> --help` to discover available flags
+- ✅ Test with `BEADS_DB=/tmp/test.db`
 - ❌ Do NOT create markdown TODO lists
+- ❌ Do NOT create test issues in production DB
 - ❌ Do NOT commit `.beads/beads.db` (JSONL only)
 
 ---
 
-**Generated by bd v0.29.0**
+**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)**
+
+---
+
+**Generated by bd v0.24.2**
 
 To regenerate this file after upgrading bd:
 ```bash

docs/CLAUDE_INTEGRATION.md

@@ -81,6 +81,29 @@ They should be:
 
 Users who want custom Skills can create their own, but beads doesn't ship with or require them.
 
+## Installation
+
+```bash
+# Install Claude Code hooks globally
+bd setup claude
+
+# Install for this project only
+bd setup claude --project
+
+# Use stealth mode (flush only, no git operations)
+bd setup claude --stealth
+
+# Check installation status
+bd setup claude --check
+
+# Remove hooks
+bd setup claude --remove
+```
+
+**What it installs:**
+- SessionStart hook: Runs `bd prime` when Claude Code starts a session
+- PreCompact hook: Runs `bd prime` before context compaction to preserve workflow instructions
+
 ## Related Files
 
 - `cmd/bd/prime.go` - Context generation

docs/CLI_REFERENCE.md

@@ -11,6 +11,7 @@
 - [Filtering & Search](#filtering--search)
 - [Advanced Operations](#advanced-operations)
 - [Database Management](#database-management)
+- [Editor Integration](#editor-integration)
 
 ## Basic Operations
 
@@ -550,6 +551,44 @@ bd sync  # Force immediate sync, bypass debounce
 
 **ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately.
 
+## Editor Integration
+
+### Setup Commands
+
+```bash
+# Setup editor integration (choose based on your editor)
+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
+
+# Check if integration is installed
+bd setup claude --check
+bd setup cursor --check
+bd setup aider --check
+
+# Remove integration
+bd setup claude --remove
+bd setup cursor --remove
+bd setup aider --remove
+```
+
+**Claude Code options:**
+```bash
+bd setup claude              # Install globally (~/.claude/settings.json)
+bd setup claude --project    # Install for this project only
+bd setup claude --stealth    # Use stealth mode (flush only, no git operations)
+```
+
+**What each setup does:**
+- **Claude Code** (`bd setup claude`): Adds hooks to Claude Code's settings.json that run `bd prime` on SessionStart and PreCompact events
+- **Cursor** (`bd setup cursor`): Creates `.cursor/rules/beads.mdc` with workflow instructions
+- **Aider** (`bd setup aider`): Creates `.aider.conf.yml` with bd workflow instructions
+
+See also:
+- [INSTALLING.md](INSTALLING.md#ide-and-editor-integrations) - Installation guide
+- [AIDER_INTEGRATION.md](AIDER_INTEGRATION.md) - Detailed Aider guide
+- [CLAUDE_INTEGRATION.md](CLAUDE_INTEGRATION.md) - Claude integration design
+
 ## See Also
 
 - [AGENTS.md](../AGENTS.md) - Main agent workflow guide

docs/INSTALLING.md

@@ -133,15 +133,17 @@ brew install bd
 cd your-project
 bd init --quiet
 
-# 3. Install hooks for automatic context injection
+# 3. Setup editor integration (choose one)
-bd hooks install
+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:**
-- SessionStart hook runs `bd prime` automatically
+- Editor hooks/rules inject `bd prime` automatically on session start
-- `bd prime` injects ~1-2k tokens of workflow context
+- `bd prime` provides ~1-2k tokens of workflow context
 - You use `bd` CLI commands directly
-- Git hooks auto-sync the database
+- 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
@@ -149,6 +151,13 @@ bd hooks install
 - **Universal** - Works with any editor that has shell access
 - **More sustainable** - Less compute per request
 
+**Verify installation:**
+```bash
+bd setup claude --check   # Check Claude Code integration
+bd setup cursor --check   # Check Cursor integration
+bd setup aider --check    # Check Aider integration
+```
+
 ### Claude Code Plugin (Optional)
 
 For enhanced UX with slash commands: