diff --git a/docs/architecture.md b/docs/architecture.md
index de916809..fb006147 100644
--- a/docs/architecture.md
+++ b/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
diff --git a/docs/federation-design.md b/docs/federation-design.md
index e6d388a6..129b38a1 100644
--- a/docs/federation-design.md
+++ b/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
diff --git a/docs/harness.md b/docs/harness.md
index 2804facf..e93b5087 100644
--- a/docs/harness.md
+++ b/docs/harness.md
@@ -278,3 +278,39 @@ BEADS_DIR=~/gt/gastown/mayor/.beads bd list
 - **GGT path**: `<rig>/mayor/.beads` for Go Gas Town structure
 
 The harness gives you a unified workspace for managing multiple projects while keeping your AI coordination infrastructure private.
+
+## Historical Context: PGT/GGT Separation
+
+During initial GGT (Go Gas Town) 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)
+```