diff --git a/packages/kilo-docs/lib/nav/code-with-ai.ts b/packages/kilo-docs/lib/nav/code-with-ai.ts
index 3668c18ef72..f30537ca61f 100644
--- a/packages/kilo-docs/lib/nav/code-with-ai.ts
+++ b/packages/kilo-docs/lib/nav/code-with-ai.ts
@@ -62,6 +62,19 @@ export const CodeWithAiNav: NavSection[] = [
       },
     ],
   },
+  {
+    title: "Gastown",
+    links: [
+      { href: "/code-with-ai/gastown", children: "Overview" },
+      { href: "/code-with-ai/gastown/quick-start", children: "Quick Start" },
+      { href: "/code-with-ai/gastown/concepts", children: "Concepts" },
+      { href: "/code-with-ai/gastown/mayor", children: "The Mayor" },
+      { href: "/code-with-ai/gastown/sling-work", children: "Sling Work" },
+      { href: "/code-with-ai/gastown/code-review", children: "Code Review" },
+      { href: "/code-with-ai/gastown/settings", children: "Settings" },
+      { href: "/code-with-ai/gastown/troubleshooting", children: "Troubleshooting" },
+    ],
+  },
   {
     title: "Productivity Tools",
     links: [
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/code-review.md b/packages/kilo-docs/pages/code-with-ai/gastown/code-review.md
new file mode 100644
index 00000000000..ad3d933ea41
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/code-review.md
@@ -0,0 +1,20 @@
+---
+title: "Code Review"
+description: "How the refinery agent reviews and merges code"
+---
+
+# {% $markdoc.frontmatter.title %}
+
+<!-- TODO: Review flow, merge strategies, approval gates -->
+
+## The Review Pipeline
+
+## Merge Strategies
+
+### Direct Merge
+
+### Pull Request Mode
+
+## Review Configuration
+
+## Handling Review Feedback
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/concepts.md b/packages/kilo-docs/pages/code-with-ai/gastown/concepts.md
new file mode 100644
index 00000000000..39a24517644
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/concepts.md
@@ -0,0 +1,24 @@
+---
+title: "Concepts"
+description: "Understand the building blocks of Gastown — towns, beads, convoys, rigs, and agents"
+---
+
+# {% $markdoc.frontmatter.title %}
+
+<!-- TODO: Detailed explanation of each concept with diagrams -->
+
+## Towns
+
+## Beads
+
+## Convoys
+
+## Rigs
+
+## Agents
+
+### Polecats (Coding Agents)
+
+### The Refinery (Review Agent)
+
+### The Mayor (Coordination Agent)
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/index.md b/packages/kilo-docs/pages/code-with-ai/gastown/index.md
new file mode 100644
index 00000000000..19924e06189
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/index.md
@@ -0,0 +1,36 @@
+---
+title: "Gastown"
+description: "Autonomous AI agent orchestration for your codebase"
+---
+
+# {% $markdoc.frontmatter.title %}
+
+Gastown is an autonomous agent orchestration platform that manages multiple AI agents working on your codebase. It coordinates polecats (coding agents), a refinery (code review agent), and a mayor (coordination agent) to handle tasks, code reviews, and merges — all without constant human oversight.
+
+## Core Concepts
+
+- **Towns** — A workspace that connects to your repository and manages agents working on it
+- **Beads** — Units of work (issues, tasks, reviews) that agents pick up and complete
+- **Convoys** — Multi-step workflows that chain beads together in a dependency graph
+- **Rigs** — Repository connections within a town, each with their own agents and configuration
+- **The Mayor** — Your primary interface to the town; a conversational agent that coordinates work and answers questions
+
+## How It Works
+
+1. **Create a town** and connect it to your repository
+2. **Sling work** — describe what you need done, and agents autonomously pick it up
+3. **Agents collaborate** — polecats write code, the refinery reviews and merges, the mayor coordinates
+4. **You stay in control** — review PRs, adjust settings, intervene when needed
+
+## Getting Started
+
+- [Quick Start](/code-with-ai/gastown/quick-start) — Get your first town running in minutes
+- [Concepts](/code-with-ai/gastown/concepts) — Understand towns, beads, convoys, and agents
+- [The Mayor](/code-with-ai/gastown/mayor) — How to interact with your town's coordinator
+
+## Guides
+
+- [Sling Work](/code-with-ai/gastown/sling-work) — Creating tasks and convoys for agents
+- [Code Review](/code-with-ai/gastown/code-review) — How the refinery reviews and merges code
+- [Settings](/code-with-ai/gastown/settings) — Configure models, merge strategies, and agent behavior
+- [Troubleshooting](/code-with-ai/gastown/troubleshooting) — Common issues and how to resolve them
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/mayor.md b/packages/kilo-docs/pages/code-with-ai/gastown/mayor.md
new file mode 100644
index 00000000000..948712e7c1c
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/mayor.md
@@ -0,0 +1,16 @@
+---
+title: "The Mayor"
+description: "How to interact with your town's coordination agent"
+---
+
+# {% $markdoc.frontmatter.title %}
+
+<!-- TODO: Mayor capabilities, conversation patterns, commands -->
+
+## What the Mayor Does
+
+## Talking to the Mayor
+
+## Mayor Commands
+
+## Tips for Effective Communication
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/quick-start.md b/packages/kilo-docs/pages/code-with-ai/gastown/quick-start.md
new file mode 100644
index 00000000000..53f17c012a6
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/quick-start.md
@@ -0,0 +1,8 @@
+---
+title: "Quick Start"
+description: "Get your first Gastown town running in minutes"
+---
+
+# {% $markdoc.frontmatter.title %}
+
+<!-- TODO: Step-by-step guide to creating a town and seeing agents work -->
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/settings.md b/packages/kilo-docs/pages/code-with-ai/gastown/settings.md
new file mode 100644
index 00000000000..f7dd7a018de
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/settings.md
@@ -0,0 +1,20 @@
+---
+title: "Settings"
+description: "Configure models, merge strategies, and agent behavior"
+---
+
+# {% $markdoc.frontmatter.title %}
+
+<!-- TODO: All configurable settings with explanations -->
+
+## Models
+
+## Merge Strategy
+
+## Refinery Configuration
+
+## Agent Limits
+
+## Environment Variables
+
+## Custom Instructions
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/sling-work.md b/packages/kilo-docs/pages/code-with-ai/gastown/sling-work.md
new file mode 100644
index 00000000000..0b3b027d4ab
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/sling-work.md
@@ -0,0 +1,18 @@
+---
+title: "Sling Work"
+description: "Creating tasks and convoys for agents to work on"
+---
+
+# {% $markdoc.frontmatter.title %}
+
+<!-- TODO: How to create beads, convoys, staged work -->
+
+## Creating a Single Task
+
+## Creating a Convoy
+
+## Staged Convoys
+
+## Assigning Priority
+
+## Watching Progress
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/troubleshooting.md b/packages/kilo-docs/pages/code-with-ai/gastown/troubleshooting.md
new file mode 100644
index 00000000000..f621e1ab7e2
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/troubleshooting.md
@@ -0,0 +1,18 @@
+---
+title: "Troubleshooting"
+description: "Common issues and how to resolve them"
+---
+
+# {% $markdoc.frontmatter.title %}
+
+<!-- TODO: Common failure modes and fixes -->
+
+## Agents Not Picking Up Work
+
+## Container Not Starting
+
+## Git Authentication Failures
+
+## Review Loop Issues
+
+## The Mayor is Unresponsive