docs: document GGT harness separation from PGT (gt-dq3)

Created docs/harness.md documenting the GGT harness at ~/gt/ and its
separation from the legacy PGT harness at ~/ai/. Updated architecture.md
and federation-design.md to use ~/gt/ consistently.

Key changes:
- Created harness.md with full harness structure documentation
- Added Harness section to Core Concepts in architecture.md
- Updated mermaid diagrams from ~/ai/ to ~/gt/
- Documented cleanup steps for legacy ~/ai/ artifacts

🤝 Handoff: The ~/ai/ directory has GGT leftovers that can be cleaned:
- rm -rf ~/ai/gastown/mayor/ (old GGT clone)
- rm ~/ai/.beads/redirect (old beads redirect)

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

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

docs/architecture.md

@@ -11,7 +11,7 @@ graph TB
     subgraph "Gas Town"
         Overseer["👤 Overseer<br/>(Human Operator)"]
 
-        subgraph Town["Town (~/ai/)"]
+        subgraph Town["Town (~/gt/)"]
             Mayor["🎩 Mayor<br/>(Global Coordinator)"]
 
             subgraph Rig1["Rig: wyvern"]
@@ -45,6 +45,10 @@ graph TB
 
 ## Core Concepts
 
+### Harness
+
+A **Harness** is the installation directory for Gas Town - the top-level workspace containing all components. The canonical GGT harness is at `~/gt/`. See [harness.md](harness.md) for setup details and migration from legacy configurations.
+
 ### Town
 
 A **Town** is a complete Gas Town installation - the workspace where everything lives. A town contains:
@@ -1281,7 +1285,7 @@ type Worker interface {
 ### Configuration
 
 ```yaml
-# ~/ai/config/outposts.yaml
+# ~/gt/config/outposts.yaml
 outposts:
   - name: local
     type: local

docs/federation-design.md

@@ -12,13 +12,13 @@ Gas Town needs to scale beyond a single machine:
 
 ### Model A: "Town Clone" (VMs)
 
-Clone the entire `~/ai` workspace to a remote VM. It runs like a regular Gas Town:
+Clone the entire `~/gt` workspace to a remote VM. It runs like a regular Gas Town:
 
 ```
 ┌─────────────────────────────────────────┐
 │  GCE VM (or any Linux box)              │
 │                                         │
-│  ~/ai/                # Full town clone │
+│  ~/gt/                # Full town clone │
 │  ├── config/          # Town config     │
 │  ├── mayor/           # Mayor (or none) │
 │  ├── gastown/         # Rig with agents │
@@ -356,7 +356,7 @@ Workers need Claude API access:
 ## Configuration
 
 ```yaml
-# ~/ai/config/outposts.yaml
+# ~/gt/config/outposts.yaml
 outposts:
   # Always present - the local machine
   - name: local

docs/harness.md

@@ -0,0 +1,131 @@
+# Gas Town Harness
+
+A **harness** is a Gas Town installation directory - the top-level workspace where all Gas Town components live.
+
+## GGT Harness Location
+
+The Go implementation of Gas Town (GGT) uses a separate harness from the Python implementation (PGT):
+
+| Implementation | Harness Location | Status |
+|----------------|------------------|--------|
+| GGT (Go) | `~/gt/` | Active, canonical |
+| PGT (Python) | `~/ai/` | Legacy, reference only |
+
+## Harness Structure
+
+A properly configured GGT harness looks like:
+
+```
+~/gt/                              # HARNESS ROOT
+├── CLAUDE.md                      # Mayor role prompting
+├── .beads/                        # Town-level beads (gm-* prefix)
+│   ├── beads.db                   # Mayor mail, coordination
+│   └── config.yaml
+│
+├── mayor/                         # Mayor's HOME at town level
+│   ├── town.json                  # {"type": "town", "name": "..."}
+│   ├── rigs.json                  # Registry of managed rigs
+│   └── state.json
+│
+├── gastown/                       # A rig (project container)
+│   ├── config.json
+│   ├── .beads/ → mayor/rig/.beads # Symlink to canonical beads
+│   ├── mayor/rig/                 # Mayor's clone (beads authority)
+│   ├── refinery/rig/              # Refinery's clone
+│   ├── witness/                   # Witness agent
+│   ├── crew/                      # Overseer workspaces
+│   └── polecats/                  # Worker directories
+│
+└── wyvern/                        # Another rig (same structure)
+```
+
+## Key Directories
+
+### Town Level (`~/gt/`)
+
+- **CLAUDE.md**: Mayor role prompting, loaded when Mayor starts
+- **.beads/**: Town-level beads database (prefix: `gm-`)
+  - Contains Mayor mail and cross-rig coordination beads
+- **mayor/**: Mayor's home directory with town configuration
+
+### Rig Level (`~/gt/<rig>/`)
+
+Each rig is a **container directory** (NOT a git clone) that holds:
+
+- **config.json**: Rig configuration (git_url, beads prefix)
+- **.beads/**: Symlink to `mayor/rig/.beads` (canonical beads)
+- **mayor/rig/**: Mayor's git clone, canonical for beads and worktrees
+- **refinery/rig/**: Refinery's clone for merge operations
+- **witness/**: Witness agent state
+- **crew/**: Overseer's personal workspaces
+- **polecats/**: Worker directories (git worktrees)
+
+## Historical Context: PGT/GGT Separation
+
+During initial GGT development, both implementations briefly shared `~/ai/`:
+
+```
+~/ai/ (legacy mixed harness - DO NOT USE for GGT)
+├── gastown/
+│   ├── .gastown/          # PGT marker
+│   └── mayor/             # OLD GGT clone (deprecated)
+├── mayor/                 # PGT Mayor home
+└── .beads/redirect        # OLD redirect (deprecated)
+```
+
+This caused confusion because:
+- `~/ai/gastown/` contained both PGT markers AND GGT code
+- `~/ai/mayor/` was PGT's Mayor home, conflicting with GGT concepts
+- The beads redirect pointed at GGT beads from a PGT harness
+
+The separation was completed by creating `~/gt/` as the dedicated GGT harness.
+
+## Cleanup Steps for ~/ai/
+
+If you have the legacy mixed harness, clean it up:
+
+```bash
+# Remove old GGT clone (beads are no longer here)
+rm -rf ~/ai/gastown/mayor/
+
+# Remove old beads redirect
+rm ~/ai/.beads/redirect
+
+# Keep PGT-specific files:
+# - ~/ai/mayor/ (PGT Mayor home)
+# - ~/ai/gastown/.gastown/ (PGT marker)
+```
+
+## Creating a New Harness
+
+To create a fresh GGT harness:
+
+```bash
+gt install ~/my-harness
+```
+
+This creates:
+- Town-level directories and configuration
+- Town-level beads database
+- CLAUDE.md for Mayor role
+
+Then add rigs:
+
+```bash
+cd ~/my-harness
+gt rig add myproject https://github.com/user/myproject
+```
+
+## Environment Variables
+
+When spawning agents, Gas Town sets:
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `BEADS_DIR` | Point to rig's beads | `/path/to/rig/.beads` |
+| `BEADS_NO_DAEMON` | Disable daemon for worktrees | `1` |
+
+## See Also
+
+- [Architecture](architecture.md) - Full system design
+- [Federation Design](federation-design.md) - Remote outposts