docs: document Dolt backend, WSL2 mixed-env workaround, issues.jsonl sync

- AGENTS.md: add Data Backend & Platform Notes section explaining
  single-platform vs mixed WSL2+Windows setup, mirrored networking
  workaround, and manual issues.jsonl re-export step
- Creates beadboard-550 (Dolt mysql2 epic) to track long-term fix
- Note: mirrored networking is explicitly scoped as a mixed-env
  workaround, not a requirement for single-platform contributors

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

AGENTS.md

@@ -10,6 +10,8 @@ This repo is execution-first, evidence-first, and beads-driven.
 4. Evidence before assertions: do not claim fixed/passing/done without fresh command output.
 5. Keep language simple in user-facing labels and UI copy.
 6. Reuse shared code paths/components; avoid one-off logic drift across pages.
+7. Treat BeadBoard as a multi-agent coordination + communication system first; optimize feature decisions for swarm execution clarity before cosmetic/layout preferences.
+8. Runtime UI route surface is query-driven from `/` (`view=social|graph|activity`); do not reintroduce direct App Router page sprawl without explicit approval.
 
 ## Quick Beads Workflow
 
@@ -63,15 +65,21 @@ npm run test
 
 If UI changed, refresh screenshots and record artifact paths.
 
+## Runtime Surface Guardrails
+
+1. Keep the active runtime page surface minimal under `src/app`.
+2. Preserve deprecated/legacy page implementations in `reference/routes/**` when useful for reuse.
+3. Maintain backward-compatible redirects in `next.config.ts` when route contracts change.
+
 ## Realtime / Refresh Bug Triage Pattern
 
 When status updates are stale or require refresh:
 
 1. Verify source-of-truth parity (`bd show` vs app output).
 2. Confirm read path prefers live BD data when needed.
-3. Confirm watcher inputs include DB + WAL + touch markers.
-4. Confirm SSE fallback compares mtime/timestamps, not only static file content.
-5. Add regression tests for watcher/events behavior.
+3. Confirm watcher coverage for active project scope roots and relevant agent/message files.
+4. Confirm SSE event flow and client subscription behavior across all active views.
+5. Add regression tests for watcher/events behavior and scope switching.
 
 ## Parallel Agent Pattern
 
@@ -106,6 +114,8 @@ Use parallel agents for independent beads.
    - Confirm DB + WAL + touch markers are watched and SSE fallback uses mtime/timestamps.
 7. Missing test registration:
    - New test files must be included in `npm run test` script if the suite is explicitly enumerated.
+8. Documentation drift:
+   - Do not claim features in `README.md` that are not currently shipped, unless clearly labeled as roadmap.
 
 ## Session Completion (Landing the Plane)
 
@@ -136,3 +146,136 @@ Never claim:
 - "closed"
 
 unless you have run the proving command(s) in the current session and can cite results.
+
+<!-- BEGIN BEADS INTEGRATION -->
+## 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" --description="Detailed context" -t bug|feature|task -p 0-4 --json
+bd create "Issue title" --description="What this issue is about" -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" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
+5. **Complete**: `bd close <id> --reason "Done"`
+
+### 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!
+
+### 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?"
+- ❌ Do NOT create markdown TODO lists
+- ❌ Do NOT use external issue trackers
+- ❌ Do NOT duplicate tracking systems
+
+For more details, see README.md and docs/QUICKSTART.md.
+
+## Data Backend & Platform Notes
+
+BeadBoard reads issues from the Dolt SQL server (`bd`'s native backend since bd 0.56+). The Dolt server runs locally at `127.0.0.1:3307` and is started automatically by the `bd` daemon.
+
+### Single-platform setups (most users)
+
+- **WSL2 only**: frontend + `bd` + Dolt all in WSL2 → just works.
+- **Windows only**: frontend + `bd` + Dolt all in Windows → just works.
+
+### Mixed WSL2 + Windows (workaround required)
+
+If you run the Next.js frontend in Windows PowerShell but `bd` / Dolt in WSL2 (or vice versa), `127.0.0.1` refers to different loopbacks and the frontend can't reach the Dolt server.
+
+**Workaround**: enable WSL2 mirrored networking so `localhost` is shared between Windows and WSL2.
+
+Create `C:\Users\<you>\.wslconfig`:
+```ini
+[wsl2]
+networkingMode=mirrored
+```
+
+Then restart WSL2:
+```powershell
+wsl --shutdown
+```
+
+This is a one-time setup for mixed environments only. It is **not required** for single-platform contributors.
+
+### Keeping issues.jsonl in sync (temporary)
+
+Until `beadboard-550` (direct mysql2 connection) is implemented, `issues.jsonl` must be exported manually after `bd` writes in mixed environments:
+
+```bash
+# In WSL2 — re-export Dolt state to issues.jsonl so Windows frontend sees it
+bd list --all --limit 0 --json | python3 -c "
+import sys, json
+issues = json.load(sys.stdin)
+with open('.beads/issues.jsonl', 'w') as f:
+    for issue in issues:
+        f.write(json.dumps(issue) + '\n')
+print(f'Exported {len(issues)} issues to issues.jsonl')
+"
+```
+
+Once `beadboard-550` ships, `issues.jsonl` becomes a deprecated fallback and this step is no longer needed.
+
+<!-- END BEADS INTEGRATION -->