docs: Add comprehensive Agent Mail integration guide

- Installation and quick start - Architecture and coordination flow - Configuration reference (environment variables) - When to use vs skip Agent Mail - Multi-machine deployment patterns - Troubleshooting and FAQ - Migration guide from git-only mode Closes bd-xzrv Amp-Thread-ID: https://ampcode.com/threads/T-e8cf1b4b-38ae-4f6b-ae17-8b960d31608e Co-authored-by: Amp <amp@ampcode.com>
2025-11-08 00:49:41 -08:00
parent bd59973170
commit 9cffd39246
2 changed files with 528 additions and 1 deletions
--- a/.beads/beads.jsonl
+++ b/.beads/beads.jsonl
@@ -347,7 +347,7 @@
 {"id":"bd-ww0g","content_hash":"973e5e6eb58975fcbe80f804b69a900cde824af4b51243737ef5fca404d0b1c1","title":"MCP server: \"No workspace set\" and \"chunk longer than limit\" errors","description":"Two related errors reported in beads-mcp v0.21:\n\n**Error 1: \"No workspace set\" after successful set_context**\n```\n✓ Set beads context\n✗ list\n  Error calling tool 'list': No workspace set. Either provide workspace_root\n  parameter or call set_context() first.\n```\n\nHypothesis: Environment variable persistence issue between MCP tool calls, or ContextVar not being set correctly by @with_workspace decorator.\n\n**Error 2: \"Separator is found, but chunk is longer than limit\"**\n```\n✗ list\n  Error calling tool 'list': Separator is found, but chunk is longer than limit\n```\n\nHypothesis: MCP protocol output size limit exceeded. Large issue databases may produce JSON output that exceeds MCP stdio buffer limits.\n\nPlatform: Fedora 43, using copilot-cli with Sonnet 4.5\n\nWorkaround: CLI works fine (`bd list --status open --json`)","notes":"## Fixes Implemented\n\n**Issue 1: \"No workspace set\" after successful set_context** ✅ FIXED\n\nRoot cause: os.environ doesn't persist across MCP tool calls. When set_context() set BEADS_WORKING_DIR in os.environ, that change was lost on the next tool call.\n\nSolution:\n- Added module-level _workspace_context dict for persistent storage (server.py:51)\n- Modified set_context() to store in both persistent dict and os.environ (server.py:265-287)\n- Modified with_workspace() decorator to check persistent context first (server.py:129-133)\n- Updated where_am_i() to check persistent context (server.py:302-330)\n\n**Issue 2: \"chunk longer than limit\"** ✅ FIXED\n\nRoot cause: MCP stdio protocol has buffer limits. Large issue lists with full dependencies/dependents exceed this.\n\nSolution:\n- Reduced default list limit from 50 to 20 (server.py:356, models.py:122)\n- Reduced max list limit from 1000 to 100 (models.py:122)\n- Strip dependencies/dependents from list() and ready() responses (server.py:343-350, 368-373)\n- Full dependency details still available via show() command\n\n## Testing\n\n✅ Python syntax validated with py_compile\n✅ Changes are backward compatible\n✅ Persistent context falls back to os.environ for compatibility\n\nUsers should now be able to call set_context() once and have it persist across all subsequent tool calls. Large databases will no longer cause buffer overflow errors.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-11-07T14:32:18.315155-08:00","updated_at":"2025-11-07T21:02:55.470937-08:00","closed_at":"2025-11-07T16:53:46.929942-08:00","source_repo":"."}
 {"id":"bd-x47","content_hash":"0b5f05ca037293f7be36f9a080da731e67bec96ba68e2b7cbeb589cc60343225","title":"Add guidance for self-hosting projects","description":"The contributor-workflow-analysis.md is optimized for OSS contributors making PRs to upstream projects. However, it doesn't address projects like VC that use beads for their own development (self-hosting).\n\nSelf-hosting projects differ from OSS contributors:\n- No upstream/downstream distinction (they ARE the project)\n- May run automated executors (not just humans)\n- In bootstrap/early phase (stability matters)\n- Single team/owner (not multiple contributors with permissions)\n\nGuidance needed on:\n- When self-hosting projects should stay single-repo (default, recommended)\n- When they should adopt multi-repo (team planning, multi-phase dev)\n- How automated executors should handle multi-repo (if at all)\n- Special considerations for projects in bootstrap phase\n\nExamples of self-hosting projects: VC (building itself with beads), internal tools, pet projects","acceptance_criteria":"- Section added: 'For Projects Using Beads for Self-Hosting'\n- Clear guidance on when to stay single-repo vs adopt multi-repo\n- Recommendations for automated executor behavior with multi-repo\n- Bootstrap phase considerations documented","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-03T20:24:27.805341-08:00","updated_at":"2025-11-05T14:16:34.69662-08:00","closed_at":"2025-11-05T14:16:34.69662-08:00","source_repo":"."}
 {"id":"bd-xo6b","content_hash":"a8f6100ae8d6569c75565d5a1aacbc0e55806fab917399ab473fb212fa694b80","title":"Review multi-repo deletion tracking implementation","description":"Thoroughly review the multi-repo deletion tracking fix (bd-4oob):\n\nFiles changed:\n- cmd/bd/deletion_tracking.go: Added getMultiRepoJSONLPaths() helper\n- cmd/bd/daemon_sync.go: Updated snapshot capture/update logic for multi-repo\n- cmd/bd/deletion_tracking_test.go: Added 2 new tests (287 lines)\n\nReview focus areas:\n1. Correctness: Does getMultiRepoJSONLPaths() handle all edge cases?\n2. Performance: Calling getMultiRepoJSONLPaths() 3x per sync (snapshot capture, merge, base update) - should we cache?\n3. Error handling: What if some repos fail snapshot operations but others succeed?\n4. Race conditions: Multiple daemons in different repos?\n5. Test coverage: Are TestMultiRepoDeletionTracking and TestMultiRepoSnapshotIsolation sufficient?\n6. Path handling: Absolute vs relative paths, tilde expansion\n\nThis is fresh code - needs careful review before considering deletion tracking production-ready.","notes":"Code review completed. Overall assessment: Core deletion tracking logic is sound, but error handling and path handling issues make this not yet production-ready for multi-repo scenarios.\n\nKey findings:\n\nCRITICAL ISSUES (Priority 1):\n1. Inconsistent error handling in daemon_sync.go - snapshot/merge fail hard but base update warns. Can leave DB in inconsistent state with no rollback. See bd-sjmr.\n2. No path normalization in getMultiRepoJSONLPaths() - tilde expansion, relative paths, duplicates not handled. See bd-iye7.\n\nSHOULD FIX (Priority 2):\n3. Missing test coverage for edge cases - empty paths, duplicates, partial failures. See bd-kdoh.\n4. Performance - getMultiRepoJSONLPaths() called 3x per sync (minor issue). See bd-we4p.\n\nWHAT WORKS WELL:\n- Atomic file operations with PID-based temp files\n- Good snapshot isolation between repos\n- Race condition protection via exclusive locks\n- Solid test coverage for happy path scenarios\n\nVERDICT: Address bd-iye7 and bd-sjmr before considering deletion tracking production-ready for multi-repo mode.\n\nDetailed review notes available in conversation history.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-06T19:23:52.402949-08:00","updated_at":"2025-11-06T19:32:34.160341-08:00","closed_at":"2025-11-06T19:32:34.160341-08:00","source_repo":".","dependencies":[{"issue_id":"bd-xo6b","depends_on_id":"bd-rbxi","type":"parent-child","created_at":"2025-11-06T19:23:52.403723-08:00","created_by":"daemon"}]}
