docs: add two-level beads architecture documentation

Add clear explanations of the town-level vs rig-level beads architecture:
- Town beads (~/gt/.beads): HQ coordination, no sync-branch
- Rig beads (in git clones): project work, uses beads-sync branch
- Clarify that rig-level .beads at container is gitignored

Updated:
- docs/architecture.md: New 'Two-Level Beads Architecture' section
- CLAUDE.md: Enhanced existing section with table and sync-branch info
- templates/roles/*.tmpl: Added beads architecture to crew, polecat, mayor

🤖 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

@@ -31,6 +31,18 @@ Town ({{ .TownRoot }})
 │   └── witness/    ← Polecat lifecycle (doesn't monitor you)
 ```
 
+## Two-Level Beads Architecture
+
+| Level | Location | sync-branch | Prefix | Purpose |
+|-------|----------|-------------|--------|---------|
+| Town | `~/gt/.beads/` | NOT set | `hq-*` | Mayor mail, HQ coordination |
+| Rig | `crew/{{ .Polecat }}/.beads/` | `beads-sync` | project prefix | Project issues |
+
+**Key points:**
+- You're in a project git clone - your `.beads/` is tracked in the project repo
+- The rig-level `{{ .RigName }}/.beads/` is **gitignored** (local runtime state)
+- Run `bd sync` to push/pull beads changes via the `beads-sync` branch
+
 ## Your Workspace
 
 You work from: {{ .WorkDir }}

internal/templates/roles/mayor.md.tmpl

@@ -29,6 +29,19 @@ Town ({{ .TownRoot }})
 - **Refinery**: Per-rig merge queue processor
 - **Beads**: Issue tracking system shared by all rig agents
 
+## Two-Level Beads Architecture
+
+| Level | Location | sync-branch | Prefix | Purpose |
+|-------|----------|-------------|--------|---------|
+| Town | `~/gt/.beads/` | NOT set | `hq-*` | Your mail, HQ coordination |
+| Rig | `<rig>/crew/*/.beads/` | `beads-sync` | project prefix | Project issues |
+
+**Key points:**
+- **Town beads**: Your mail lives here. Commits to main (single clone, no sync needed)
+- **Rig beads**: Project work lives in git clones (crew/*, polecats/*)
+- The rig-level `<rig>/.beads/` is **gitignored** (local runtime state)
+- Rig beads use `beads-sync` branch for multi-clone coordination
+
 ## Responsibilities
 
 - **Work dispatch**: Spawn workers for issues, coordinate batch work on epics

internal/templates/roles/polecat.md.tmpl

@@ -28,6 +28,18 @@ Town ({{ .TownRoot }})
 - **Witness**: Monitors you, nudges if stuck, handles your cleanup
 - **Refinery**: Merges your work when complete
 
+## Two-Level Beads Architecture
+
+| Level | Location | sync-branch | Prefix | Purpose |
+|-------|----------|-------------|--------|---------|
+| Town | `~/gt/.beads/` | NOT set | `hq-*` | Mayor mail, HQ coordination |
+| Rig | `polecats/{{ .Polecat }}/.beads/` | `beads-sync` | project prefix | Project issues |
+
+**Key points:**
+- You're in a project git clone - your `.beads/` is tracked in the project repo
+- The rig-level `{{ .RigName }}/.beads/` is **gitignored** (local runtime state)
+- Run `bd sync` to push/pull beads changes via the `beads-sync` branch
+
 ## Responsibilities
 
 - **Issue completion**: Work on assigned beads issues