diff --git a/packages/kilo-docs/lib/nav/code-with-ai.ts b/packages/kilo-docs/lib/nav/code-with-ai.ts
index f30537ca61f..83ba81a5863 100644
--- a/packages/kilo-docs/lib/nav/code-with-ai.ts
+++ b/packages/kilo-docs/lib/nav/code-with-ai.ts
@@ -23,6 +23,19 @@ export const CodeWithAiNav: NavSection[] = [
       { href: "/code-with-ai/platforms/mobile", children: "Mobile Apps" },
       { href: "/code-with-ai/platforms/slack", children: "Slack" },
       { href: "/code-with-ai/app-builder", children: "App Builder" },
+      {
+        href: "/code-with-ai/gastown",
+        children: "Gas Town by Kilo",
+        subLinks: [
+          { 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" },
+        ],
+      },
     ],
   },
   {
@@ -62,19 +75,7 @@ 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
index ad3d933ea41..24ae8b33c70 100644
--- a/packages/kilo-docs/pages/code-with-ai/gastown/code-review.md
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/code-review.md
@@ -5,16 +5,163 @@ description: "How the refinery agent reviews and merges code"
 
 # {% $markdoc.frontmatter.title %}
 
-<!-- TODO: Review flow, merge strategies, approval gates -->
+Every piece of code produced by Gas Town agents goes through automated review before merging. The **refinery** agent is dedicated to critiquing, verifying, and gatekeeping what lands in your codebase.
 
 ## The Review Pipeline
 
+When a polecat finishes a bead and pushes its branch, the work enters the review pipeline:
+
+<!-- TODO: React Flow diagram — Review Pipeline
+  Linear flow with decision points:
+  
+  Polecat "pushes branch" 
+    → MR bead created (status: open)
+    → Refinery dispatched (status: in_progress)
+    → Refinery reviews diff
+    → Decision: "Quality check"
+      → PASS: "Merge" → bead closed ✓
+      → FAIL: "Send feedback" → Polecat revises → Re-submit → (loop back to Refinery)
+  
+  Show retry counter on the loop (max 3 attempts)
+  Caption: "The review pipeline — code must pass refinery review before merging"
+-->
+
+The refinery evaluates:
+- **Correctness** — does the code do what the task asked?
+- **Style** — does it follow project conventions?
+- **Completeness** — are tests included? Are edge cases handled?
+- **Safety** — any security issues, data leaks, or breaking changes?
+
+## Micro-Adversarial Loops
+
+The core insight behind Gas Town's review system is **adversarial iteration**. Rather than one agent producing a final answer, two agents with different objectives improve the output through tension:
+
+<!-- TODO: React Flow diagram — Adversarial Loop Detail
+  Circular/orbital layout showing the tension:
+  
+  Center: "The Code" (evolving artifact)
+  
+  Orbit 1 (Polecat, blue): 
+    Goal: "Ship the feature" → writes code → pushes
+    
+  Orbit 2 (Refinery, amber):
+    Goal: "Protect quality" → reviews → sends feedback OR approves
+    
+  Connection: feedback arrow from Refinery back to Polecat with example text:
+    "Missing error handling in the catch block. The API endpoint should return 
+     a structured error response, not swallow the exception."
+  
+  Polecat then: "Revises with feedback" → pushes again → Refinery re-reviews
+  
+  Style: animated orbital, showing the push-pull dynamic
+  Caption: "Adversarial tension between 'ship it' and 'make it better'"
+-->
+
+This pattern is fundamentally different from having a single agent self-review:
+- Self-review has a **confirmation bias** — the same "mind" that wrote the code evaluates it
+- Adversarial review creates **genuine tension** — the refinery has different priorities than the polecat
+- Each revision cycle **measurably improves** the output because feedback is specific and actionable
+
+### The Loop in Practice
+
+A typical bead goes through 1-2 revision cycles:
+
+| Cycle | What happens |
+|---|---|
+| **Write** | Polecat reads the task, writes code, runs tests, pushes |
+| **Review 1** | Refinery finds 2 issues: missing test case, inconsistent naming |
+| **Revise 1** | Polecat adds the test, fixes naming, pushes again |
+| **Review 2** | Refinery approves — code meets quality bar |
+| **Merge** | Code lands on target branch |
+
+After 3 failed revision cycles, the bead escalates rather than looping forever.
+
 ## Merge Strategies
 
+Gas Town supports two merge strategies, configurable per-town or per-rig:
+
 ### Direct Merge
 
+The refinery merges directly to the target branch (convoy feature branch or main) without creating a GitHub PR. This is faster but gives you less visibility into individual merges.
+
+**Best for:** trusted agent output, internal projects, rapid iteration.
+
 ### Pull Request Mode
 
+The refinery creates a GitHub PR for each merge. The PR includes:
+- The diff
+- Review comments from the refinery
+- Status checks from CI
+
+You can configure whether PRs auto-merge after refinery approval or require human approval.
+
+**Best for:** production codebases, team environments, audit trails.
+
+## Convoy-Level Review
+
+Convoys add an additional review layer beyond per-bead review:
+
+<!-- TODO: React Flow diagram — Convoy Review Layers
+  Three columns showing review at different scopes:
+  
+  Column 1 "Per-Bead Review":
+    Bead 1 → Refinery ✓
+    Bead 2 → Refinery ✓  
+    Bead 3 → Refinery ✓ (with one revision cycle shown)
+    
+  Column 2 "Landing Review":
+    Combined diff (all 3 beads) → Refinery reviews holistically
+    "Does the combined work make sense as a feature?"
+    
+  Column 3 "Human Review" (optional):
+    Final PR to main → Your team reviews
+    
+  Caption: "Three layers of review — individual, combined, and human"
+-->
+
+| Review Layer | What's checked | Who reviews |
+|---|---|---|
+| Per-bead | Individual contribution quality | Refinery agent |
+| Landing | Combined feature coherence | Refinery agent |
+| Human (optional) | Business logic, architecture | Your team |
+
+## Combining with Kilo Code Review
+
+Gas Town's refinery works independently, but combining it with [Kilo Code Review](/code-with-ai/platforms/cloud-agent) creates an even stronger pipeline:
+
+1. **Agent writes** → agent-level refinery reviews (fast, automated)
+2. **Code lands as PR** → Kilo Code Review provides human-readable review (deeper, contextual)
+3. **Human approves** → code ships
+
+This gives you automated adversarial review for speed **plus** AI-assisted human review for judgment — the best of both approaches.
+
 ## Review Configuration
 
+Customize the refinery's behavior in **Town Settings** → **Review**:
+
+| Setting | Options | Default |
+|---|---|---|
+| `review_mode` | `always` / `never` / `pr_only` | `always` |
+| `merge_strategy` | `direct` / `pr` | `direct` |
+| `auto_merge` | `true` / `false` | `true` |
+| `review_gates` | Strictness level (1-5) | 3 |
+| `max_review_cycles` | How many revision attempts | 3 |
+
+### Review Mode
+
+- **`always`** — every bead goes through refinery review (recommended)
+- **`never`** — skip review, merge directly on polecat completion (fast but risky)
+- **`pr_only`** — only review work that creates a PR
+
+### Review Gates
+
+Higher gate levels make the refinery stricter:
+- **Level 1** — basic sanity (compiles, doesn't break tests)
+- **Level 3** — standard (style, tests, correctness) — default
+- **Level 5** — strict (architecture review, performance, security)
+
 ## Handling Review Feedback
+
+When the refinery rejects a submission, it provides specific, actionable feedback. The polecat receives this feedback and revises accordingly. You can see the feedback exchange in the bead's event history.
+
+If a bead fails review 3 times, it transitions to `failed` and creates an **escalation** for human attention. This prevents infinite loops while ensuring difficult code doesn't slip through without proper quality.
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/concepts.md b/packages/kilo-docs/pages/code-with-ai/gastown/concepts.md
index 39a24517644..e478347be6c 100644
--- a/packages/kilo-docs/pages/code-with-ai/gastown/concepts.md
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/concepts.md
@@ -1,24 +1,193 @@
 ---
 title: "Concepts"
-description: "Understand the building blocks of Gastown — towns, beads, convoys, rigs, and agents"
+description: "Understand the building blocks of Gas Town — towns, beads, convoys, rigs, and agents"
 ---
 
 # {% $markdoc.frontmatter.title %}
 
-<!-- TODO: Detailed explanation of each concept with diagrams -->
+Gas Town by Kilo is built around a small set of composable primitives. Understanding these concepts is key to getting the most out of agent orchestration.
 
 ## Towns
 
+A **town** is a persistent workspace where agents operate on your code. It maintains:
+
+- **Configuration** — models, merge strategy, review settings, custom instructions
+- **Agent state** — which agents exist, what they're working on, their capabilities
+- **Work history** — every bead that's been created, worked on, reviewed, and closed
+- **Rig connections** — which repositories are connected and how they're configured
+
+Think of a town as a team's workspace — it accumulates institutional knowledge over time. Agents in your town learn from the history of what's been built, reviewed, and merged.
+
+A town can be personal (owned by you) or organizational (shared across a team).
+
 ## Beads
 
+A **bead** is the fundamental unit of work. Every task, review, and coordination action is represented as a bead with a lifecycle:
+
+<!-- TODO: React Flow diagram — Bead Lifecycle
+  Nodes: open → in_progress → in_review → closed
+  With branch for: open → in_progress → failed
+  And loop: in_review → open (when review rejects)
+  Style: horizontal flow, status-colored nodes (green=closed, blue=in_progress, amber=in_review, red=failed)
+-->
+
+| Status | What's happening |
+|---|---|
+| `open` | Waiting to be picked up by an agent |
+| `in_progress` | An agent is actively working on it |
+| `in_review` | Work is complete, awaiting review by the refinery |
+| `closed` | Successfully completed and merged |
+| `failed` | Could not be completed (agent exhausted retries) |
+
+### Bead Types
+
+| Type | Purpose |
+|---|---|
+| `issue` | A coding task — bug fix, feature, refactor |
+| `merge_request` | A review task for the refinery |
+| `convoy` | A container for multi-step workflows |
+| `escalation` | An issue the agents couldn't resolve — needs human input |
+| `message` | Inter-agent communication |
+
 ## Convoys
 
+A **convoy** is a multi-bead workflow where tasks can depend on each other. Instead of slinging isolated tasks, convoys let you express complex work as a directed graph.
+
+<!-- TODO: React Flow diagram — Convoy DAG Example
+  Nodes: 
+    "Explore codebase" (closed) → "Design schema" (closed) → "Implement API" (in_progress)
+    "Design schema" (closed) → "Write tests" (open)
+    "Implement API" → "Integration tests" (open)
+  Style: DAG layout, edges showing dependencies, node colors by status
+  Caption: "A convoy executing a 5-bead feature implementation"
+-->
+
+When you create a convoy, you define:
+- **Tasks** — what needs to be done (each becomes a bead)
+- **Dependencies** — which tasks must complete before others can start
+- **Feature branch** — a shared branch that convoy work lands on
+
+The reconciler ensures beads are only dispatched when their dependencies are met. This means agents naturally build on each other's work.
+
+### Staged Convoys
+
+Convoys can be **staged** — created but not started immediately. This lets you review the plan before agents begin executing. Un-stage when you're ready to go.
+
 ## Rigs
 
+A **rig** connects a repository to your town. Each rig has:
+
+- Its own set of agents (polecats, refinery)
+- Branch configuration (default branch, merge target)
+- Override settings (model, review mode, merge strategy)
+
+A town can have **multiple rigs** — useful when your project spans several repositories.
+
 ## Agents
 
+Agents are the workers in your town. Each has a specialized role:
+
 ### Polecats (Coding Agents)
 
+Polecats do the actual software engineering:
+
+- Read and understand your codebase
+- Write code changes in isolated git worktrees
+- Run tests and commands to verify their work
+- Push branches when done
+
+Multiple polecats can work in **parallel** on different beads. The default is 2 per rig, configurable up to 5+.
+
+Each polecat gets its own git worktree — they never conflict with each other or with your local development.
+
 ### The Refinery (Review Agent)
 
+The refinery is the quality gate. When a polecat finishes a bead:
+
+1. The refinery reviews the diff
+2. Checks for issues, style violations, missing tests
+3. Either **approves and merges** or **sends feedback**
+4. If feedback is sent, the polecat revises and resubmits
+
+This creates a **micro-adversarial loop** — one agent writes, another critiques, forcing iterative improvement before code lands.
+
+<!-- TODO: React Flow diagram — Micro-Adversarial Loop
+  Circular flow: 
+    Polecat "writes code" → Refinery "reviews" → (approve) → "merge" 
+                                                → (reject) → Polecat "revises" → Refinery "reviews" (loop back)
+  Style: circular/orbital layout, animated edges showing the loop, 
+  highlight the adversarial tension between write and review
+  Caption: "The micro-adversarial loop — code is critiqued before it lands"
+-->
+
 ### The Mayor (Coordination Agent)
+
+The mayor is your interface to the town:
+
+- Plans convoys from high-level descriptions
+- Reports on status and progress
+- Triages issues and escalations
+- Manages agent configuration
+- Answers questions about the codebase and work history
+
+The mayor runs persistently — always available for conversation.
+
+## The Reconciler
+
+The reconciler is the engine that drives the town forward. It runs on every alarm tick (every 5 seconds when work is active) and:
+
+1. **Drains events** — agent completions, status changes, failures
+2. **Evaluates rules** — which beads need agents, which convoys are ready to advance
+3. **Emits actions** — dispatch an agent, create a review, update convoy progress
+4. **Enforces invariants** — no double-dispatch, no orphaned hooks, bounded retries
+
+You don't interact with the reconciler directly — it's the autonomous engine that keeps the town moving.
+
+## The Micro-Adversarial Loop
+
+The most powerful concept in Gas Town is the **micro-adversarial loop**. Rather than trusting a single agent's output, every piece of work goes through an adversarial cycle:
+
+<!-- TODO: React Flow diagram — Full Adversarial Pipeline
+  Multi-lane flow showing:
+  Lane 1 (Polecat): "Read task" → "Write code" → "Run tests" → "Push branch"
+  Lane 2 (Refinery): "Review diff" → decision diamond "Quality?" 
+    → Yes: "Merge to target"
+    → No: "Send feedback" → (back to Polecat "Revise")
+  Lane 3 (Convoy level): Multiple beads flowing through the pipeline in sequence,
+    each one building on the merged output of the previous
+  
+  Caption: "Every bead goes through write → review → revise cycles before landing"
+-->
+
+This pattern compounds when combined with **convoys**:
+
+1. Bead 1: Explore the codebase → reviewed → merged to convoy branch
+2. Bead 2: Design the schema (builds on bead 1's context) → reviewed → merged
+3. Bead 3: Implement the feature (builds on beads 1+2) → reviewed → merged
+4. **Landing review**: The full convoy branch is reviewed as a cohesive unit before merging to main
+
+At every stage, work is critiqued and refined. Combined with Kilo's [Code Review](/code-with-ai/gastown/code-review) product, this creates a pipeline where code is reviewed multiple times by different agents with different perspectives before it ever reaches your main branch.
+
+## How It All Fits Together
+
+<!-- TODO: React Flow diagram — Full Town Architecture
+  Shows the complete flow:
+  User → Mayor (chat) → creates Convoy/Beads
+  Reconciler (center, engine) → dispatches Polecats
+  Polecat → pushes branch → Refinery reviews → merges
+  Container (wrapping polecats) with git worktrees
+  Rig connecting to GitHub repo
+  
+  Style: similar to the Connect talk architecture diagram but simplified for docs
+  Caption: "The complete Gas Town architecture"
+-->
+
+| Component | Responsibility |
+|---|---|
+| **You** | Describe work, review PRs, set direction |
+| **Mayor** | Plan, coordinate, communicate |
+| **Reconciler** | Schedule, dispatch, enforce rules |
+| **Polecats** | Write code, run tests, push branches |
+| **Refinery** | Review, critique, merge |
+| **Container** | Isolated environment with git, tools, runtime |
+| **Rig** | Repository connection and configuration |
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/index.md b/packages/kilo-docs/pages/code-with-ai/gastown/index.md
index 19924e06189..0dae8954a8e 100644
--- a/packages/kilo-docs/pages/code-with-ai/gastown/index.md
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/index.md
@@ -1,36 +1,103 @@
 ---
-title: "Gastown"
+title: "Gas Town by Kilo"
 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.
+Gastown by Kilo is an autonomous agent orchestration platform that manages teams of AI agents working on your codebase. Built on [Gastown](https://gastown.dev) — the open protocol for agent orchestration — Kilo's implementation coordinates coding agents, a code review agent, and a conversational coordinator to ship features, fix bugs, and maintain your projects with minimal human intervention.
 
-## Core Concepts
+You describe the work. Agents figure out how to do it, write the code, review each other's output, and land clean PRs — while you stay in control of what ships.
 
-- **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
+<!-- TODO: Screenshot — town overview page showing active agents, beads in progress, and a recent merge -->
+
+## What Makes Gastown Different
+
+Unlike single-agent coding tools that handle one task at a time, Gastown orchestrates **multiple specialized agents** working in parallel:
+
+| Agent | Role | What it does |
+|---|---|---|
+| **Polecats** | Coding | Write code, run tests, push branches. Multiple can work simultaneously on different tasks. |
+| **Refinery** | Code Review | Reviews polecat output, runs quality checks, merges approved work. |
+| **Mayor** | Coordination | Your conversational interface. Plans work, answers questions, triages issues, keeps things moving. |
+
+These agents operate within a **town** — a persistent workspace connected to your repository. The town maintains state across sessions: work history, agent configuration, and institutional knowledge about your codebase.
+
+<!-- TODO: Screenshot — the mayor chat interface showing a conversation about planning work -->
 
 ## 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
+### 1. Create a town
+
+Connect a GitHub repository to a new town. Gastown provisions a dedicated environment with agents ready to work.
+
+### 2. Sling work
+
+Describe what needs to be done — a bug to fix, a feature to build, a refactor to execute. You can sling a single task or a **convoy** (a multi-step plan where tasks depend on each other).
+
+<!-- TODO: Screenshot — the "Sling Work" dialog or the convoy creation UI -->
+
+### 3. Agents pick it up
+
+The reconciler assigns open work to available polecats. Each agent gets its own git worktree, writes code, runs commands, and pushes a branch when done.
+
+### 4. Code gets reviewed
+
+Completed work flows to the refinery for automated code review. Depending on your merge strategy, the refinery either merges directly or creates a PR for your approval.
+
+### 5. You stay in control
+
+Monitor progress from the town dashboard. Chat with the mayor. Review PRs. Adjust priorities. Intervene when agents need guidance. Everything the agents do is visible — branches, commits, review comments, and decision reasoning.
+
+<!-- TODO: Screenshot — beads page showing a mix of closed, in-progress, and open beads -->
+
+## Core Concepts
+
+| Concept | What it is |
+|---|---|
+| **Town** | A persistent workspace connecting your repo to a team of agents. Maintains configuration, history, and state. |
+| **Bead** | A unit of work — an issue to fix, a task to complete, a review to perform. Beads have a lifecycle: open, in progress, in review, closed. |
+| **Convoy** | A multi-bead workflow. Beads within a convoy can depend on each other, forming a DAG that agents execute in order. |
+| **Rig** | A repository connection within a town. Each rig has its own branch configuration, agents, and settings. A town can have multiple rigs. |
+| **Mayor** | The coordination agent. Your primary interface for interacting with the town through natural language. |
+| **Polecat** | A coding agent. Works on individual beads — reads code, makes changes, runs tests, pushes branches. |
+| **Refinery** | The review agent. Checks polecat output for quality, performs merges, and gates what lands in your codebase. |
+
+For a deeper dive, see [Concepts](/code-with-ai/gastown/concepts).
+
+## The Mayor — Your Interface to the Town
+
+The mayor is how you interact with Gastown conversationally. Think of it as a technical lead that knows your codebase, tracks what all agents are doing, and can take action on your behalf.
+
+You can ask the mayor to:
+
+- Plan and create convoys from high-level descriptions
+- Check on the status of in-progress work
+- Investigate failures and stuck agents
+- Update town settings and configuration
+- Triage incoming issues or bug reports
+
+The mayor runs persistently in your town — it's always available, even when no coding agents are active.
+
+<!-- TODO: Screenshot — mayor conversation showing it creating a convoy from a user request -->
+
+## What You Can Build With Gastown
+
+- **Feature development** — Describe a feature, get back a PR with tests
+- **Bug fixes** — Point agents at an issue, they investigate and fix it
+- **Refactoring** — Large-scale codebase changes executed methodically across convoys
+- **Maintenance** — Dependency updates, lint fixes, documentation generation
+- **Code review** — Automated first-pass review on all agent and human PRs
 
 ## 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
+- [Quick Start](/code-with-ai/gastown/quick-start) — Create your first town and see agents work in under 5 minutes
+- [Concepts](/code-with-ai/gastown/concepts) — Detailed explanation of towns, beads, convoys, and the agent lifecycle
+- [The Mayor](/code-with-ai/gastown/mayor) — How to interact with the coordination agent effectively
 
 ## 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
+- [Sling Work](/code-with-ai/gastown/sling-work) — Creating tasks, convoys, and staged workflows
+- [Code Review](/code-with-ai/gastown/code-review) — Merge strategies, review gates, and the refinery pipeline
+- [Settings](/code-with-ai/gastown/settings) — Model configuration, agent limits, custom instructions, and environment variables
 - [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
index 948712e7c1c..1092eb7d93c 100644
--- a/packages/kilo-docs/pages/code-with-ai/gastown/mayor.md
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/mayor.md
@@ -5,12 +5,100 @@ description: "How to interact with your town's coordination agent"
 
 # {% $markdoc.frontmatter.title %}
 
-<!-- TODO: Mayor capabilities, conversation patterns, commands -->
+The Mayor is your primary interface to a Gas Town. It's a persistent conversational agent that coordinates work, answers questions, and takes action on your behalf.
 
 ## What the Mayor Does
 
+The Mayor operates as a technical lead that:
+
+- **Plans work** — converts high-level descriptions into convoys and beads
+- **Reports status** — knows what every agent is doing, what's stuck, what's shipped
+- **Triages issues** — investigates failures, stuck agents, and escalations
+- **Configures the town** — updates settings, manages rigs, adjusts agent behavior
+- **Answers questions** — about the codebase, work history, and town state
+
+Unlike polecats (which spin up to work on specific beads), the Mayor runs **persistently**. It's always available, even when no coding agents are active.
+
+<!-- TODO: Screenshot — Mayor chat interface showing a multi-turn conversation -->
+
 ## Talking to the Mayor
 
-## Mayor Commands
+Open the Mayor panel from your town dashboard. The conversation is persistent — the Mayor remembers context from previous messages within the same session.
+
+### Planning Work
+
+Ask the Mayor to create work for the town:
+
+> *"Create a convoy to add authentication to the API. We need JWT token generation, middleware for protected routes, and integration tests."*
+
+The Mayor will:
+1. Break this into individual beads with dependencies
+2. Propose a convoy plan for your review
+3. Create the convoy (staged by default, so you can review before agents start)
+
+### Checking Status
+
+> *"What's everyone working on?"*
+> *"Is anything stuck?"*
+> *"How did the last convoy go?"*
+
+The Mayor has full visibility into agent state, bead progress, and recent history.
+
+### Investigating Problems
+
+> *"The auth refactor bead has been in progress for 20 minutes — what's happening?"*
+> *"Why did the refinery reject the last review?"*
+
+The Mayor can inspect agent status messages, review feedback, and container logs to diagnose issues.
+
+### Updating Configuration
+
+> *"Switch the model to Claude Opus for this town"*
+> *"Set max polecats to 4"*
+> *"Add a custom instruction: always use TypeScript strict mode"*
+
+The Mayor can modify town settings on your behalf through natural language.
+
+## Mayor Tools
+
+The Mayor has access to specialized tools for town management:
+
+| Tool | What it does |
+|---|---|
+| `gt_sling` | Create a bead or convoy |
+| `gt_convoy_close` | Force-close a stuck convoy |
+| `gt_agent_reset` | Reset a stuck agent |
+| `gt_bead_delete` | Delete beads (single or bulk) |
+| `gt_report_bug` | File a bug report about town behavior |
+| `gt_done` | Mark work as complete |
+
+These tools are used automatically when you make requests — you don't need to invoke them directly.
 
 ## Tips for Effective Communication
+
+### Be specific about scope
+
+Instead of: *"Fix the bugs"*
+
+Try: *"Fix the TypeScript type errors in src/auth/. There are 3 reported in the CI output."*
+
+### Use convoys for complex work
+
+Instead of: *"Add a user dashboard with charts, settings, and notifications"*
+
+Try: *"Create a staged convoy for the user dashboard. Break it into: 1) dashboard layout and navigation, 2) chart components with mock data, 3) settings page, 4) notification system. Each should build on the previous."*
+
+### Let the Mayor triage
+
+When something goes wrong, ask the Mayor before investigating yourself:
+
+> *"Bead abc123 has been stuck for 30 minutes — can you investigate?"*
+
+The Mayor can often diagnose and resolve issues (reset agents, close stuck convoys, re-dispatch work) without you needing to dig into the admin panel.
+
+## Mayor Limitations
+
+- The Mayor coordinates but doesn't write code itself — that's what polecats are for
+- It can only see what's happening inside your town, not external systems
+- Complex multi-repo orchestration may need manual coordination between towns
+- The Mayor's context window is bounded — very long conversations may lose early context
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
index 53f17c012a6..c194cdc1ef7 100644
--- a/packages/kilo-docs/pages/code-with-ai/gastown/quick-start.md
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/quick-start.md
@@ -1,8 +1,88 @@
 ---
 title: "Quick Start"
-description: "Get your first Gastown town running in minutes"
+description: "Get your first Gas Town running in minutes"
 ---
 
 # {% $markdoc.frontmatter.title %}
 
-<!-- TODO: Step-by-step guide to creating a town and seeing agents work -->
+This guide walks you through creating your first town, connecting a repository, and watching agents work on real code.
+
+## Prerequisites
+
+- A [Kilo account](https://app.kilo.ai) (free tier works)
+- A GitHub repository you want agents to work on
+- A GitHub Personal Access Token (recommended)
+
+## 1. Create a Town
+
+From the Kilo dashboard, click **New Town**. Give it a name — this is just for your reference.
+
+<!-- TODO: Screenshot — "New Town" button and creation dialog -->
+
+## 2. Connect a Repository
+
+Add a **rig** to your town. A rig is a connection to a specific repository.
+
+1. Click **Add Rig**
+2. Select your GitHub repository (or paste the URL)
+3. Choose the default branch (usually `main`)
+4. Click **Connect**
+
+Gastown uses the [Kilo GitHub App](https://github.com/apps/kilo-code) to access your repository. You'll be prompted to install it if you haven't already.
+
+<!-- TODO: Screenshot — rig creation flow showing repo selection -->
+
+## 3. Add a GitHub Personal Access Token
+
+{% callout type="tip" title="Recommended" %}
+Adding a GitHub PAT means all commits, branches, and PRs created by your town's agents will appear as **you** — not a bot account. It also enables agents to use `gh` CLI commands (creating issues, commenting on PRs, etc.) on your behalf.
+{% /callout %}
+
+1. Go to **Town Settings** → **Git & Authentication**
+2. Paste your GitHub Personal Access Token
+3. The token needs `repo` scope (and `workflow` if your repo uses GitHub Actions)
+
+Without a PAT, agents use the GitHub App installation token — functional but shows up as a bot in your git history.
+
+## 4. Sling Your First Task
+
+Now let's give the agents something to do:
+
+1. Click **Sling Work** (or ask the Mayor)
+2. Describe a simple task, e.g.: *"Add a CONTRIBUTING.md file with basic setup instructions"*
+3. Click **Sling**
+
+<!-- TODO: Screenshot — Sling Work dialog with a sample task -->
+
+## 5. Watch Agents Work
+
+The reconciler assigns your task to an available polecat agent. You'll see:
+
+1. A **bead** appear in the beads list with status `open`
+2. The bead transitions to `in_progress` as a polecat picks it up
+3. The agent reads your code, makes changes, and pushes a branch
+4. The bead moves to `in_review` as the refinery checks the work
+5. The refinery merges (or creates a PR depending on your settings)
+6. The bead reaches `closed`
+
+<!-- TODO: Screenshot — bead lifecycle showing the transitions in real-time -->
+
+The whole cycle typically takes 2-10 minutes depending on complexity and the model you're using.
+
+## 6. Talk to the Mayor
+
+Click the **Mayor** chat to interact with your town's coordinator. Try:
+
+- *"What's the status of the town?"*
+- *"Create a convoy to add unit tests for the auth module"*
+- *"What settings should I change for faster reviews?"*
+
+The Mayor is always running — it's your primary interface for managing the town conversationally.
+
+<!-- TODO: Screenshot — Mayor chat with a greeting and status response -->
+
+## What's Next?
+
+- [Concepts](/code-with-ai/gastown/concepts) — Understand the building blocks in depth
+- [Sling Work](/code-with-ai/gastown/sling-work) — Learn about convoys and multi-step workflows
+- [Settings](/code-with-ai/gastown/settings) — Configure models, merge strategies, and agent behavior
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/settings.md b/packages/kilo-docs/pages/code-with-ai/gastown/settings.md
index f7dd7a018de..60479d5b30f 100644
--- a/packages/kilo-docs/pages/code-with-ai/gastown/settings.md
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/settings.md
@@ -5,16 +5,161 @@ description: "Configure models, merge strategies, and agent behavior"
 
 # {% $markdoc.frontmatter.title %}
 
-<!-- TODO: All configurable settings with explanations -->
+Gas Town settings control how your agents behave — which models they use, how they review code, and how they interact with your repositories.
+
+Access settings from your town dashboard → **Settings**.
 
 ## Models
 
+### Default Model
+
+The primary model used by all agents (polecats, refinery, mayor). This affects quality, speed, and cost.
+
+Popular choices:
+- **Claude Sonnet** — fast, good for most tasks (default)
+- **Claude Opus** — highest quality, best for complex work
+- **Kilo Auto Free** — free tier, great for trying things out
+
+### Role-Specific Models
+
+Override the default model for specific agent roles:
+
+| Role | Recommended | Why |
+|---|---|---|
+| Polecat | Claude Sonnet / Opus | Balance of speed and quality for code generation |
+| Refinery | Claude Opus | Higher reasoning for thorough review |
+| Mayor | Claude Sonnet | Fast responses for conversational coordination |
+
+### Small Model
+
+Used for lightweight tasks (classification, routing, summarization). Usually a smaller, cheaper model.
+
+## Git & Authentication
+
+### GitHub Personal Access Token
+
+{% callout type="tip" title="Strongly Recommended" %}
+Adding a GitHub PAT ensures that all commits, branches, and PRs created by your agents appear as **you** in git history. Without it, activity shows up under the Kilo GitHub App bot account.
+{% /callout %}
+
+**To add a PAT:**
+1. Go to **Settings** → **Git & Authentication**
+2. Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens)
+3. Required scopes: `repo` (full repository access)
+4. Recommended: also add `workflow` (if your repo uses GitHub Actions)
+5. Paste the token and save
+
+**What the PAT enables:**
+- Commits and PRs appear as you (your avatar, your username)
+- Agents can use `gh` CLI commands on your behalf
+- Full access to private repositories you own
+- Ability to trigger CI workflows
+
+**Without a PAT:**
+- The GitHub App installation token is used (functional but less personal)
+- PRs show as created by the Kilo bot
+- Some `gh` CLI operations may not work
+
+### GitHub App Installation
+
+The [Kilo GitHub App](https://github.com/apps/kilo-code) provides base-level repository access. It's installed per-organization or per-repository and gives agents read/write access to code, PRs, and issues.
+
+The GitHub App is **required** — it's how Gastown gets installation tokens for cloning and pushing. The PAT is **optional but recommended** — it provides user-level attribution.
+
 ## Merge Strategy
 
+Controls how reviewed code lands in your repository:
+
+| Strategy | Behavior | Best for |
+|---|---|---|
+| `direct` | Refinery merges directly (no PR) | Speed, trusted environments |
+| `pr` | Refinery creates a PR | Audit trail, team visibility, CI integration |
+
+For `pr` mode, you can also configure:
+- **Auto-merge** — PRs merge automatically after refinery approval
+- **Require human approval** — PRs wait for a human reviewer
+
 ## Refinery Configuration
 
+### Review Mode
+
+| Mode | Behavior |
+|---|---|
+| `always` | Every completed bead goes through review (default, recommended) |
+| `never` | Skip review entirely — merge on polecat completion |
+| `pr_only` | Only review work that generates a PR |
+
+### Review Gates
+
+Strictness level from 1 (lenient) to 5 (strict). Higher levels mean the refinery will reject more frequently but produce higher quality output.
+
+### Max Review Cycles
+
+How many write → review → revise cycles before a bead fails and escalates. Default: 3.
+
 ## Agent Limits
 
+### Max Polecats Per Rig
+
+How many coding agents can work simultaneously on a single rig. Default: 2.
+
+Higher values mean more parallel work but also more resource consumption. Consider:
+- **1-2** — conservative, good for small repos or limited budgets
+- **3-4** — moderate parallelism, good for medium projects
+- **5+** — aggressive, best for large repos with lots of independent work
+
+### Alarm Intervals
+
+Controls how frequently the reconciler checks for work:
+- **Active interval** — when agents are working (default: 5s)
+- **Idle interval** — when no work is pending (default: 60s)
+
+Lower active intervals mean faster response to events but more compute usage.
+
 ## Environment Variables
 
+Add environment variables that are available to all agents in the container. Useful for:
+- API keys for external services agents might test against
+- Database connection strings for test environments
+- Feature flags or configuration values
+
+{% callout type="warning" %}
+Environment variables are visible to all agents in the town. Do not store production secrets here — use test/development credentials only.
+{% /callout %}
+
 ## Custom Instructions
+
+Free-form text injected into every agent's system prompt. Use this to communicate:
+
+- Project conventions: *"Always use TypeScript strict mode"*
+- Architecture decisions: *"The auth module uses JWT with RS256. Never use HS256."*
+- Style preferences: *"Use functional components with hooks, never class components"*
+- Constraints: *"Do not modify files in the `vendor/` directory"*
+- Testing requirements: *"Every new function must have a corresponding unit test"*
+
+Custom instructions are powerful — they let you encode institutional knowledge that agents follow consistently.
+
+## Convoy Settings
+
+### Staged Convoys Default
+
+When `true`, new convoys are created as staged (paused until you un-stage). Default: `true`.
+
+### Convoy Merge Mode
+
+| Mode | Behavior |
+|---|---|
+| `review-then-land` | Each bead merges to a feature branch, then a landing review merges to main (default) |
+| `review-and-merge` | Each bead goes through review and merges directly to main (no feature branch) |
+
+`review-then-land` provides the strongest quality guarantees but takes longer. Use `review-and-merge` for simpler tasks or when you want immediate feedback.
+
+## Per-Rig Overrides
+
+Any town-level setting can be overridden at the rig level. This lets you:
+- Use a more powerful model for a complex repository
+- Set stricter review gates for a production codebase
+- Allow more polecats on a repo with many independent modules
+- Disable review for a documentation-only repo
+
+Access per-rig settings from the rig detail page → **Settings**.
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
index 0b3b027d4ab..f481421395a 100644
--- a/packages/kilo-docs/pages/code-with-ai/gastown/sling-work.md
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/sling-work.md
@@ -5,14 +5,152 @@ description: "Creating tasks and convoys for agents to work on"
 
 # {% $markdoc.frontmatter.title %}
 
-<!-- TODO: How to create beads, convoys, staged work -->
+"Slinging work" is how you give agents something to do. You can sling a single task (a bead) or a structured multi-step plan (a convoy).
 
-## Creating a Single Task
+## Single Tasks
 
-## Creating a Convoy
+The simplest way to use Gas Town — describe what needs to be done, and an agent picks it up:
 
-## Staged Convoys
+1. Click **Sling Work** in the town header
+2. Write a description: *"Fix the 404 error on the /settings page — the route is missing from the router config"*
+3. Click **Sling**
+
+The reconciler assigns the bead to an available polecat. The agent reads the relevant code, makes the fix, runs any tests, and pushes a branch.
+
+<!-- TODO: Screenshot — Sling Work dialog with a single task -->
+
+### Writing Good Task Descriptions
+
+The quality of agent output directly correlates with the clarity of your description:
+
+| Approach | Example |
+|---|---|
+| **Vague** (avoid) | "Fix the auth" |
+| **Specific** (better) | "Fix the JWT token expiration — tokens should last 24h, not 1h. The constant is in `src/auth/config.ts`" |
+| **Contextual** (best) | "Fix #142: users are getting logged out after 1 hour. The issue is the JWT expiration in `src/auth/config.ts` is set to 3600 (1h) but should be 86400 (24h). Add a test to verify." |
+
+Include:
+- **What** needs to change
+- **Where** in the codebase (file paths if you know them)
+- **Why** it's needed (link to issues, error messages)
+- **How to verify** (tests to run, behavior to check)
+
+## Convoys
+
+Convoys are where Gas Town really shines. Instead of one agent doing everything in one pass, convoys break complex work into stages where each builds on the last — with adversarial review at every step.
+
+### Why Convoys?
+
+Single-pass agent output has a quality ceiling. The longer an agent works on one task, the more likely it is to accumulate compounding errors. Convoys solve this by:
+
+1. **Decomposing** complex work into focused, reviewable chunks
+2. **Sequencing** so later steps build on reviewed, merged code
+3. **Reviewing** each chunk independently before it becomes the foundation for the next step
+4. **Containing failures** — if step 3 fails, steps 1 and 2 are already safely merged
+
+<!-- TODO: React Flow diagram — Convoy vs Single-Pass Comparison
+  Two parallel flows:
+  
+  Top (Single-Pass): 
+    "Big task" → Polecat works 30min → "Large PR (800 lines)" → Review struggles → Bugs land
+    
+  Bottom (Convoy):
+    "Explore" → review ✓ → "Design" → review ✓ → "Implement" → review ✓ → "Test" → review ✓ → Clean merged result
+    Each step: small PR, easy review, bugs caught early
+    
+  Caption: "Convoys produce higher quality output through iterative adversarial review"
+-->
+
+### Creating a Convoy
+
+**Via the UI:**
+1. Click **Sling Work** → **Convoy**
+2. Add tasks in order
+3. Define dependencies (which tasks block others)
+4. Choose **staged** (review plan first) or **immediate** (start right away)
+
+**Via the Mayor:**
+> *"Create a convoy to migrate the database from PostgreSQL to MySQL. Steps: 1) audit current schema and queries, 2) design the new schema with migration plan, 3) implement the migration scripts, 4) update the application layer, 5) add integration tests"*
+
+The Mayor converts this into a convoy with proper dependencies.
+
+<!-- TODO: Screenshot — Convoy creation UI showing task list with dependency arrows -->
+
+### Convoy Execution
+
+Once started, the reconciler manages the convoy:
+
+<!-- TODO: React Flow diagram — Convoy Execution Flow
+  Animated stage-by-stage flow:
+  
+  Stage 1: Bead "Audit schema" dispatched to Polecat-1
+    → Polecat works → pushes branch → Refinery reviews → MERGE to convoy branch
+  
+  Stage 2: Bead "Design migration" dispatched to Polecat-2 (starts from convoy branch)  
+    → Polecat works (has context from stage 1) → pushes → Refinery reviews → MERGE
+  
+  Stage 3: Bead "Implement scripts" dispatched (starts from convoy branch with stages 1+2)
+    → works → pushes → reviews → MERGE
+  
+  Final: "Landing Review" — full convoy branch reviewed as cohesive unit → MERGE to main
+  
+  Caption: "Each stage builds on merged, reviewed work from previous stages"
+-->
+
+Key behaviors:
+- Each polecat starts from the **convoy feature branch**, which accumulates all previously merged work
+- Beads only dispatch when their **dependencies are satisfied** (upstream beads closed)
+- The refinery reviews each sub-PR against the convoy branch
+- Once all beads close, a **landing review** checks the full combined diff before merging to main
+
+### The Adversarial Advantage
+
+The convoy pattern creates **layered adversarial review**:
+
+1. **Per-bead review** — refinery critiques each individual contribution
+2. **Context accumulation** — each agent builds on verified, reviewed code
+3. **Landing review** — the complete feature is reviewed holistically
+4. **Combined with Kilo Code Review** — if configured, human reviewers see the final PR too
+
+This means code goes through **3-4 review passes** before landing in your main branch. Bugs get caught at the smallest possible scope where they're cheapest to fix.
+
+### Staged Convoys
+
+By default, convoys are created **staged** — the plan exists but agents don't start until you un-stage it. This lets you:
+
+- Review the task breakdown before execution
+- Adjust descriptions, add context, reorder
+- Ensure the plan makes sense before burning compute
+
+Un-stage via the convoy detail page or ask the Mayor: *"Start the database migration convoy"*
 
 ## Assigning Priority
 
+Beads have priority levels: `low`, `medium` (default), `high`, `critical`.
+
+Higher priority beads are dispatched first when multiple beads are waiting for agents. Set priority:
+- In the Sling Work dialog
+- Via the Mayor: *"Make the auth fix high priority"*
+- By editing the bead after creation
+
 ## Watching Progress
+
+### Beads Page
+
+The beads list shows all work in your town with real-time status updates. Filter by:
+- Status (open, in progress, in review, closed, failed)
+- Type (issue, merge_request, convoy)
+- Rig (if you have multiple repos)
+
+<!-- TODO: Screenshot — Beads page with filter controls and mixed status beads -->
+
+### Town Overview
+
+The town overview shows a high-level summary:
+- Active agents and what they're working on
+- Recent completions
+- Pending work queue
+
+### Real-Time Events
+
+The event timeline shows every state transition as it happens — bead dispatched, review submitted, merge completed. Useful for understanding the flow in real-time.
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/troubleshooting.md b/packages/kilo-docs/pages/code-with-ai/gastown/troubleshooting.md
index f621e1ab7e2..83c112ed832 100644
--- a/packages/kilo-docs/pages/code-with-ai/gastown/troubleshooting.md
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/troubleshooting.md
@@ -5,14 +5,133 @@ description: "Common issues and how to resolve them"
 
 # {% $markdoc.frontmatter.title %}
 
-<!-- TODO: Common failure modes and fixes -->
+Gas Town is a complex system with multiple agents, containers, and external integrations. When things go wrong, this guide helps you diagnose and fix common issues.
 
 ## Agents Not Picking Up Work
 
+**Symptom:** Beads stay in `open` status. No agents transition to `working`.
+
+**Common causes:**
+
+| Cause | Fix |
+|---|---|
+| All polecats at max dispatch attempts | Ask the Mayor: *"Reset agent dispatch attempts"* |
+| Container not running | Check container status in the admin panel. The Mayor can confirm: *"Is the container running?"* |
+| Reconciler paused (draining) | Wait for drain to complete, or cancel it in settings |
+| No available polecats | Check `max_polecats_per_rig` — you may need to increase it |
+
+**Quick fix:** Ask the Mayor: *"Why aren't beads getting picked up?"* — it can diagnose and often resolve the issue.
+
 ## Container Not Starting
 
+**Symptom:** The container status shows errors or stays in "starting" indefinitely.
+
+**Common causes:**
+- Git clone failure (bad credentials, repo not accessible)
+- GitHub App not installed on the repository
+- Environment variables causing startup crash
+
+**Fix:**
+1. Check that the [Kilo GitHub App](https://github.com/apps/kilo-code) is installed on your repository
+2. Verify your GitHub PAT is valid (if configured)
+3. Remove any environment variables that might cause issues during container init
+4. Try a container restart from town settings
+
 ## Git Authentication Failures
 
-## Review Loop Issues
+**Symptom:** Agents can't clone, push, or fetch. Errors mention "authentication failed" or "permission denied".
+
+**Common causes:**
+
+| Cause | Fix |
+|---|---|
+| GitHub App uninstalled | Reinstall at [github.com/apps/kilo-code](https://github.com/apps/kilo-code) |
+| PAT expired or revoked | Generate a new token and update in Settings → Git & Authentication |
+| Repository visibility changed | Ensure the GitHub App has access to the repo |
+| Org SSO not authorized | Authorize the token for your organization's SSO |
+
+**Diagnosis:** The Mayor may report *"git credential refresh failed: no_installation_found"* — this definitively means the GitHub App needs to be reinstalled.
+
+## Review Loop / Stuck in Review
+
+**Symptom:** A bead cycles between `in_review` and `in_progress` repeatedly, or MR beads keep failing.
+
+**Common causes:**
+- The refinery finds issues the polecat can't fix (e.g., fundamental architecture problems)
+- Missing PR URL on merge request beads
+- Convoy feature branch deleted from remote
+
+**Fix:**
+1. Check the bead's event history for review feedback
+2. If the feedback is a dead end, ask the Mayor to close the bead: *"Close bead [id] — the approach isn't working"*
+3. For stuck convoys, the Mayor can force-close: *"Force close convoy [name]"*
+
+{% callout type="info" %}
+Beads automatically escalate after 3 failed review cycles. If a bead is genuinely stuck in a loop, it will eventually fail and notify you rather than running forever.
+{% /callout %}
 
 ## The Mayor is Unresponsive
+
+**Symptom:** Messages to the Mayor don't get responses, or the Mayor says it's "unauthenticated".
+
+**Common causes:**
+- Container sleeping (wakes up after ~30 seconds)
+- KILOCODE_TOKEN expired
+- Gateway authentication failure
+
+**Fix:**
+1. Wait 30 seconds — the container may be waking from sleep
+2. If persistent: go to Settings → refresh the container token
+3. If still failing: check that your Kilo account is active and the town's billing is current
+
+## Convoy Stuck / Never Completes
+
+**Symptom:** A convoy shows open but no beads are being dispatched, or it never reaches "landed".
+
+**Common causes:**
+- Upstream dependency bead failed (blocks downstream)
+- Convoy feature branch doesn't exist on remote
+- Landing MR repeatedly failing
+
+**Fix:**
+1. Check convoy progress: which beads are closed? which are open/failed?
+2. For failed dependencies: fix or close the blocking bead, then downstream beads will dispatch
+3. Ask the Mayor: *"What's blocking convoy [name]?"*
+4. If truly stuck: force-close the convoy and re-create it
+
+## Agent Permanently Stuck
+
+**Symptom:** An agent shows as `working` but hasn't produced output for 20+ minutes.
+
+**Common causes:**
+- Container process crashed but heartbeat continues
+- Agent waiting on an external resource (network, API)
+- Infinite loop in agent execution
+
+**Fix:**
+1. Ask the Mayor: *"Reset agent [name]"*
+2. This clears the hook, resets the agent to idle, and returns the bead to `open`
+3. The reconciler will re-dispatch the bead to a fresh agent
+
+## High Failure Rate
+
+**Symptom:** Many beads ending in `failed` status.
+
+**Common causes:**
+- Task descriptions are too vague (agents can't figure out what to do)
+- The codebase has issues that prevent agents from working (broken build, missing dependencies)
+- Model quality is too low for the complexity of the work
+
+**Fix:**
+1. Review failed bead descriptions — make them more specific
+2. Ensure the repo builds cleanly (agents struggle with pre-existing broken builds)
+3. Consider upgrading the model (Sonnet → Opus for complex work)
+4. Add custom instructions to guide agents: test commands, build steps, conventions
+
+## Getting Help
+
+If you can't resolve an issue:
+
+1. **Ask the Mayor** — it can diagnose most problems
+2. **Check the event timeline** — see exactly what happened and when
+3. **Contact support** — reach out at [kilo.ai/discord](https://kilo.ai/discord) with your town ID