docs: add Mermaid architecture diagrams

- System overview: Town hierarchy with Overseer, Mayor, Rigs, Agents
- Communication flows: Mail-based agent communication
- Swarm dispatch sequence: Full workflow from Overseer to completion
- Worker cleanup sequence: Witness verification with escalation path
- Session cycling sequence: Mail-to-self handoff pattern
- Rig structure: Visual of container with agent directories
- Merge queue flow: Polecat branches → Refinery → main

All diagrams render in GitHub markdown.

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

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

docs/architecture.md

@@ -2,6 +2,45 @@
 
 Gas Town is a multi-agent workspace manager that coordinates AI coding agents working on software projects. It provides the infrastructure for running swarms of agents, managing their lifecycle, and coordinating their work through mail and issue tracking.
 
+## System Overview
+
+```mermaid
+graph TB
+    subgraph "Gas Town"
+        Overseer["👤 Overseer<br/>(Human Operator)"]
+
+        subgraph Town["Town (~/ai/)"]
+            Mayor["🎩 Mayor<br/>(Global Coordinator)"]
+
+            subgraph Rig1["Rig: wyvern"]
+                W1["👁 Witness"]
+                R1["🔧 Refinery"]
+                P1["🐱 Polecat"]
+                P2["🐱 Polecat"]
+                P3["🐱 Polecat"]
+            end
+
+            subgraph Rig2["Rig: beads"]
+                W2["👁 Witness"]
+                R2["🔧 Refinery"]
+                P4["🐱 Polecat"]
+            end
+        end
+    end
+
+    Overseer --> Mayor
+    Mayor --> W1
+    Mayor --> W2
+    W1 --> P1
+    W1 --> P2
+    W1 --> P3
+    W2 --> P4
+    P1 -.-> R1
+    P2 -.-> R1
+    P3 -.-> R1
+    P4 -.-> R2
+```
+
 ## Core Concepts
 
 ### Town
@@ -51,6 +90,19 @@ Agents communicate via **mail** - JSONL-based inboxes for asynchronous messaging
 - Session handoff (Agent → Self for context cycling)
 - Escalation (Witness → Mayor for stuck workers)
 
+```mermaid
+flowchart LR
+    subgraph "Communication Flows"
+        direction LR
+        Mayor -->|"dispatch swarm"| Refinery
+        Refinery -->|"assign work"| Polecat
+        Polecat -->|"done signal"| Witness
+        Witness -->|"swarm complete"| Mayor
+        Witness -->|"escalation"| Mayor
+        Mayor -->|"escalation"| Overseer["👤 Overseer"]
+    end
+```
+
 ### Beads
 
 **Beads** is the issue tracking system. Gas Town agents use beads to:
@@ -115,6 +167,38 @@ wyvern/                            # Rig = container (NOT a git clone)
 - Refinery's clone is the authoritative "main branch" view
 - Witness may not need its own clone (just monitors polecat state)
 
+```mermaid
+graph TB
+    subgraph Rig["Rig: wyvern (container, NOT a git clone)"]
+        Config["config.json"]
+        Beads[".beads/"]
+
+        subgraph Polecats["polecats/"]
+            Nux["Nux/<br/>(git clone)"]
+            Toast["Toast/<br/>(git clone)"]
+            Capable["Capable/<br/>(git clone)"]
+        end
+
+        subgraph Refinery["refinery/"]
+            RefRig["rig/<br/>(canonical main)"]
+            RefMail["mail/inbox.jsonl"]
+        end
+
+        subgraph Witness["witness/"]
+            WitMail["mail/inbox.jsonl"]
+            WitState["state.json"]
+        end
+
+        subgraph MayorRig["mayor/"]
+            MayRig["rig/<br/>(git clone)"]
+        end
+    end
+
+    Beads -.->|BEADS_DIR| Nux
+    Beads -.->|BEADS_DIR| Toast
+    Beads -.->|BEADS_DIR| Capable
+```
+
 ### Why Decentralized?
 
 Agents live IN rigs rather than in a central location:
@@ -155,6 +239,18 @@ The Refinery manages the merge queue:
 - **Conflict resolution**: Handle merge conflicts
 - **Quality gate**: Ensure tests pass, code quality maintained
 
