Implement BD_GUIDE.md generation for version-stamped documentation (bd-woro)

This implements the ability to separate bd-specific instructions from
project-specific instructions by generating a canonical BD_GUIDE.md file.

## Changes

1. Added `--output` flag to `bd onboard` command
   - Generates version-stamped BD_GUIDE.md at specified path
   - Includes both agentsContent and copilotInstructionsContent
   - Auto-generated header warns against manual editing

2. Version tracking integration
   - checkAndSuggestBDGuideUpdate() detects outdated BD_GUIDE.md
   - Suggests regeneration when bd version changes
   - Integrated with maybeShowUpgradeNotification()

3. Comprehensive test coverage
   - Tests for BD_GUIDE.md generation
   - Tests for version stamp validation
   - Tests for content inclusion

4. Documentation updates
   - Updated AGENTS.md with BD_GUIDE.md workflow
   - Added regeneration instructions to upgrade workflow

## Benefits

- Clear separation of concerns (bd vs project instructions)
- Deterministic updates (no LLM involved)
- Git-trackable diffs show exactly what changed
- Progressive disclosure (agents read when needed)

## Usage

\`\`\`bash
# Generate BD_GUIDE.md
bd onboard --output .beads/BD_GUIDE.md

# After upgrading bd
bd onboard --output .beads/BD_GUIDE.md  # Regenerate
\`\`\`

Closes bd-woro

.beads/BD_GUIDE.md

@@ -0,0 +1,291 @@
+<!-- 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
+
+This file contains canonical bd (beads) workflow instructions for AI agents.
+It is auto-generated and version-stamped to track bd upgrades.
+
+> **For project-specific instructions**, see AGENTS.md in the repository root.
+> This file only covers bd tool usage, not project-specific workflows.
+
+---
+
+## Issue Tracking with bd (beads)
+
+**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
+
+### Why bd?
+
+- Dependency-aware: Track blockers and relationships between issues
+- Git-friendly: Auto-syncs to JSONL for version control
+- Agent-optimized: JSON output, ready work detection, discovered-from links
+- Prevents duplicate tracking systems and confusion
+
+### Quick Start
+
+**Check for ready work:**
+```bash
+bd ready --json
+```
+
+**Create new issues:**
+```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
+```
+
+**Claim and update:**
+```bash
+bd update bd-42 --status in_progress --json
+bd update bd-42 --priority 1 --json
+```
+
+**Complete work:**
+```bash
+bd close bd-42 --reason "Completed" --json
+```
+
+### Issue Types
+
+- `bug` - Something broken
+- `feature` - New functionality
+- `task` - Work item (tests, docs, refactoring)
+- `epic` - Large feature with subtasks
+- `chore` - Maintenance (dependencies, tooling)
+
+### Priorities
+
+- `0` - Critical (security, data loss, broken builds)
+- `1` - High (major features, important bugs)
+- `2` - Medium (default, nice-to-have)
+- `3` - Low (polish, optimization)
+- `4` - Backlog (future ideas)
+
+### Workflow for AI Agents
+
+1. **Check ready work**: `bd ready` shows unblocked issues
+2. **Claim your task**: `bd update <id> --status in_progress`
+3. **Work on it**: Implement, test, document
+4. **Discover new work?** Create linked issue:
+   - `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`
+5. **Complete**: `bd close <id> --reason "Done"`
+6. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state
+
+### Auto-Sync
+
+bd automatically syncs with git:
+- Exports to `.beads/issues.jsonl` after changes (5s debounce)
+- Imports from JSONL when newer (e.g., after `git pull`)
+- No manual export/import needed!
+
+### GitHub Copilot Integration
+
+If using GitHub Copilot, also create `.github/copilot-instructions.md` for automatic instruction loading.
+Run `bd onboard` to get the content, or see step 2 of the onboard instructions.
+
+### MCP Server (Recommended)
+
+If using Claude or MCP-compatible clients, install the beads MCP server:
+
+```bash
+pip install beads-mcp
+```
+
+Add to MCP config (e.g., `~/.config/claude/config.json`):
+```json
+{
+  "beads": {
+    "command": "beads-mcp",
+    "args": []
+  }
+}
+```
+
+Then use `mcp__beads__*` functions instead of CLI commands.
+
+### Managing AI-Generated Planning Documents
+
+AI assistants often create planning and design documents during development:
+- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
+- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
+- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
+
+**Best Practice: Use a dedicated directory for these ephemeral files**
+
+**Recommended approach:**
+- Create a `history/` directory in the project root
+- Store ALL AI-generated planning/design docs in `history/`
+- Keep the repository root clean and focused on permanent project files
+- Only access `history/` when explicitly asked to review past planning
+
+**Example .gitignore entry (optional):**
+```
+# AI planning documents (ephemeral)
+history/
+```
+
+**Benefits:**
+- ✅ Clean repository root
+- ✅ Clear separation between ephemeral and permanent documentation
+- ✅ Easy to exclude from version control if desired
+- ✅ Preserves planning history for archeological research
+- ✅ Reduces noise when browsing the project
+
+### Important Rules
+
+- ✅ Use bd for ALL task tracking
+- ✅ Always use `--json` flag for programmatic use
+- ✅ Link discovered work with `discovered-from` dependencies
+- ✅ Check `bd ready` before asking "what should I work on?"
+- ✅ Store AI planning docs in `history/` directory
+- ❌ Do NOT create markdown TODO lists
+- ❌ Do NOT use external issue trackers
+- ❌ Do NOT duplicate tracking systems
+- ❌ Do NOT clutter repo root with planning documents
+
+For more details, see README.md and QUICKSTART.md.
+
+---
+
+# GitHub Copilot Instructions for Beads
+
+## Project Overview
+
+**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
+- Auto-sync with Git via JSONL
+- AI-optimized CLI with JSON output
+- Built-in daemon for background operations
+- MCP server integration for Claude and other AI assistants
+
+## 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
+
+```bash
+# Find work
+bd ready --json                    # Unblocked issues
+bd stale --days 30 --json          # Forgotten issues
+
+# Create and manage
+bd create "Title" -t bug|feature|task -p 0-4 --json
+bd update <id> --status in_progress --json
+bd close <id> --reason "Done" --json
+
+# Search
+bd list --status open --priority 1 --json
+bd show <id> --json
+
+# Sync (CRITICAL at end of session!)
+bd sync  # Force immediate export/commit/push
+```
+
+### Workflow
+
+1. **Check ready work**: `bd ready --json`
+2. **Claim task**: `bd update <id> --status in_progress`
+3. **Work on it**: Implement, test, document
+4. **Discover new work?** `bd create "Found bug" -p 1 --deps discovered-from:<parent-id> --json`
+5. **Complete**: `bd close <id> --reason "Done" --json`
+6. **Sync**: `bd sync` (flushes changes to git immediately)
+
+### Priorities
+
+- `0` - Critical (security, data loss, broken builds)
+- `1` - High (major features, important bugs)
+- `2` - Medium (default, nice-to-have)
+- `3` - Low (polish, optimization)
+- `4` - Backlog (future ideas)
+
+## Project Structure
+
+```
+beads/
+├── 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:
+- Install: `pip install beads-mcp`
+- Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc.
+- See `integrations/beads-mcp/README.md`
+
+### 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
+
+### Key Documentation
+- **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
+- ✅ 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)
+
+---
+
+**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
+bd onboard --output .beads/BD_GUIDE.md
+```

.beads/beads.jsonl

@@ -22,7 +22,7 @@
 {"id":"bd-0fvq","content_hash":"6fb6e394efe3010fd5d9213669417e5f6376017de4187988d5a6fd0d36c80b40","title":"bd doctor should recommend bd prime migration for existing repos","description":"bd doctor should detect old beads integration patterns and recommend migrating to bd prime approach.\n\n## Current behavior\n- bd doctor checks if Claude hooks are installed globally\n- Doesn't check project-level integration (AGENTS.md, CLAUDE.md)\n- Doesn't recommend migration for repos using old patterns\n\n## Desired behavior\nbd doctor should detect and suggest:\n\n1. **Old slash command pattern detected**\n   - Check for /beads:* references in AGENTS.md, CLAUDE.md\n   - Suggest: These slash commands are deprecated, use bd prime hooks instead\n   \n2. **No agent documentation**\n   - Check if AGENTS.md or CLAUDE.md exists\n   - Suggest: Run 'bd onboard' or 'bd setup claude' to document workflow\n   \n3. **Old MCP-only pattern**\n   - Check for instructions to use MCP tools but no bd prime hooks\n   - Suggest: Add bd prime hooks for better token efficiency\n\n4. **Migration path**\n   - Show: 'Run bd setup claude to add SessionStart/PreCompact hooks'\n   - Show: 'Update AGENTS.md to reference bd prime instead of slash commands'\n\n## Example output\n\n⚠ Warning: Old beads integration detected in CLAUDE.md\n  Found: /beads:* slash command references (deprecated)\n  Recommend: Migrate to bd prime hooks for better token efficiency\n  Fix: Run 'bd setup claude' and update CLAUDE.md\n\n💡 Tip: bd prime + hooks reduces token usage by 80-99% vs slash commands\n  MCP mode: ~50 tokens vs ~10.5k for full MCP scan\n  CLI mode: ~1-2k tokens with automatic context recovery\n\n## Benefits\n- Helps existing repos adopt new best practices\n- Clear migration path for users\n- Better token efficiency messaging","status":"open","priority":2,"issue_type":"feature","created_at":"2025-11-12T03:20:25.567748-08:00","updated_at":"2025-11-12T03:20:25.567748-08:00","source_repo":"."}
 {"id":"bd-0kz8","content_hash":"b641c9c097cdeaa44b090d632eac2f89d89a5c3579f0ea58c8b02320b0fa49f7","title":"Fix default .beads/.gitignore to ignore merge artifacts (GH #274)","description":"Updated the default .gitignore template created by `bd init` to properly ignore merge artifacts and fix overly broad patterns.\n\nChanges:\n- Added `*.db?*` pattern for database files with query strings\n- Added explicit patterns for merge artifacts: beads.{base,left,right}.{jsonl,meta.json}\n- Changed `!*.jsonl` to `!issues.jsonl` to avoid including merge artifact JSONL files\n\nThis fixes GitHub issue #274 reported by rscorer.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-11-09T11:23:25.595551-08:00","updated_at":"2025-11-09T11:23:28.780095-08:00","closed_at":"2025-11-09T11:23:28.780095-08:00","source_repo":"."}
 {"id":"bd-0qeg","content_hash":"50f35dcc442b133e766668f3201f5e4820a66dd05cfac1c5d30595d11806f98e","title":"Fix bd doctor hash ID detection for short all-numeric hashes","description":"bd doctor incorrectly flags hash-based IDs as sequential when they are short (3-4 chars) and all-numeric (e.g., pf-158).\n\nRoot cause: isHashID() in cmd/bd/migrate_hash_ids.go:328-358 uses faulty heuristic:\n- For IDs \u003c 5 chars, only returns true if contains letters\n- But base36 hash IDs can be 3+ chars and all-numeric (MinLength: 3)\n- Example: pf-158 is valid hash ID but flagged as sequential\n\nFix: Check multiple IDs (10-20 samples) instead of single-ID pattern matching:\n- Sample IDs across database \n- Check majority pattern (sequential vs hash format)\n- Sequential: 1-4 digits (bd-1, bd-2...)\n- Hash: 3-8 chars base36 (pf-158, pf-3s9...)\n\nImpact: False positive warnings in bd doctor output","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-11-16T13:45:20.733761-08:00","updated_at":"2025-11-16T14:27:48.143485-08:00","closed_at":"2025-11-16T14:27:48.143485-08:00","source_repo":"."}
-{"id":"bd-0tr0","content_hash":"6bcdf8cba6934e0d8b703a2c5a35297db3bf31c83513d78cdd633c05a737973d","title":"Claude Code frequently creates issues with empty descriptions","description":"## Problem\n\nUsers report that Claude Code creates beads issues with titles but no descriptions when asked to analyze code and create issues. Discussion #366 on GitHub highlights this.\n\n## Evidence\n\nAnalysis of our own projects shows significant rates of empty descriptions:\n- ~/src/beads: 110 empty / 630 total (17.5%)\n- ~/wyvern: 8 empty / 119 total (6.7%)\n- ~/src/vc: 3 empty / 170 total (1.8%)\n\nExamples of real issues with no description:\n- [deleted:bd-5qim]: Optimize GetReadyWork performance\n- bd-ge7/vc-7kln: Improve test coverage (appears in multiple projects)\n- Package-specific test coverage tasks (bd-m0w, bd-4h3, bd-t3b, bd-e92)\n- Wyvern testing tasks (wy-3hx, wy-qc9, wy-66)\n\nMany date from Nov 20-21, suggesting batch creation operations.\n\n## Impact\n\n- Issues lack context for future work\n- Harder to prioritize without understanding scope\n- Need manual follow-up to add details\n- Poor workflow experience for users\n\n## Related\n\n- GitHub Discussion #366: https://github.com/steveyegge/beads/discussions/366","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-23T13:59:45.931488-08:00","updated_at":"2025-11-23T20:22:04.259399-08:00","source_repo":"."}
+{"id":"bd-0tr0","content_hash":"6bcdf8cba6934e0d8b703a2c5a35297db3bf31c83513d78cdd633c05a737973d","title":"Claude Code frequently creates issues with empty descriptions","description":"## Problem\n\nUsers report that Claude Code creates beads issues with titles but no descriptions when asked to analyze code and create issues. Discussion #366 on GitHub highlights this.\n\n## Evidence\n\nAnalysis of our own projects shows significant rates of empty descriptions:\n- ~/src/beads: 110 empty / 630 total (17.5%)\n- ~/wyvern: 8 empty / 119 total (6.7%)\n- ~/src/vc: 3 empty / 170 total (1.8%)\n\nExamples of real issues with no description:\n- [deleted:bd-5qim]: Optimize GetReadyWork performance\n- bd-ge7/vc-7kln: Improve test coverage (appears in multiple projects)\n- Package-specific test coverage tasks (bd-m0w, bd-4h3, bd-t3b, bd-e92)\n- Wyvern testing tasks (wy-3hx, wy-qc9, wy-66)\n\nMany date from Nov 20-21, suggesting batch creation operations.\n\n## Impact\n\n- Issues lack context for future work\n- Harder to prioritize without understanding scope\n- Need manual follow-up to add details\n- Poor workflow experience for users\n\n## Related\n\n- GitHub Discussion #366: https://github.com/steveyegge/beads/discussions/366","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-23T13:59:45.931488-08:00","updated_at":"2025-11-23T21:11:04.522351-08:00","closed_at":"2025-11-23T21:11:04.522351-08:00","source_repo":"."}
 {"id":"bd-0vfe","content_hash":"e142bd97d91f70e50e8fea0681d8cdcffb17f17fdbd4c106d56607e243005d21","title":"Blocked issue","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-07T19:07:17.105974-08:00","updated_at":"2025-11-07T22:07:17.342098-08:00","closed_at":"2025-11-07T21:55:09.425545-08:00","source_repo":"."}
 {"id":"bd-1022","content_hash":"0b712a337844711597d2dd950d27d4c032a3b746a27f44326d62db740f5944e9","title":"Use external_ref as primary matching key for import updates","description":"Enable re-syncing from external systems (Jira, GitHub, Linear) by using external_ref as the primary matching key during imports. Currently imports treat any content change as a collision, making it impossible to sync updates from external systems without creating duplicates.\n\nSee GH #142 for detailed proposal and implementation plan.\n\nKey changes needed:\n1. Add findByExternalRef() query function\n2. Update DetectCollisions() to match by external_ref first\n3. Update import_shared.go to update existing issues when external_ref matches\n4. Add index on external_ref for performance\n5. Preserve local issues (no external_ref) from being overwritten\n\nThis enables hybrid workflows: import external backlog, break down with local tasks, re-sync anytime.","notes":"## Code Review Complete ✅\n\n**Overall Assessment**: EXCELLENT - Production ready\n\n### Implementation Quality\n- ✓ Clean architecture with proper interface extension\n- ✓ Dual backend support (SQLite + Memory)\n- ✓ Smart matching priority: external_ref → ID → content hash\n- ✓ O(1) lookups with database index\n- ✓ Timestamp-based conflict resolution\n- ✓ Comprehensive test coverage (11 test cases)\n\n### Follow-up Issues Filed\nHigh Priority (P2):\n- bd-897a: Add UNIQUE constraint on external_ref column\n- bd-7315: Add validation for duplicate external_ref in batch imports\n\nMedium Priority (P3):\n- bd-f9a1: Add index usage verification test\n- bd-3f6a: Add concurrent import race condition tests\n\nLow Priority (P4):\n- bd-e166: Improve timestamp comparison readability\n- bd-9e23: Optimize Memory backend with index\n- bd-537e: Add external_ref change tracking\n- bd-df11: Add import metrics\n- bd-9f4a: Document external_ref in content hash\n\n### Key Features\n✅ External systems (Jira, GitHub, Linear) can re-sync without duplicates\n✅ Hybrid workflows: import external backlog, add local tasks, re-sync anytime\n✅ Local issues protected from being overwritten\n✅ Timestamp checking ensures only newer updates applied\n✅ Performance optimized with database index\n\n**Confidence Level**: 95% - Ship it! 🚀","status":"closed","priority":0,"issue_type":"feature","created_at":"2025-11-02T14:55:56.355813-08:00","updated_at":"2025-11-02T15:34:56.634126-08:00","closed_at":"2025-11-02T15:27:44.810375-08:00","source_repo":"."}
 {"id":"bd-1048","content_hash":"1a889d79a98f8c0919f99094736ee7c856c6d8a2ee062a0add49ce2c06c40174","title":"Daemon crashes silently on RPC query after startup","description":"The daemon fails to handle 'show' RPC commands when:\n1) JSONL is newer than database (needs import)\n2) git pull fails due to uncommitted changes\n\nSymptoms:\n- Daemon appears to run (ps shows process)\n- 'bd list' and other commands work fine  \n- 'bd show \u003cid\u003e' returns \"failed to read response: EOF\"\n- No panic or error logged in daemon.log\n\nRoot cause likely: auto-import deadlock or state corruption when import is blocked by git conflicts.\n\nWorkaround: \n- Restart daemon after syncing git state (commit/push changes)\n- OR use --no-daemon flag for all commands\n\nThe panic recovery added in server_lifecycle_conn.go:183 didn't catch any panics, confirming this isn't a panic-based crash.","notes":"Root cause found and fixed: Two bugs - (1) nil pointer check missing in handleShow causing panic, (2) double JSON encoding in show.go ID resolution. Both fixed. bd show now works with daemon.","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-11-02T17:05:03.658333-08:00","updated_at":"2025-11-03T12:08:12.947672-08:00","closed_at":"2025-11-03T12:08:12.947676-08:00","source_repo":"."}
@@ -647,7 +647,7 @@
 {"id":"bd-wfmw","content_hash":"21706f1701be9fb51fa9e17d1dded6343bc2585e4bdb608239a20c5853d00220","title":"Integration Layer Implementation","description":"Build the adapter layer that makes Agent Mail optional and non-intrusive.","notes":"Progress: bd-m9th (Python adapter library) completed with full test coverage. Next: bd-fzbg (update python-agent example with Agent Mail integration).","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-11-07T22:42:09.356429-08:00","updated_at":"2025-11-08T00:20:30.888756-08:00","closed_at":"2025-11-08T00:20:30.888756-08:00","source_repo":".","dependencies":[{"issue_id":"bd-wfmw","depends_on_id":"bd-spmx","type":"blocks","created_at":"2025-11-07T22:42:09.357488-08:00","created_by":"daemon"}]}
 {"id":"bd-wgu4","content_hash":"31cf5cc105fee5de26f4c2756b8368c90b18eb5f65c656eb0d90f96b23daf21d","title":"Standardize daemon detection: use tryDaemonLock probe before RPC","description":"Before attempting RPC connection, call tryDaemonLock() to check if lock is held:\n- If lock NOT held: skip RPC attempt (no daemon running)\n- If lock IS held: proceed with RPC + short timeout\n\nThis is extremely cheap and eliminates unnecessary connection attempts.\n\nApply across all client entry points that probe for daemon.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-07T16:42:12.709802-08:00","updated_at":"2025-11-07T20:15:23.282181-08:00","closed_at":"2025-11-07T20:15:23.282181-08:00","source_repo":".","dependencies":[{"issue_id":"bd-wgu4","depends_on_id":"bd-ndyz","type":"discovered-from","created_at":"2025-11-07T16:42:12.710564-08:00","created_by":"daemon"}]}
 {"id":"bd-wh24","content_hash":"86122b8c5ab2eae17b7d6ab92f0f21a40f2c3ad733f6a1ee40376018d792ff99","title":"Fix Windows test failure: File permissions in TestAtomicWriteFile","description":"On Windows, file permissions work differently. The test expects 0600 but gets 0666. Windows doesn't support Unix-style file permissions in the same way. Need to either skip this check on Windows or adjust expectations.\n\nTest failure: utils_test.go:39: file permissions mismatch: got 666, want 600\n\nRoot cause: Windows filesystem doesn't support Unix-style permission bits. Need to use runtime.GOOS check or skip permission validation on Windows.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-23T20:16:14.190555-08:00","updated_at":"2025-11-23T20:16:14.190555-08:00","source_repo":"."}
-{"id":"bd-woro","content_hash":"c638f71927d96ea8e8f8aeeb9f8bcd236241124fbaf1589d2b62977b64db3ebb","title":"Separate canonical BD_GUIDE.md from AGENTS.md","description":"Create architectural separation between bd-specific instructions and project-specific instructions.\n\n## Problem\nCurrently AGENTS.md mixes:\n- bd tool documentation (changes with bd upgrades)\n- Project-specific workflow (stable, manually maintained)\n\nThis makes it hard to update bd instructions without touching project docs.\n\n## Solution\n1. Generate .beads/BD_GUIDE.md from 'bd onboard' output\n2. Mark it as auto-generated (never manually edit)\n3. Version-stamp header with bd version\n4. AGENTS.md references it instead of duplicating content\n5. Auto-update BD_GUIDE.md when bd version changes\n\n## Implementation\n- Add 'bd onboard --output .beads/BD_GUIDE.md' option\n- Detect version changes and offer to regenerate\n- Add header: '\u003c!-- Auto-generated by bd v0.24.2 - DO NOT EDIT --\u003e'\n- Update AGENTS.md to reference BD_GUIDE.md\n\n## Benefits\n- Clear separation of concerns\n- Deterministic updates (no agent LLM involved)\n- Git-trackable diffs show exactly what changed\n- Progressive disclosure (agents read when needed)\n\n## Acceptance Criteria\n- BD_GUIDE.md auto-generated and version-stamped\n- AGENTS.md references it appropriately\n- Upgrade workflow auto-updates BD_GUIDE.md\n- Git diffs clearly show bd instruction changes\n","status":"open","priority":3,"issue_type":"feature","created_at":"2025-11-23T16:21:55.451925-08:00","updated_at":"2025-11-23T16:21:55.451925-08:00","source_repo":".","dependencies":[{"issue_id":"bd-woro","depends_on_id":"bd-nxgk","type":"parent-child","created_at":"2025-11-23T16:21:55.453758-08:00","created_by":"daemon"}]}
+{"id":"bd-woro","content_hash":"ea0cffdac7fcc712387fbeece501de3e8d6be739822141bd48ea8a5b953be156","title":"Separate canonical BD_GUIDE.md from AGENTS.md","description":"Create architectural separation between bd-specific instructions and project-specific instructions.\n\n## Problem\nCurrently AGENTS.md mixes:\n- bd tool documentation (changes with bd upgrades)\n- Project-specific workflow (stable, manually maintained)\n\nThis makes it hard to update bd instructions without touching project docs.\n\n## Solution\n1. Generate .beads/BD_GUIDE.md from 'bd onboard' output\n2. Mark it as auto-generated (never manually edit)\n3. Version-stamp header with bd version\n4. AGENTS.md references it instead of duplicating content\n5. Auto-update BD_GUIDE.md when bd version changes\n\n## Implementation\n- Add 'bd onboard --output .beads/BD_GUIDE.md' option\n- Detect version changes and offer to regenerate\n- Add header: '\u003c!-- Auto-generated by bd v0.24.2 - DO NOT EDIT --\u003e'\n- Update AGENTS.md to reference BD_GUIDE.md\n\n## Benefits\n- Clear separation of concerns\n- Deterministic updates (no agent LLM involved)\n- Git-trackable diffs show exactly what changed\n- Progressive disclosure (agents read when needed)\n\n## Acceptance Criteria\n- BD_GUIDE.md auto-generated and version-stamped\n- AGENTS.md references it appropriately\n- Upgrade workflow auto-updates BD_GUIDE.md\n- Git diffs clearly show bd instruction changes\n","status":"in_progress","priority":3,"issue_type":"feature","created_at":"2025-11-23T16:21:55.451925-08:00","updated_at":"2025-11-23T21:11:28.757382-08:00","source_repo":".","dependencies":[{"issue_id":"bd-woro","depends_on_id":"bd-nxgk","type":"parent-child","created_at":"2025-11-23T16:21:55.453758-08:00","created_by":"daemon"}]}
 {"id":"bd-wpkz","content_hash":"58003aaff85c85ba5c314fb5b253e0b79094484059a8fecedb9474ea4f984458","title":"Run tests to ensure refactoring didn't break anything","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-23T18:08:17.264759-08:00","updated_at":"2025-11-23T18:15:22.990153-08:00","closed_at":"2025-11-23T18:15:22.990153-08:00","source_repo":".","dependencies":[{"issue_id":"bd-wpkz","depends_on_id":"bd-9csf","type":"blocks","created_at":"2025-11-23T18:08:30.928086-08:00","created_by":"daemon"},{"issue_id":"bd-wpkz","depends_on_id":"bd-wrfz","type":"blocks","created_at":"2025-11-23T18:08:31.009873-08:00","created_by":"daemon"},{"issue_id":"bd-wpkz","depends_on_id":"bd-x2ba","type":"blocks","created_at":"2025-11-23T18:08:31.080663-08:00","created_by":"daemon"},{"issue_id":"bd-wpkz","depends_on_id":"bd-t596","type":"blocks","created_at":"2025-11-23T18:08:31.153866-08:00","created_by":"daemon"}]}
 {"id":"bd-wrfz","content_hash":"a03a18ee69cedc5e7e9c7553d27168fd1935b8d77c863b4888a2b73fec9531bf","title":"Create queries.go with core issue CRUD methods","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-23T18:08:13.46714-08:00","updated_at":"2025-11-23T18:12:55.233765-08:00","closed_at":"2025-11-23T18:12:55.233765-08:00","source_repo":"."}
 {"id":"bd-wta","content_hash":"eee40bbe4e00af632ad46e1461a25e4b0e5508bea115422aea0772381eec0d84","title":"Add performance benchmarks for multi-repo hydration","description":"The contributor-workflow-analysis.md asserts sub-second queries (line 702) and describes smart caching via file mtime tracking (Decision #4, lines 584-618), but doesn't provide concrete performance benchmarks.\n\nVC's requirement (from VC feedback section):\n- Executor polls GetReadyWork() every 5-10 seconds\n- Queries must be sub-second (ideally \u003c100ms)\n- Smart caching must avoid re-parsing JSONLs on every query\n\nSuggested performance targets to validate:\n- File stat overhead: \u003c1ms per repo\n- Hydration (when needed): \u003c500ms for typical JSONL (\u003c25k)\n- Query (from cache): \u003c10ms\n- Total GetReadyWork(): \u003c100ms (VC's requirement)\n\nAlso test at scale:\n- N=1 repo (baseline)\n- N=3 repos (typical)\n- N=10 repos (edge case)\n\nThese benchmarks are critical for library consumers like VC that run automated polling loops.","acceptance_criteria":"- Performance benchmark suite created for multi-repo hydration\n- Benchmarks cover file stat, hydration, and query times\n- Tests at N=1, N=3, N=10 repo scales\n- Results documented in contributor-workflow-analysis.md\n- Performance targets met or issues filed for optimization","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-03T20:24:39.331528-08:00","updated_at":"2025-11-05T14:17:15.079226-08:00","closed_at":"2025-11-05T14:17:15.079226-08:00","source_repo":"."}

AGENTS.md

@@ -38,12 +38,17 @@ bd info --whats-new
 # 2. Update git hooks to match new bd version
 bd hooks install
 
-# 3. Check for any outdated hooks (optional)
+# 3. Regenerate BD_GUIDE.md if it exists (optional but recommended)
+bd onboard --output .beads/BD_GUIDE.md
+
+# 4. Check for any outdated hooks (optional)
 bd info  # Shows warnings if hooks are outdated
 ```
 
 **Why update hooks?** Git hooks (pre-commit, post-merge, pre-push) are versioned with bd. Outdated hooks may miss new auto-sync features or bug fixes. Running `bd hooks install` ensures hooks match your bd version.
 
