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>

CLAUDE.md

@@ -69,7 +69,18 @@ go test ./...
 
 ## Beads Database
 
-Your rig has its own beads database at `/Users/stevey/gt/gastown/.beads`
+**Two-level beads architecture** - understand this to avoid confusion:
+
+| Level | Location | sync-branch | Prefix | Purpose |
+|-------|----------|-------------|--------|---------|
+| Town | `~/gt/.beads/` | NOT set | `hq-*` | Mayor mail, HQ coordination |
+| Rig | `crew/max/.beads/` (this clone) | `beads-sync` | `gt-*` | Project issues |
+
+**Key points:**
+- You're in a **gastown.git clone** - your `.beads/` is tracked in the gastown repo
+- The rig-level `~/gt/gastown/.beads/` is **gitignored** (local runtime state)
+- Your beads sync via `beads-sync` branch to coordinate with other clones
+- Run `bd sync` to push/pull beads changes
 
 Issue prefix: `gt-`
 

docs/architecture.md

@@ -203,6 +203,46 @@ There is no separate orchestrator maintaining workflow state. Beads IS the orche
 | **Pinned beads** | Ongoing concerns that don't close | Planned (post-v1) |
 | **Resource beads** | Leases, locks, quotas | Planned (post-v1) |
 
+#### Two-Level Beads Architecture
+
+Gas Town uses a **two-level beads architecture**. This is critical to understand:
+
+```
+~/gt/                              # Town repo (stevey-gt.git)
+├── .beads/                        # TOWN-LEVEL: HQ beads (tracked here)
+│   ├── config.yaml                # NO sync-branch (single clone)
+│   └── issues.jsonl               # hq-* prefix for mayor mail
+│
+└── gastown/                       # Rig container (NOT a git clone)
+    ├── .beads/                    # GITIGNORED - local runtime state
+    │   └── (populated at runtime)
+    │
+    └── crew/max/                  # Project repo clone (gastown.git)
+        └── .beads/                # RIG-LEVEL: Project beads (tracked in gastown.git)
+            ├── config.yaml        # sync-branch: beads-sync
+            └── issues.jsonl       # gt-* prefix for project issues
+```
+
+**Key points:**
+
+| Level | Location | Git Repo | sync-branch | Prefix | Purpose |
+|-------|----------|----------|-------------|--------|---------|
+| Town | `~/gt/.beads/` | stevey-gt.git | NOT set | `hq-*` | Mayor mail, cross-rig coordination |
+| Rig | `~/gt/gastown/crew/max/.beads/` | gastown.git | `beads-sync` | `gt-*` | Project bugs, features, tasks |
+
+**Why two levels?**
+- **Town beads** are for the Gas Town installation itself (only one clone)
+- **Rig beads** are for the project (shared across multiple clones: crew, polecats, mayor/rig)
+
+**Why different sync-branch settings?**
+- **Town beads**: Single clone at HQ, no coordination needed, commits to main
+- **Rig beads**: Multiple clones (polecats, crew, refinery), need `beads-sync` branch to avoid conflicts with code commits
+
+**Common confusion:**
+- `~/gt/gastown/.beads/` at the rig container level is **gitignored** (local runtime state)
+- The real project beads live in the **gastown.git clones** (e.g., `crew/max/.beads/`)
+- All clones share the same beads via git sync on the `beads-sync` branch
+
 **Molecules** are crystallized workflow patterns that can be attached to work items. See the dedicated **Molecules** section below for full details on composition, nondeterministic idempotence, and built-in workflows.
 
 **The OS Metaphor**: Gas Town is an operating system for work:

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