+```mermaid
+flowchart LR
+    subgraph "Merge Queue Flow"
+        P1[Polecat 1<br/>branch] --> Q[Merge Queue]
+        P2[Polecat 2<br/>branch] --> Q
+        P3[Polecat 3<br/>branch] --> Q
+        Q --> R{Refinery}
+        R -->|merge| M[main]
+        R -->|conflict| P1
+    end
+```
+
 ### Polecat
 
 Polecats are the workers that do actual implementation:
@@ -167,35 +263,60 @@ Polecats are the workers that do actual implementation:
 
 ### Swarm Dispatch
 
-```
+```mermaid
-Mayor                     Refinery                    Polecats
+sequenceDiagram
-  │                          │                           │
+    participant O as 👤 Overseer
-  ├─── [dispatch swarm] ────►│                           │
+    participant M as 🎩 Mayor
-  │                          ├─── [assign issues] ──────►│
+    participant R as 🔧 Refinery
-  │                          │                           │ (work)
+    participant P as 🐱 Polecats
-  │                          │◄── [PR ready] ────────────┤
+
-  │                          │ (review/merge)            │
+    O->>M: Start swarm on issues
-  │◄── [swarm complete] ─────┤                           │
+    M->>R: Dispatch swarm
+    R->>P: Assign issues
+
+    loop For each polecat
+        P->>P: Work on issue
+        P->>R: PR ready
+        R->>R: Review & merge
+    end
+
+    R->>M: Swarm complete
+    M->>O: Report results
 ```
 
 ### Worker Cleanup (Witness-Owned)
 
-```
+```mermaid
-Polecat                   Witness                     Mayor         Overseer
+sequenceDiagram
-  │                          │                           │              │
+    participant P as 🐱 Polecat
-  │ (completes work)         │                           │              │
+    participant W as 👁 Witness
-  ├─── [done signal] ───────►│                           │              │
+    participant M as 🎩 Mayor
-  │                          │ (capture git state)       │              │
+    participant O as 👤 Overseer
-  │                          │ (assess cleanliness)      │              │
+
-  │◄── [nudge if dirty] ─────┤                           │              │
+    P->>P: Complete work
-  │ (fixes issues)           │                           │              │
+    P->>W: Done signal
-  ├─── [done signal] ───────►│                           │              │
+
-  │                          │ (verify clean)            │              │
+    W->>W: Capture git state
-  │                          │ (kill session)            │              │
+    W->>W: Assess cleanliness
-  │                          │                           │              │
+
-  │                          │ (if stuck 3x) ───────────►│              │
+    alt Git state dirty
-  │                          │                           │ (can't fix) ─►│
+        W->>P: Nudge (fix issues)
-  │                          │                           │              │ (human decision)
+        P->>P: Fix issues
+        P->>W: Done signal (retry)
+    end
+
+    alt Clean after ≤3 tries
+        W->>W: Verify clean
+        W->>P: Kill session
+    else Stuck after 3 tries
+        W->>M: Escalate
+        alt Mayor can fix
+            M->>W: Resolution
+        else Mayor can't fix
+            M->>O: Escalate to human
+            O->>M: Decision
+        end
+    end
 ```
 
 ### Session Cycling (Mail-to-Self)
@@ -209,6 +330,24 @@ When an agent's context fills, it hands off to its next session:
 5. **Exit**: End session cleanly
 6. **Resume**: New session reads handoff, picks up where old session left off
 
+```mermaid
+sequenceDiagram
+    participant S1 as Agent Session 1
+    participant MB as 📬 Mailbox
+    participant S2 as Agent Session 2
+
+    S1->>S1: Context filling up
+    S1->>S1: Capture current state
+    S1->>MB: Send handoff note
+    S1->>S1: Exit cleanly
+
+    Note over S1,S2: Session boundary
+
+    S2->>MB: Check inbox
+    MB->>S2: Handoff note
+    S2->>S2: Resume from handoff state
+```
+
 ## Key Design Decisions
 
 ### 1. Witness Owns Worker Cleanup