+**About BD_GUIDE.md:** This is an optional auto-generated file that separates bd-specific instructions from project-specific ones. If your project uses this file (in `.beads/BD_GUIDE.md`), regenerate it after upgrades to get the latest bd documentation. The file is version-stamped and should never be manually edited.
+
 **Related:** See GitHub Discussion #239 for background on agent upgrade workflows.
 
 ## Human Setup vs Agent Usage

cmd/bd/onboard.go

@@ -415,6 +415,66 @@ func renderOnboardInstructions(w io.Writer) error {
 	return nil
 }
 
+// bdGuideContent generates the canonical BD_GUIDE.md content
+const bdGuideHeader = `<!-- Auto-generated by bd v%s - DO NOT EDIT MANUALLY -->
+<!-- Run 'bd onboard --output .beads/BD_GUIDE.md' to regenerate -->
+
+# BD (Beads) Guide for AI Agents
+
+This file contains canonical bd (beads) workflow instructions for AI agents.
+It is auto-generated and version-stamped to track bd upgrades.
+
+> **For project-specific instructions**, see AGENTS.md in the repository root.
+> This file only covers bd tool usage, not project-specific workflows.
+
+---
+
+`
+
+// generateBDGuide creates a version-stamped BD_GUIDE.md file
+func generateBDGuide(outputPath string) error {
+	// Create output file
+	f, err := os.Create(outputPath)
+	if err != nil {
+		return fmt.Errorf("failed to create output file: %w", err)
+	}
+	defer f.Close()
+
+	// Write header with version stamp
+	if _, err := fmt.Fprintf(f, bdGuideHeader, Version); err != nil {
+		return fmt.Errorf("failed to write header: %w", err)
+	}
+
+	// Write AGENTS.md content (bd-specific instructions)
+	if _, err := f.WriteString(agentsContent); err != nil {
+		return fmt.Errorf("failed to write agents content: %w", err)
+	}
+
+	// Write separator
+	if _, err := f.WriteString("\n\n---\n\n"); err != nil {
+		return fmt.Errorf("failed to write separator: %w", err)
+	}
+
+	// Write Copilot instructions content (comprehensive technical guide)
+	if _, err := f.WriteString(copilotInstructionsContent); err != nil {
+		return fmt.Errorf("failed to write copilot content: %w", err)
+	}
+
+	// Write footer with regeneration instructions
+	footer := fmt.Sprintf("\n\n---\n\n"+
+		"**Generated by bd v%s**\n\n"+
+		"To regenerate this file after upgrading bd:\n"+
+		"```bash\n"+
+		"bd onboard --output .beads/BD_GUIDE.md\n"+
+		"```\n", Version)
+
+	if _, err := f.WriteString(footer); err != nil {
+		return fmt.Errorf("failed to write footer: %w", err)
+	}
+
+	return nil
+}
+
 var onboardCmd = &cobra.Command{
 	Use:   "onboard",
 	Short: "Display instructions for configuring AGENTS.md",
@@ -422,8 +482,29 @@ var onboardCmd = &cobra.Command{
 
 This command outputs instructions that AI agents should follow to integrate bd
 into the project's agent documentation. The agent will intelligently merge the
-content into AGENTS.md and update CLAUDE.md if present.`,
+content into AGENTS.md and update CLAUDE.md if present.
+
+Use --output to generate a canonical BD_GUIDE.md file instead:
+  bd onboard --output .beads/BD_GUIDE.md
+
+The generated BD_GUIDE.md is version-stamped and auto-generated - it should
+never be manually edited. This separates bd-specific instructions (which change
+with bd upgrades) from project-specific instructions in AGENTS.md.`,
 	Run: func(cmd *cobra.Command, args []string) {
+		outputPath, _ := cmd.Flags().GetString("output")
+
+		if outputPath != "" {
+			// Generate BD_GUIDE.md instead of onboarding instructions
+			if err := generateBDGuide(outputPath); err != nil {
+				fmt.Fprintf(cmd.ErrOrStderr(), "Error generating BD_GUIDE.md: %v\n", err)
+				os.Exit(1)
+			}
+			fmt.Printf("✓ Generated %s (bd v%s)\n", outputPath, Version)
+			fmt.Println("  This file is auto-generated - do not edit manually")
+			fmt.Println("  Update your AGENTS.md to reference this file instead of duplicating bd instructions")
+			return
+		}
+
 		if err := renderOnboardInstructions(cmd.OutOrStdout()); err != nil {
 			if _, writeErr := fmt.Fprintf(cmd.ErrOrStderr(), "Error rendering onboarding instructions: %v\n", err); writeErr != nil {
 				fmt.Fprintf(os.Stderr, "Error rendering onboarding instructions: %v (stderr write failed: %v)\n", err, writeErr)
@@ -434,5 +515,6 @@ content into AGENTS.md and update CLAUDE.md if present.`,
 }
 
 func init() {
+	onboardCmd.Flags().String("output", "", "Generate BD_GUIDE.md at the specified path (e.g., .beads/BD_GUIDE.md)")
 	rootCmd.AddCommand(onboardCmd)
 }

cmd/bd/onboard_test.go

@@ -2,6 +2,8 @@ package main
 
 import (
 	"bytes"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 )
@@ -68,3 +70,120 @@ func TestOnboardCommand(t *testing.T) {
 		}
 	})
 }
+
+func TestGenerateBDGuide(t *testing.T) {
+	t.Run("generates BD_GUIDE.md with version stamp", func(t *testing.T) {
+		// Create temp directory
+		tmpDir := t.TempDir()
+		outputPath := filepath.Join(tmpDir, "BD_GUIDE.md")
+
+		// Generate BD_GUIDE.md
+		if err := generateBDGuide(outputPath); err != nil {
+			t.Fatalf("generateBDGuide() error = %v", err)
+		}
+
+		// Read generated file
+		content, err := os.ReadFile(outputPath)
+		if err != nil {
+			t.Fatalf("Failed to read generated file: %v", err)
+		}
+
+		output := string(content)
+
+		// Verify version stamp in header
+		if !strings.Contains(output, "Auto-generated by bd v"+Version) {
+			t.Error("Generated file should contain version stamp in header")
+		}
+
+		if !strings.Contains(output, "DO NOT EDIT MANUALLY") {
+			t.Error("Generated file should contain DO NOT EDIT warning")
+		}
+
+		// Verify regeneration instructions
+		if !strings.Contains(output, "bd onboard --output") {
+			t.Error("Generated file should contain regeneration instructions")
+		}
+	})
+
+	t.Run("includes agents content", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		outputPath := filepath.Join(tmpDir, "BD_GUIDE.md")
+
+		if err := generateBDGuide(outputPath); err != nil {
+			t.Fatalf("generateBDGuide() error = %v", err)
+		}
+
+		content, err := os.ReadFile(outputPath)
+		if err != nil {
+			t.Fatalf("Failed to read generated file: %v", err)
+		}
+
+		output := string(content)
+
+		// Verify key sections from agentsContent are present
+		expectedSections := []string{
+			"Issue Tracking with bd (beads)",
+			"bd ready",
+			"bd create",
+			"MCP Server",
+		}
+
+		for _, section := range expectedSections {
+			if !strings.Contains(output, section) {
+				t.Errorf("Generated file should contain '%s'", section)
+			}
+		}
+	})
+
+	t.Run("includes copilot instructions content", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		outputPath := filepath.Join(tmpDir, "BD_GUIDE.md")
+
+		if err := generateBDGuide(outputPath); err != nil {
+			t.Fatalf("generateBDGuide() error = %v", err)
+		}
+
+		content, err := os.ReadFile(outputPath)
+		if err != nil {
+			t.Fatalf("Failed to read generated file: %v", err)
+		}
+
+		output := string(content)
+
+		// Verify key sections from copilotInstructionsContent are present
+		expectedSections := []string{
+			"GitHub Copilot Instructions",
+			"Project Structure",
+			"Tech Stack",
+			"Coding Guidelines",
+		}
+
+		for _, section := range expectedSections {
+			if !strings.Contains(output, section) {
+				t.Errorf("Generated file should contain '%s'", section)
+			}
+		}
+	})
+
+	t.Run("has proper structure with separators", func(t *testing.T) {
+		tmpDir := t.TempDir()
+		outputPath := filepath.Join(tmpDir, "BD_GUIDE.md")
+
+		if err := generateBDGuide(outputPath); err != nil {
+			t.Fatalf("generateBDGuide() error = %v", err)
+		}
+
+		content, err := os.ReadFile(outputPath)
+		if err != nil {
+			t.Fatalf("Failed to read generated file: %v", err)
+		}
+
+		output := string(content)
+
+		// Count separators (should have at least 3: after header, between sections, before footer)
+		separatorCount := strings.Count(output, "---")
+		if separatorCount < 3 {
+			t.Errorf("Expected at least 3 separators (---), got %d", separatorCount)
+		}
+	})
+}

cmd/bd/version_tracking.go

@@ -114,9 +114,67 @@ func maybeShowUpgradeNotification() {
 	// Display notification
 	fmt.Printf("🔄 bd upgraded from v%s to v%s since last use\n", previousVersion, Version)
 	fmt.Println("💡 Run 'bd upgrade review' to see what changed")
+
+	// Check if BD_GUIDE.md exists and needs updating
+	checkAndSuggestBDGuideUpdate()
+
 	fmt.Println()
 }
 
+// checkAndSuggestBDGuideUpdate checks if .beads/BD_GUIDE.md exists and suggests regeneration if outdated.
+// bd-woro: Auto-update BD_GUIDE.md on version changes
+func checkAndSuggestBDGuideUpdate() {
+	beadsDir := beads.FindBeadsDir()
+	if beadsDir == "" {
+		return
+	}
+
+	guidePath := beadsDir + "/BD_GUIDE.md"
+
+	// Check if BD_GUIDE.md exists
+	if _, err := os.Stat(guidePath); os.IsNotExist(err) {
+		// File doesn't exist - no suggestion needed
+		return
+	}
+
+	// Read first few lines to check version stamp
+	content, err := os.ReadFile(guidePath)
+	if err != nil {
+		return // Silent failure
+	}
+
+	// Look for version in the first 200 bytes (should be in the header)
+	header := string(content)
+	if len(header) > 200 {
+		header = header[:200]
+	}
+
+	// Check if the file has the old version stamp
+	oldVersionStamp := fmt.Sprintf("bd v%s", previousVersion)
+	currentVersionStamp := fmt.Sprintf("bd v%s", Version)
+
+	if containsSubstring(header, oldVersionStamp) && !containsSubstring(header, currentVersionStamp) {
+		// BD_GUIDE.md is outdated
+		fmt.Printf("📄 BD_GUIDE.md is outdated (v%s → v%s)\n", previousVersion, Version)
+		fmt.Printf("💡 Run 'bd onboard --output .beads/BD_GUIDE.md' to regenerate\n")
+	}
+}
+
+// containsSubstring checks if haystack contains needle (case-sensitive)
+func containsSubstring(haystack, needle string) bool {
+	return len(haystack) >= len(needle) && findSubstring(haystack, needle) >= 0
+}
+
+// findSubstring returns the index of needle in haystack, or -1 if not found
+func findSubstring(haystack, needle string) int {
+	for i := 0; i <= len(haystack)-len(needle); i++ {
+		if haystack[i:i+len(needle)] == needle {
+			return i
+		}
+	}
+	return -1
+}
+
 // autoMigrateOnVersionBump automatically migrates the database when CLI version changes.
 // This function is best-effort - failures are silent to avoid disrupting commands.
 // Called from PersistentPreRun after daemon check but before opening DB for main operation.