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/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