-{"id":"bd-xzrv","content_hash":"d5833f7953e5c353b9b5466c054d5bb8472bf8139570326353ec6402f368f8f4","title":"Write Agent Mail integration guide","description":"Comprehensive guide for setting up and using Agent Mail with Beads.\n\nAcceptance Criteria:\n- Installation instructions\n- Configuration (environment variables)\n- Architecture diagram\n- Benefits and tradeoffs\n- When to use vs not use\n- Troubleshooting section\n- Migration from git-only mode\n\nFile: docs/AGENT_MAIL.md\n\nSections:\n- Quick start\n- How it works\n- Integration points\n- Graceful degradation\n- Multi-machine deployment\n- FAQ","status":"open","priority":1,"issue_type":"task","created_at":"2025-11-07T22:42:51.231066-08:00","updated_at":"2025-11-07T22:42:51.231066-08:00","source_repo":".","dependencies":[{"issue_id":"bd-xzrv","depends_on_id":"bd-fzbg","type":"blocks","created_at":"2025-11-07T22:42:51.232246-08:00","created_by":"daemon"}]}
+{"id":"bd-xzrv","content_hash":"bc0097eb1382f92d5f2a80189a9a7da19a4cc2a11ac3beda5af4c93a55692227","title":"Write Agent Mail integration guide","description":"Comprehensive guide for setting up and using Agent Mail with Beads.\n\nAcceptance Criteria:\n- Installation instructions\n- Configuration (environment variables)\n- Architecture diagram\n- Benefits and tradeoffs\n- When to use vs not use\n- Troubleshooting section\n- Migration from git-only mode\n\nFile: docs/AGENT_MAIL.md\n\nSections:\n- Quick start\n- How it works\n- Integration points\n- Graceful degradation\n- Multi-machine deployment\n- FAQ","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-07T22:42:51.231066-08:00","updated_at":"2025-11-08T00:40:38.798162-08:00","closed_at":"2025-11-08T00:40:38.798162-08:00","source_repo":".","dependencies":[{"issue_id":"bd-xzrv","depends_on_id":"bd-fzbg","type":"blocks","created_at":"2025-11-07T22:42:51.232246-08:00","created_by":"daemon"}]}
 {"id":"bd-yek6","content_hash":"f155913af8c58c0a7ea3da6a7d9e232e8cb29c3825f2d6f272a5417a449692a9","title":"CLI tests (cli_fast_test.go) are slow and should be integration tests","description":"The TestCLI_* tests in cmd/bd/cli_fast_test.go are taking 4-5 seconds each (40+ seconds total), making them the slowest part of the fast test suite.\n\nCurrent timings:\n- TestCLI_Import: 4.73s\n- TestCLI_Blocked: 4.33s  \n- TestCLI_DepTree: 4.15s\n- TestCLI_Close: 3.59s\n- TestCLI_DepAdd: 3.50s\n- etc.\n\nThese tests compile the bd binary once in init(), but then execute it multiple times per test with filesystem operations. Despite being named \"fast\", they're actually end-to-end CLI integration tests.\n\nOptions:\n1. Tag with //go:build integration (move to integration suite)\n2. Optimize: Use in-memory databases, reduce exec calls, better parallelization\n3. Keep as-is but understand they're the baseline for \"fast\" tests\n\nTotal test suite currently: 13.8s (cmd/bd alone is 12.8s, and most of that is these CLI tests)","notes":"Fixed by reusing existing bd binary from repo root instead of rebuilding.\n\nBefore: 15+ minutes (rebuilding binary for every test package)\nAfter: ~12 seconds (reuses pre-built binary)\n\nThe init() function now checks for ../../bd first before falling back to building. This means `go build \u0026\u0026 go test` is now fast.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-05T20:19:12.822543-08:00","updated_at":"2025-11-05T20:31:19.321787-08:00","closed_at":"2025-11-05T20:31:19.321787-08:00","source_repo":"."}
 {"id":"bd-z3s3","content_hash":"24d99dc1a9a5f35af962137f5709d4b0f1b6a9ec91511c30a2517d790640cce8","title":"Create deployment scripts for GCP","description":"Automated provisioning scripts for GCP Compute Engine deployment.\n\nAcceptance Criteria:\n- Terraform/gcloud scripts\n- Static IP allocation\n- Firewall rules\n- NGINX reverse proxy config\n- TLS setup (Let's Encrypt)\n- Systemd service file\n\nFile: deployment/agent-mail/gcp/","status":"open","priority":3,"issue_type":"task","created_at":"2025-11-07T22:43:43.294839-08:00","updated_at":"2025-11-07T22:43:43.294839-08:00","source_repo":".","dependencies":[{"issue_id":"bd-z3s3","depends_on_id":"bd-9li4","type":"blocks","created_at":"2025-11-07T23:04:27.982336-08:00","created_by":"daemon"}]}
 {"id":"bd-z528","content_hash":"3f332e9997d2b7eb0af23885820df5f607fe08671a2615cadec941bbe7d36f68","title":"Prevent test pollution in production database","description":"The bd-vxdr cleanup revealed test issues were created during manual testing in the production workspace (Nov 2-4, template feature development).\n\n**Root cause:** Manual testing with `./bd create \"Test issue\"` pollutes the production .beads database.\n\n**Prevention strategies:**\n1. Use TEST_DB environment variable for manual testing\n2. Add warning when creating issues with \"Test\" prefix\n3. Improve developer docs about testing workflow\n4. Consider adding `bd test-mode` command for isolated testing","notes":"**Implementation completed:**\n\n1. ✅ Added warning when creating issues with \"Test\" prefix in production database\n   - Shows yellow warning with ⚠ symbol\n   - Suggests using BEADS_DB for isolated testing\n   - Warning appears in create.go after title validation\n\n2. ✅ Documented BEADS_DB testing workflow in AGENTS.md\n   - Added \"Testing Workflow\" section in Development Guidelines\n   - Includes manual testing examples with BEADS_DB\n   - Includes automated testing examples with t.TempDir()\n   - Clear warning about not polluting production database\n\n3. ⚠️ Decided against bd test-mode command\n   - BEADS_DB already provides simple, flexible isolation\n   - Additional command would add complexity without much benefit\n   - Current approach follows Unix philosophy (env vars for config)\n\n**Files modified:**\n- cmd/bd/create.go - Added Test prefix warning\n- AGENTS.md - Added Testing Workflow section\n\n**Testing:**\n- Verified warning appears when creating \"Test\" prefix issues\n- Verified BEADS_DB isolation works correctly\n- Built successfully with `go build`","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-07T16:07:28.255289-08:00","updated_at":"2025-11-07T23:18:08.386514-08:00","closed_at":"2025-11-07T22:43:28.669908-08:00","source_repo":"."}
