docs(skill): add coordination system reference

skills/beadboard-driver/references/coordination-system.md

@@ -0,0 +1,206 @@
+# Coordination System Reference
+
+This document is the canonical reference for BeadBoard agent coordination via `bb agent` and `bd mail` delegation.
+
+## Command Surface
+
+All commands are available through the global CLI:
+
+```bash
+bb agent <command> [flags]
+```
+
+### Identity Commands
+
+Register/update an agent:
+
+```bash
+bb agent register --name silver-scribe --role ui [--display "Silver Scribe"] [--force-update]
+```
+
+List agents (optional filters):
+
+```bash
+bb agent list [--role ui] [--status working]
+```
+
+Show one agent:
+
+```bash
+bb agent show --agent silver-scribe
+```
+
+Refresh liveness lease:
+
+```bash
+bb agent activity-lease --agent silver-scribe
+```
+
+### Mail Commands
+
+Send message:
+
+```bash
+bb agent send \
+  --from silver-scribe \
+  --to graph-scout \
+  --bead beadboard-izs.4 \
+  --category HANDOFF \
+  --subject "UI wiring complete" \
+  --body "Please verify graph parity" \
+  [--thread bead:beadboard-izs.4]
+```
+
+List inbox:
+
+```bash
+bb agent inbox --agent graph-scout [--state unread|read|acked] [--bead beadboard-izs.4] [--limit 25]
+```
+
+Mark as read:
+
+```bash
+bb agent read --agent graph-scout --message msg_20260304_001122_abcd
+```
+
+Acknowledge:
+
+```bash
+bb agent ack --agent graph-scout --message msg_20260304_001122_abcd
+```
+
+### Reservation Commands
+
+Reserve scope:
+
+```bash
+bb agent reserve --agent silver-scribe --scope src/components/social --bead beadboard-izs.4 [--ttl 120] [--takeover-stale]
+```
+
+Release scope:
+
+```bash
+bb agent release --agent silver-scribe --scope src/components/social
+```
+
+Show reservation/message status:
+
+```bash
+bb agent status [--agent silver-scribe] [--bead beadboard-izs.4]
+```
+
+## Message Model
+
+Categories:
+- `HANDOFF`
+- `BLOCKED`
+- `DECISION`
+- `INFO`
+
+States:
+- `unread`
+- `read`
+- `acked`
+
+State machine:
+- `unread -> read -> acked`
+- `ack` on unread implicitly sets `read_at` and `acked_at`
+
+Required acknowledgment:
+- `requires_ack=true` for `HANDOFF` and `BLOCKED`
+- `requires_ack=false` for `DECISION` and `INFO`
+
+## WHEN-to-Use Trigger Map
+
+1. Task completed and ownership moves to another agent: send `HANDOFF`.
+2. Work blocked by dependency, missing input, or failing environment: send `BLOCKED`.
+3. Input needed but not a hard blocker: send `DECISION`.
+4. FYI telemetry or non-blocking update: send `INFO`.
+5. You receive a required-ack (`HANDOFF`/`BLOCKED`) message and have processed it: run `ack`.
+6. You receive a message and need to indicate it was seen but not completed: run `read`.
+7. You start modifying a scoped area: `reserve`.
+8. You finish scoped work: `release`.
+
+## Inbox Polling Protocol
+
+Minimum polling moments:
+- Session start (before claiming work)
+- Before switching beads
+- Before closing a bead
+- Whenever local state becomes stuck
+
+Recommended interval:
+- Every 60-120 seconds during active execution
+
+Handling required-ack backlog:
+- Prioritize unacked `BLOCKED` first, then `HANDOFF`
+- If action taken, run `ack` immediately
+- If waiting on external input, reply with `DECISION` or `INFO` and keep task status accurate
+
+## Reservation Conflict Policy
+
+Conflict semantics for same/overlapping scope:
+- Active owner blocks takeover: `RESERVATION_CONFLICT`
+- Stale/evicted/expired owner requires explicit intent: `RESERVATION_STALE_FOUND` unless `--takeover-stale`
+- Same owner can refresh reservation without conflict
+
+Operational rule:
+- Never force takeover without `--takeover-stale` when warned
+- Include bead id in every reserve action for traceability
+
+## Worked HANDOFF Flow (End-to-End)
+
+1. Sender completes implementation:
+```bash
+bb agent send \
+  --from silver-scribe \
+  --to graph-scout \
+  --bead beadboard-izs.4 \
+  --category HANDOFF \
+  --subject "Social badges complete" \
+  --body "Please validate edge cases and close" 
+```
+
+2. Recipient checks inbox:
+```bash
+bb agent inbox --agent graph-scout --state unread
+```
+
+3. Recipient reads details:
+```bash
+bb agent read --agent graph-scout --message <message-id>
+```
+
+4. Recipient validates and accepts handoff:
+```bash
+bb agent ack --agent graph-scout --message <message-id>
+```
+
+5. Recipient proceeds with assigned bead work and updates `bd` status/notes.
+
+## `bd mail` Delegate Setup (bb-backed)
+
+`bd mail` delegates to external provider using:
+- `BEADS_MAIL_DELEGATE` / `BD_MAIL_DELEGATE` env vars
+- or `mail.delegate` config key
+
+For BeadBoard driver skill, session preflight configures:
+
+```bash
+bd config set mail.delegate "node <abs-path>/skills/beadboard-driver/scripts/bb-mail-shim.mjs"
+```
+
+Then:
+- `bd mail inbox` -> `bb agent inbox --agent <BB_AGENT>`
+- `bd mail send ...` -> `bb agent send --from <BB_AGENT> ...`
+- `bd mail read <id>` -> `bb agent read --agent <BB_AGENT> --message <id>`
+- `bd mail ack <id>` -> `bb agent ack --agent <BB_AGENT> --message <id>`
+
+Required env:
+
+```bash
+export BB_AGENT=silver-scribe
+```
+
+Fallback behavior if `bb` is missing:
+- Shim exits non-zero and prints: `bb-mail-shim: bb command not found in PATH.`