docs: Add prefix-based routing to all role templates

Explains how bd commands route to the correct rig based on issue
prefix, and documents routes.jsonl location and debug mode.

Updated templates:
- mayor.md.tmpl (full section)
- crew.md.tmpl (full section)
- polecat.md.tmpl (full section)
- witness.md.tmpl (compact note)
- refinery.md.tmpl (compact note)
- deacon.md.tmpl (full section)

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

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

internal/templates/roles/crew.md.tmpl

@@ -43,6 +43,20 @@ Town ({{ .TownRoot }})
 - Project issues use your clone's beads - `bd` commands use local `.beads/`
 - Run `bd sync` to push/pull beads changes via the `beads-sync` branch
 
+## Prefix-Based Routing
+
+`bd` commands automatically route to the correct rig based on issue ID prefix:
+
+```
+bd show gt-xyz   # Routes to gastown beads (from anywhere in town)
+bd show hq-abc   # Routes to town beads
+```
+
+**How it works:**
+- Routes defined in `~/gt/.beads/routes.jsonl`
+- Each rig's prefix (e.g., `gt-`) maps to its beads location
+- Debug with: `BD_DEBUG_ROUTING=1 bd show <id>`
+
 ## Your Workspace
 
 You work from: {{ .WorkDir }}

internal/templates/roles/deacon.md.tmpl

@@ -33,6 +33,14 @@ Go Daemon (watches you, auto-starts you if down)
 patrol cycle is a wisp that gets squashed to a digest when complete. This keeps
 beads clean while maintaining an audit trail.
 
+## Prefix-Based Routing
+
+`bd` commands automatically route to the correct rig based on issue ID prefix:
+- `bd show gt-xyz` routes to gastown beads
+- `bd show hq-abc` routes to town beads
+
+Routes defined in `~/gt/.beads/routes.jsonl`. Debug with: `BD_DEBUG_ROUTING=1 bd show <id>`
+
 ## Gotchas when Filing Beads
 
 **Temporal language inverts dependencies.** "Phase 1 blocks Phase 2" is backwards.

internal/templates/roles/mayor.md.tmpl

@@ -69,6 +69,25 @@ Town ({{ .TownRoot }})
 - The rig-level `<rig>/.beads/` is **gitignored** (local runtime state)
 - Rig beads use `beads-sync` branch for multi-clone coordination
 
+## Prefix-Based Routing
+
+`bd` commands automatically route to the correct rig based on issue ID prefix:
+
+```
+bd show gt-xyz   # Routes to gastown beads (from anywhere in town)
+bd show hq-abc   # Routes to town beads
+bd show bd-def   # Routes to beads rig
+```
+
+**How it works:**
+- Routes defined in `~/gt/.beads/routes.jsonl`
+- `gt rig add` auto-registers new rig prefixes
+- Each rig's prefix (e.g., `gt-`) maps to its beads location
+
+**Debug routing:** `BD_DEBUG_ROUTING=1 bd show <id>`
+
+**Conflicts:** If two rigs share a prefix, use `bd rename-prefix <new>` to fix.
+
 ## Gotchas when Filing Beads
 
 **Temporal language inverts dependencies.** "Phase 1 blocks Phase 2" is backwards.

internal/templates/roles/polecat.md.tmpl

@@ -40,6 +40,20 @@ Town ({{ .TownRoot }})
 - The rig-level `{{ .RigName }}/.beads/` is **gitignored** (local runtime state)
 - Run `bd sync` to push/pull beads changes via the `beads-sync` branch
 
+## Prefix-Based Routing
+
+`bd` commands automatically route to the correct rig based on issue ID prefix:
+
+```
+bd show gt-xyz   # Routes to gastown beads (from anywhere in town)
+bd show hq-abc   # Routes to town beads
+```
+
+**How it works:**
+- Routes defined in `~/gt/.beads/routes.jsonl`
+- Each rig's prefix (e.g., `gt-`) maps to its beads location
+- Debug with: `BD_DEBUG_ROUTING=1 bd show <id>`
+
 ## Gotchas when Filing Beads
 
 **Temporal language inverts dependencies.** "Phase 1 blocks Phase 2" is backwards.

internal/templates/roles/refinery.md.tmpl

@@ -149,6 +149,8 @@ gt mail send {{ .RigName }}/<worker> -s "Rebase needed" \
 - `bd close <id>` - Close issue after merge
 - `bd sync` - Sync beads changes
 
+**Prefix-based routing:** `bd show gt-xyz` works from anywhere - routes via `~/gt/.beads/routes.jsonl`.
+
 ## Session Cycling
 
 When your context fills up:

internal/templates/roles/witness.md.tmpl

@@ -76,6 +76,8 @@ bd show <id>                             # Issue details
 bd list --status=in_progress             # Active work in rig
 ```
 
+**Prefix-based routing:** `bd show gt-xyz` works from anywhere - routes via `~/gt/.beads/routes.jsonl`.
+
 ---
 
 ## 🚀 PROPULSION: The Universal Law