diff --git a/docs/bootstrap.md b/docs/bootstrap.md
new file mode 100644
index 00000000..a17eb2c6
--- /dev/null
+++ b/docs/bootstrap.md
@@ -0,0 +1,224 @@
+# Bootstrapping Gas Town from a Harness
+
+This guide documents how to bootstrap a full Gas Town installation from a harness repository (e.g., `steveyegge/stevey-gt`).
+
+## Prerequisites
+
+- macOS or Linux
+- Git configured with SSH access to GitHub
+- Homebrew (for macOS)
+
+## Overview
+
+A Gas Town harness is a template repository containing:
+- Town-level configuration (`mayor/`, `.beads/`)
+- Rig configs (`gastown/config.json`, `beads/config.json`)
+- CLAUDE.md for Mayor context
+
+The harness does NOT contain:
+- The actual gt binary (must be built)
+- Full rig structures (must be populated)
+- Agent state files (must be created)
+
+## Step 1: Clone the Harness
+
+```bash
+git clone git@github.com:steveyegge/stevey-gt.git ~/gt
+cd ~/gt
+```
+
+## Step 2: Install Go
+
+Gas Town is written in Go. Install it via Homebrew:
+
+```bash
+brew install go
+go version  # Verify: should show go1.25+
+```
+
+## Step 3: Clone Gastown into Mayor's Rig
+
+The gt binary lives in the gastown repository. Clone it into the mayor's rig directory:
+
+```bash
+mkdir -p ~/gt/gastown/mayor
+git clone git@github.com:steveyegge/gastown.git ~/gt/gastown/mayor/rig
+```
+
+## Step 4: Build the gt Binary
+
+```bash
+cd ~/gt/gastown/mayor/rig
+go build -o gt ./cmd/gt
+```
+
+Optionally install to PATH:
+
+```bash
+mkdir -p ~/bin
+cp gt ~/bin/gt
+# Ensure ~/bin is in your PATH
+```
+
+## Step 5: Populate Rig Structures
+
+For each rig in your harness (gastown, beads, etc.), create the full agent structure:
+
+### Gastown Rig
+
+```bash
+cd ~/gt/gastown
+
+# Create directories
+mkdir -p refinery witness polecats crew/main
+
+# Clone for refinery (canonical main)
+git clone git@github.com:steveyegge/gastown.git refinery/rig
+
+# Clone for crew workspace
+git clone git@github.com:steveyegge/gastown.git crew/main
+```
+
+### Beads Rig
+
+```bash
+cd ~/gt/beads
+
+# Create directories
+mkdir -p refinery mayor witness polecats crew/main
+
+# Clone for each agent
+git clone git@github.com:steveyegge/beads.git refinery/rig
+git clone git@github.com:steveyegge/beads.git mayor/rig
+git clone git@github.com:steveyegge/beads.git crew/main
+```
+
+## Step 6: Create Agent State Files
+
+Each agent needs a state.json file:
+
+```bash
+# Gastown agents
+echo '{"role": "refinery", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/gastown/refinery/state.json
+echo '{"role": "witness", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/gastown/witness/state.json
+echo '{"role": "mayor", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/gastown/mayor/state.json
+
+# Beads agents
+echo '{"role": "refinery", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/beads/refinery/state.json
+echo '{"role": "witness", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/beads/witness/state.json
+echo '{"role": "mayor", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/beads/mayor/state.json
+```
+
+## Step 7: Initialize Town-Level Beads
+
+```bash
+cd ~/gt
+bd init --prefix gm
+```
+
+If there are existing issues in JSONL that fail to import (e.g., due to invalid issue types), you can:
+- Fix the JSONL manually and re-run `bd sync --import-only`
+- Or start fresh with the empty database
+
+Run doctor to check for issues:
+
+```bash
+bd doctor --fix
+```
+
+## Step 8: Verify Installation
+
+```bash
+cd ~/gt
+
+# Check gt works
+gt status
+
+# Check rig structure
+gt rig list
+
+# Expected output:
+# gastown - Polecats: 0, Crew: 1, Agents: [refinery mayor]
+# beads   - Polecats: 0, Crew: 1, Agents: [refinery mayor]
+```
+
+## Troubleshooting
+
+### Go not in PATH
+If `go` command fails, ensure Homebrew's bin is in your PATH:
+```bash
+export PATH="/opt/homebrew/bin:$PATH"
+```
+
+### Witnesses Not Detected
+Known issue (gm-2ej): The witness detection code checks for `witness/rig` but witnesses don't have a git clone. This is a bug in the detection logic - witnesses should still work.
+
+### Beads Import Fails
+Known issue (gm-r6e): If your JSONL contains invalid issue types (e.g., "merge-request"), the import will fail. Either fix the JSONL or start with an empty database.
+
+## Full Bootstrap Script
+
+Here's a condensed script for bootstrapping:
+
+```bash
+#!/bin/bash
+set -e
+
+# Configuration
+HARNESS_REPO="git@github.com:steveyegge/stevey-gt.git"
+GASTOWN_REPO="git@github.com:steveyegge/gastown.git"
+BEADS_REPO="git@github.com:steveyegge/beads.git"
+TOWN_ROOT="$HOME/gt"
+
+# Clone harness
+git clone "$HARNESS_REPO" "$TOWN_ROOT"
+cd "$TOWN_ROOT"
+
+# Install Go if needed
+if ! command -v go &> /dev/null; then
+    brew install go
+fi
+
+# Clone and build gastown
+mkdir -p gastown/mayor
+git clone "$GASTOWN_REPO" gastown/mayor/rig
+cd gastown/mayor/rig
+go build -o gt ./cmd/gt
+cp gt ~/bin/gt
+cd "$TOWN_ROOT"
+
+# Populate gastown rig
+cd gastown
+mkdir -p refinery witness polecats crew/main
+git clone "$GASTOWN_REPO" refinery/rig
+git clone "$GASTOWN_REPO" crew/main
+echo '{"role": "refinery"}' > refinery/state.json
+echo '{"role": "witness"}' > witness/state.json
+echo '{"role": "mayor"}' > mayor/state.json
+cd "$TOWN_ROOT"
+
+# Populate beads rig
+cd beads
+mkdir -p refinery mayor witness polecats crew/main
+git clone "$BEADS_REPO" refinery/rig
+git clone "$BEADS_REPO" mayor/rig
+git clone "$BEADS_REPO" crew/main
+echo '{"role": "refinery"}' > refinery/state.json
+echo '{"role": "witness"}' > witness/state.json
+echo '{"role": "mayor"}' > mayor/state.json
+cd "$TOWN_ROOT"
+
+# Initialize beads
+bd init --prefix gm
+
+# Verify
+gt status
+echo "Bootstrap complete!"
+```
+
+## Next Steps
+
+After bootstrapping:
+1. Start a Mayor session: `gt mayor attach`
+2. Check for work: `bd ready`
+3. Spawn workers as needed: `gt spawn --issue <id>`