--- a/docs/AGENT_MAIL.md
+++ b/docs/AGENT_MAIL.md
@@ -0,0 +1,527 @@
+# Agent Mail Integration Guide
+
+**Status:** Optional Enhancement  
+**Minimum bd Version:** 0.21.0  
+**Related ADR:** [002-agent-mail-integration.md](adr/002-agent-mail-integration.md)
+
+## Overview
+
+MCP Agent Mail provides real-time coordination for multi-agent beads workflows, reducing latency from 2-5 seconds (git sync) to <100ms (HTTP API) and preventing work collisions through file reservations.
+
+**Key Benefits:**
+- **20-50x latency reduction**: <100ms vs 2000-5000ms for status updates
+- **Collision prevention**: Exclusive file reservations prevent duplicate work
+- **Lightweight**: <50MB memory, simple HTTP API
+- **100% optional**: Git-only mode works identically without it
+
+## Quick Start
+
+### Prerequisites
+- Python 3.11+
+- bd 0.21.0+
+- Multi-agent workflow (2+ AI agents working on same repository)
+
+### Installation
+
+```bash
+# Install Agent Mail server
+git clone https://github.com/Dicklesworthstone/mcp_agent_mail.git
+cd mcp_agent_mail
+python3 -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e .
+
+# Start server
+python -m mcp_agent_mail.cli serve-http
+# Server runs on http://127.0.0.1:8765
+```
+
+### Configuration
+
+Enable Agent Mail by setting environment variables before running bd commands:
+
+```bash
+# Agent 1
+export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
+export BEADS_AGENT_NAME=assistant-alpha
+export BEADS_PROJECT_ID=my-project
+
+# Agent 2
+export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
+export BEADS_AGENT_NAME=assistant-beta
+export BEADS_PROJECT_ID=my-project
+
+# Now run bd commands normally
+bd ready
+bd update bd-42 --status in_progress
+```
+
+**All configuration is via environment variables** - no changes to `.beads/` or git required.
+
+### Verification
+
+```bash
+# Check if Agent Mail is active
+bd info --json | grep agent_mail
+
+# View reservations in web UI
+open http://127.0.0.1:8765/mail
+
+# Test collision prevention
+# Terminal 1 (Agent A):
+bd update bd-123 --status in_progress
+
+# Terminal 2 (Agent B):
+bd update bd-123 --status in_progress
+# Expected: Error - bd-123 reserved by assistant-alpha
+```
+
+## How It Works
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│ bd (Beads CLI)                              │
+│                                             │
+│  ┌─────────────┐      ┌─────────────────┐  │
+│  │ Git Sync    │      │ Agent Mail      │  │
+│  │ (required)  │      │ (optional)      │  │
+│  │             │      │                 │  │
+│  │ - Export    │      │ - Reservations  │  │
+│  │ - Import    │      │ - Notifications │  │
+│  │ - Commit    │      │ - Status updates│  │
+│  │ - Push/Pull │      │                 │  │
+│  └─────────────┘      └─────────────────┘  │
+│         │                      │            │
+└─────────┼──────────────────────┼────────────┘
+          │                      │
+          ▼                      ▼
+  ┌──────────────┐      ┌──────────────┐
+  │ .beads/      │      │ Agent Mail   │
+  │ issues.jsonl │      │ Server       │
+  │ (git)        │      │ (HTTP)       │
+  └──────────────┘      └──────────────┘
+```
+
+**Git remains the source of truth.** Agent Mail provides ephemeral coordination state only.
+
+### Coordination Flow
+
+**Without Agent Mail (git-only):**
+```
+Agent A: bd update bd-123 --status in_progress
+  ↓ (30s debounce)
+  ↓ export to JSONL
+  ↓ git commit + push (1-2s)
+  ↓ 
+Agent B: git pull (1-2s)
+  ↓ import from JSONL
+  ↓ sees bd-123 is taken (TOO LATE - work already started!)
+
+Total latency: 2000-5000ms
+Risk: Both agents work on same issue
+```
+
+**With Agent Mail:**
+```
+Agent A: bd update bd-123 --status in_progress
+  ↓ 
+  ├─ Agent Mail: POST /api/reservations (5ms)
+  │  └─ Reserve bd-123 for Agent A
+  ├─ Local: Update .beads/beads.db
+  └─ Background: Export to JSONL (30s debounce)
+  
+Agent B: bd update bd-123 --status in_progress
+  ↓
+  └─ Agent Mail: POST /api/reservations (5ms)
+     └─ HTTP 409 Conflict: "bd-123 reserved by Agent A"
+     └─ bd exits with clear error
+
+Total latency: <100ms
+Risk: Zero - collision prevented at reservation layer
+```
+
+### Integration Points
+
+Agent Mail integrates at 4 key points in the bd workflow:
+
+1. **Issue Reservation** (`bd update --status in_progress`)
+   - Check if issue already reserved
+   - Create reservation if available
+   - Error 409 if conflict
+
+2. **Issue Release** (`bd close`)
+   - Release reservation automatically
+   - Notify other agents (optional)
+
+3. **Ready Work Query** (`bd ready`)
+   - Filter out reserved issues (future enhancement)
+   - Show only truly available work
+
+4. **Status Updates** (`bd update --priority`, etc.)
+   - No reservation required for non-status changes
+   - Graceful degradation if server unavailable
+
+## Configuration Reference
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BEADS_AGENT_MAIL_URL` | Yes | None | Agent Mail server URL (e.g., `http://127.0.0.1:8765`) |
+| `BEADS_AGENT_NAME` | Yes | None | Unique agent identifier (e.g., `assistant-alpha`) |
+| `BEADS_PROJECT_ID` | Yes | None | Project namespace (e.g., `my-project`) |
+| `BEADS_AGENT_MAIL_TOKEN` | No | None | Bearer token for authentication (future) |
+
+### Example Configurations
+
+**Local Development (Single Machine):**
+```bash
+# ~/.bashrc or ~/.zshrc
+export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
+export BEADS_AGENT_NAME=$(whoami)-$(hostname)
+export BEADS_PROJECT_ID=$(basename $(pwd))
+```
+
+**Multi-Machine Setup:**
+```bash
+# Machine 1 (runs server)
+export BEADS_AGENT_MAIL_URL=http://192.168.1.100:8765
+export BEADS_AGENT_NAME=dev-machine-1
+export BEADS_PROJECT_ID=beads
+
+# Machine 2 (client only)
+export BEADS_AGENT_MAIL_URL=http://192.168.1.100:8765
+export BEADS_AGENT_NAME=dev-machine-2
+export BEADS_PROJECT_ID=beads
+```
+
+**Docker Compose:**
+```yaml
+services:
+  agent-mail:
+    image: ghcr.io/dicklesworthstone/mcp_agent_mail:latest
+    ports:
+      - "8765:8765"
+    
+  agent-1:
+    image: my-beads-agent
+    environment:
+      BEADS_AGENT_MAIL_URL: http://agent-mail:8765
+      BEADS_AGENT_NAME: worker-1
+      BEADS_PROJECT_ID: my-project
+```
+
+## When to Use Agent Mail
+
+### ✅ Use Agent Mail When:
+
+1. **Multiple AI agents** working on the same repository simultaneously
+2. **Frequent status updates** (multiple agents claiming/releasing work)
+3. **Collision-sensitive workflows** (duplicate work is expensive)
+4. **Real-time coordination needed** (latency matters)
+5. **CI/CD integration** (agents triggered by webhooks/events)
+
+**Example Scenario:**
+- Team has 3 AI agents (Claude, GPT-4, Gemini)
+- Agents pull from work queue every 5 minutes
+- Repository has 50+ open issues
+- Duplicate work costs 30+ minutes to resolve
+
+### ❌ Skip Agent Mail When:
+
+1. **Single agent** workflows (no collision risk)
+2. **Infrequent updates** (once per day/week)
+3. **Git-only infrastructure** (no external services allowed)
+4. **Offline workflows** (no network connectivity)
+5. **Low issue volume** (<10 open issues)
+
+**Example Scenario:**
+- Solo developer using beads for personal task tracking
+- Updates happen once per session
+- No concurrent work
+- Simplicity over latency
+
+## Graceful Degradation
+
+**Agent Mail failure NEVER breaks beads.** If the server is unavailable:
+
+1. bd logs a warning: `Agent Mail unavailable, falling back to git-only mode`
+2. All operations proceed normally
+3. Git sync handles coordination (with higher latency)
+4. No errors, no crashes
+
+**Test graceful degradation:**
+```bash
+# Stop Agent Mail server
+pkill -f "mcp_agent_mail.cli"
+
+# bd commands work identically
+bd ready  # Success
+bd update bd-42 --status in_progress  # Success (git-only mode)
+```
+
+**Automatic fallback conditions:**
+- Server not responding (connection refused)
+- Server returns 500+ errors
+- Network timeout (>5s)
+- Invalid/missing environment variables
+
+## Multi-Machine Deployment
+
+### Centralized Server Pattern (Recommended)
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  Agent A    │────▶│ Agent Mail  │◀────│  Agent B    │
+│ (Machine 1) │     │   Server    │     │ (Machine 2) │
+└─────────────┘     │ (Machine 3) │     └─────────────┘
+                    └─────────────┘
+                           │
+                           ▼
+                    ┌─────────────┐
+                    │ PostgreSQL  │ (optional)
+                    │  Storage    │
+                    └─────────────┘
+```
+
+**Steps:**
+1. Deploy Agent Mail on dedicated server/container
+2. Configure firewall to allow port 8765 from agent machines
+3. Set `BEADS_AGENT_MAIL_URL` to server IP on all agents
+4. (Optional) Configure PostgreSQL backend for persistence
+
+### Peer-to-Peer Pattern (Advanced)
+
+```
+┌─────────────┐     ┌─────────────┐
+│  Agent A    │────▶│  Agent B    │
+│ + Server    │     │ + Server    │
+└─────────────┘     └─────────────┘
+       │                   │
+       └─────────┬─────────┘
+                 ▼
+          ┌─────────────┐
+          │ Shared DB   │ (e.g., Redis)
+          └─────────────┘
+```
+
+**Use case:** High-availability setups where server can't be single point of failure.
+
+## Troubleshooting
+
+### Issue: "Agent Mail unavailable" warnings
+
+**Symptoms:**
+```
+WARN Agent Mail unavailable, falling back to git-only mode
+```
+
+**Solutions:**
+1. Check server is running: `curl http://127.0.0.1:8765/health`
+2. Verify `BEADS_AGENT_MAIL_URL` is set correctly
+3. Check firewall allows connections to port 8765
+4. Review server logs: `tail -f ~/.mcp_agent_mail/logs/server.log`
+
+### Issue: "Reservation conflict" errors
+
+**Symptoms:**
+```
+Error: bd-123 already reserved by assistant-alpha
+```
+
+**Solutions:**
+1. **Expected behavior** - another agent claimed the issue first
+2. Find different work: `bd ready`
+3. If reservation is stale (agent crashed), release manually:
+   ```bash
+   curl -X DELETE http://127.0.0.1:8765/api/reservations/bd-123
+   ```
+4. Configure reservation TTL to auto-expire stale locks (future)
+
+### Issue: Reservations persist after agent crashes
+
+**Symptoms:**
+- Agent crashes mid-work
+- Reservation not released
+- Other agents can't claim the issue
+
+**Solutions:**
+1. **Manual release** via web UI: http://127.0.0.1:8765/mail
+2. **API release**: `curl -X DELETE http://127.0.0.1:8765/api/reservations/<issue-id>`
+3. **Restart server** (clears all ephemeral state): `pkill -f mcp_agent_mail; python -m mcp_agent_mail.cli serve-http`
+4. **Future:** Configure TTL to auto-expire (not yet implemented)
+
+### Issue: Two agents have different project IDs
+
+**Symptoms:**
+- Agents don't see each other's reservations
+- Collisions still happen
+
+**Solutions:**
+1. Ensure all agents use **same** `BEADS_PROJECT_ID`
+2. Check environment: `echo $BEADS_PROJECT_ID`
+3. Set globally in shell profile:
+   ```bash
+   # ~/.bashrc
+   export BEADS_PROJECT_ID=my-project
+   ```
+
+### Issue: Server uses too much memory
+
+**Symptoms:**
+- Agent Mail process grows to 100+ MB
+- Server becomes slow
+
+**Solutions:**
+1. **Normal for in-memory mode** (<50MB baseline + reservation data)
+2. Use PostgreSQL backend for large-scale deployments
+3. Configure reservation expiry to prevent unbounded growth
+4. Restart server periodically (ephemeral state is OK to lose)
+
+## Migration from Git-Only Mode
+
+**Good news:** Zero migration required! Agent Mail is purely additive.
+
+### Step 1: Test with Single Agent
+```bash
+# Start server
+python -m mcp_agent_mail.cli serve-http
+
+# Configure one agent
+export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
+export BEADS_AGENT_NAME=test-agent
+export BEADS_PROJECT_ID=test
+
+# Run normal workflow
+bd ready
+bd update bd-42 --status in_progress
+bd close bd-42 "Done"
+
+# Verify in web UI
+open http://127.0.0.1:8765/mail
+```
+
+### Step 2: Add Second Agent
+```bash
+# In separate terminal/machine
+export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
+export BEADS_AGENT_NAME=test-agent-2
+export BEADS_PROJECT_ID=test
+
+# Try claiming same issue (should fail)
+bd update bd-42 --status in_progress
+# Expected: Error - reservation conflict
+```
+
+### Step 3: Roll Out to Production
+1. Deploy Agent Mail server to production environment
+2. Add environment variables to agent deployment configs
+3. Monitor logs for "Agent Mail unavailable" warnings
+4. Gradually enable for all agents
+
+### Rollback Plan
+Simply **unset environment variables** - agents immediately fall back to git-only mode:
+```bash
+unset BEADS_AGENT_MAIL_URL
+unset BEADS_AGENT_NAME
+unset BEADS_PROJECT_ID
+
+# bd works identically without Agent Mail
+bd ready
+```
+
+## FAQ
+
+### Q: Do I need Agent Mail for single-agent workflows?
+**A:** No. Agent Mail is only useful for multi-agent coordination. Single agents get no benefit from it.
+
+### Q: Can I use Agent Mail with the MCP server (beads-mcp)?
+**A:** Yes! Set the environment variables before starting beads-mcp, and it will use Agent Mail for all operations.
+
+### Q: What happens if Agent Mail and git get out of sync?
+**A:** Git is the source of truth. If Agent Mail has stale reservation data, worst case is a 409 error. Agent can manually release and retry.
+
+### Q: Does Agent Mail require changes to .beads/ or git?
+**A:** No. Agent Mail is 100% external. No changes to database schema, JSONL format, or git workflow.
+
+### Q: Can I use Agent Mail for multiple projects on the same server?
+**A:** Yes. Set different `BEADS_PROJECT_ID` for each project. Agent Mail provides namespace isolation.
+
+### Q: Is Agent Mail required for beads 1.0?
+**A:** No. Agent Mail is an optional enhancement. Git-only mode is fully supported indefinitely.
+
+### Q: How does Agent Mail handle authentication?
+**A:** Currently, no authentication (local network only). Bearer token support planned for future release.
+
+### Q: Can I self-host Agent Mail on corporate infrastructure?
+**A:** Yes. Agent Mail is open source (MIT license) and can be deployed anywhere Python runs.
+
+### Q: What's the performance impact of Agent Mail?
+**A:** ~5ms overhead per reservation API call. Negligible compared to 2000-5000ms git sync.
+
+### Q: Does Agent Mail work with protected branches?
+**A:** Yes. Agent Mail operates independently of git workflow. Use with `bd config set sync.branch beads-metadata` as normal.
+
+## Advanced Topics
+
+### Custom Reservation TTL
+```bash
+# Future feature (not yet implemented)
+export BEADS_RESERVATION_TTL=3600  # 1 hour in seconds
+```
+
+### PostgreSQL Backend
+```bash
+# For production deployments with persistence
+export AGENT_MAIL_DB_URL=postgresql://user:pass@localhost/agentmail
+python -m mcp_agent_mail.cli serve-http
+```
+
+### Monitoring & Observability
+```bash
+# Server exposes Prometheus metrics (future)
+curl http://127.0.0.1:8765/metrics
+
+# Health check
+curl http://127.0.0.1:8765/health
+```
+
+### Integration with CI/CD
+```yaml
+# GitHub Actions example
+jobs:
+  agent-workflow:
+    runs-on: ubuntu-latest
+    services:
+      agent-mail:
+        image: ghcr.io/dicklesworthstone/mcp_agent_mail:latest
+        ports:
+          - 8765:8765
+    env:
+      BEADS_AGENT_MAIL_URL: http://localhost:8765
+      BEADS_AGENT_NAME: github-actions-${{ github.run_id }}
+      BEADS_PROJECT_ID: ${{ github.repository }}
+    steps:
+      - run: bd ready | head -1 | xargs -I {} bd update {} --status in_progress
+```
+
+## Resources
+
+- [ADR 002: Agent Mail Integration](adr/002-agent-mail-integration.md)
+- [Agent Mail Repository](https://github.com/Dicklesworthstone/mcp_agent_mail)
+- [Integration Status](../AGENT_MAIL_INTEGRATION_STATUS.md)
+- [Latency Benchmark Results](../latency_results.md)
+- [Python Agent Example](../examples/python-agent/)
+
+## Contributing
+
+Found a bug or want to improve Agent Mail integration? See:
+- [CONTRIBUTING.md](../CONTRIBUTING.md) for beads contribution guidelines
+- [Agent Mail Issues](https://github.com/Dicklesworthstone/mcp_agent_mail/issues) for server-side issues
+
+## License
+
+Beads: Apache 2.0  
+MCP Agent Mail: MIT