docs(kilo-docs): add BrowserFrame component and place all screenshots

Add BrowserFrame component that wraps images in abstract browser chrome
(traffic light dots, optional URL bar, optional caption). Register as
Markdoc tag: {% browserFrame url="..." caption="..." %}...{% /browserFrame %}

Place all 12 provided screenshots across all Gastown pages:
- gt-new-town-onboarding.png → Quick Start
- gt-new-rig.png → Quick Start
- gt-town-overview.png → Quick Start, Overview, Concepts, Mayor
- gt-rig-page-convoy-in-progress.png → Quick Start, Overview, Sling Work
- gt-rig-page-staged-convoy.png → Overview
- gt-rig-page-staged-convoy-detail.png → Overview, Sling Work
- gt-rig-page-convoy-bead-in-review.png → Sling Work, Code Review
- gt-rig-page-convoy-review-bead-detail.png → Sling Work
- gt-beads-page.png → Overview, Sling Work
- gt-beads-page-detail.png → Sling Work
- gt-merge-queue-page.png → Code Review
- gt-merge-queue-page-review-detail.png → Code Review

Remove all TODO screenshot placeholders — every page now has visuals.
This commit is contained in:
John Fawcett
2026-04-30 15:09:14 -05:00
parent 6c48186f41
commit 196a34d8bc
22 changed files with 231 additions and 117 deletions
@@ -0,0 +1,107 @@
"use client"
import React from "react"
/**
* BrowserFrame wraps content (typically an image) in an abstract browser chrome.
* Provides a minimal title bar with traffic light dots and an optional URL bar.
*/
export function BrowserFrame({
children,
url,
caption,
}: {
children: React.ReactNode
url?: string
caption?: string
}) {
return (
<figure style={{ margin: "24px 0" }}>
<div
style={{
borderRadius: "12px",
overflow: "hidden",
border: "1px solid rgba(255,255,255,0.08)",
background: "#0f0f16",
boxShadow: "0 8px 32px rgba(0,0,0,0.4)",
}}
>
{/* Title bar */}
<div
style={{
display: "flex",
alignItems: "center",
gap: "8px",
padding: "12px 16px",
background: "#1a1a24",
borderBottom: "1px solid rgba(255,255,255,0.06)",
}}
>
{/* Traffic lights */}
<div style={{ display: "flex", gap: "6px" }}>
<div
style={{
width: "10px",
height: "10px",
borderRadius: "50%",
background: "#ff5f57",
}}
/>
<div
style={{
width: "10px",
height: "10px",
borderRadius: "50%",
background: "#febc2e",
}}
/>
<div
style={{
width: "10px",
height: "10px",
borderRadius: "50%",
background: "#28c840",
}}
/>
</div>
{/* URL bar */}
{url && (
<div
style={{
flex: 1,
marginLeft: "12px",
padding: "4px 12px",
borderRadius: "6px",
background: "rgba(255,255,255,0.04)",
border: "1px solid rgba(255,255,255,0.06)",
fontSize: "11px",
fontFamily: "'JetBrains Mono', monospace",
color: "rgba(255,255,255,0.4)",
overflow: "hidden",
textOverflow: "ellipsis",
whiteSpace: "nowrap",
}}
>
{url}
</div>
)}
</div>
{/* Content */}
<div style={{ lineHeight: 0 }}>{children}</div>
</div>
{caption && (
<figcaption
style={{
textAlign: "center",
fontSize: "13px",
color: "var(--text-muted, #888)",
marginTop: "8px",
fontStyle: "italic",
}}
>
{caption}
</figcaption>
)}
</figure>
)
}
+1
View File
@@ -17,3 +17,4 @@ export * from "./TopNav"
export * from "./VideoEmbed"
export * from "./YouTube"
export * from "./FlowDiagram"
export * from "./BrowserFrame"
@@ -0,0 +1,16 @@
import { BrowserFrame } from "../../components"
export const browserFrame = {
render: BrowserFrame,
children: ["paragraph", "tag", "list"],
attributes: {
url: {
type: String,
description: "Optional URL to display in the address bar",
},
caption: {
type: String,
description: "Optional caption below the frame",
},
},
}
+1
View File
@@ -8,3 +8,4 @@ export * from "./kilo-code-icon.markdoc"
export * from "./video.markdoc"
export * from "./youtube.markdoc"
export * from "./flow-diagram.markdoc"
export * from "./browser-frame.markdoc"
@@ -11,20 +11,11 @@ Every piece of code produced by Gas Town agents goes through automated review be
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"
-->
{% flowDiagram name="adversarial-loop" height="340px" /%}
{% browserFrame url="app.kilo.ai/gastown/town/rigs/main" caption="A bead in review — the refinery is evaluating the polecat's work" %}
{% image src="/docs/img/gastown/gt-rig-page-convoy-bead-in-review.png" alt="Gas Town rig page showing a bead in review status" /%}
{% /browserFrame %}
The refinery evaluates:
- **Correctness** — does the code do what the task asked?
@@ -82,23 +73,11 @@ You can configure whether PRs auto-merge after refinery approval or require huma
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"
-->
{% flowDiagram name="convoy-execution" height="200px" /%}
{% browserFrame url="app.kilo.ai/gastown/town/merges" caption="The merge queue — review detail showing refinery feedback" %}
{% image src="/docs/img/gastown/gt-merge-queue-page-review-detail.png" alt="Gas Town merge queue with review detail" /%}
{% /browserFrame %}
| Review Layer | What's checked | Who reviews |
|---|---|---|
@@ -116,6 +95,14 @@ Gas Town's refinery works independently, but combining it with [Kilo Code Review
This gives you automated adversarial review for speed **plus** AI-assisted human review for judgment — the best of both approaches.
## The Merge Queue
The merge queue page shows all active and completed reviews in your town:
{% browserFrame url="app.kilo.ai/gastown/town/merges" caption="The merge queue — all reviews at a glance" %}
{% image src="/docs/img/gastown/gt-merge-queue-page.png" alt="Gas Town merge queue page" /%}
{% /browserFrame %}
## Review Configuration
Customize the refinery's behavior in **Town Settings** → **Review**:
@@ -128,17 +128,7 @@ You don't interact with the reconciler directly — it's the autonomous engine t
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"
-->
{% flowDiagram name="adversarial-loop" height="340px" /%}
This pattern compounds when combined with **convoys**:
@@ -151,17 +141,9 @@ At every stage, work is critiqued and refined. Combined with Kilo's [Code Review
## 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"
-->
{% browserFrame url="app.kilo.ai/gastown/town" caption="The complete Gas Town experience — Mayor chat, convoy progress, and agent coordination" %}
{% image src="/docs/img/gastown/gt-town-overview.png" alt="Gas Town overview showing the full architecture in action" /%}
{% /browserFrame %}
| Component | Responsibility |
|---|---|
@@ -9,7 +9,9 @@ Gastown by Kilo is an autonomous agent orchestration platform that manages teams
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.
<!-- TODO: Screenshot — town overview page showing active agents, beads in progress, and a recent merge -->
{% browserFrame url="app.kilo.ai/gastown/town" caption="A Gas Town with active agents, convoy progress, and Mayor chat" %}
{% image src="/docs/img/gastown/gt-town-overview.png" alt="Gas Town overview showing active work and Mayor chat" /%}
{% /browserFrame %}
## What Makes Gastown Different
@@ -23,7 +25,9 @@ Unlike single-agent coding tools that handle one task at a time, Gastown orchest
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 -->
{% browserFrame url="app.kilo.ai/gastown/town/rigs/main" caption="A staged convoy ready to be kicked off" %}
{% image src="/docs/img/gastown/gt-rig-page-staged-convoy.png" alt="Gas Town rig page with a staged convoy" /%}
{% /browserFrame %}
## How It Works
@@ -35,7 +39,9 @@ Connect a GitHub repository to a new town. Gastown provisions a dedicated enviro
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 -->
{% browserFrame url="app.kilo.ai/gastown/town/rigs/main" caption="Agents working on a convoy — beads flowing through the pipeline" %}
{% image src="/docs/img/gastown/gt-rig-page-convoy-in-progress.png" alt="Gas Town rig page with convoy in progress" /%}
{% /browserFrame %}
### 3. Agents pick it up
@@ -49,7 +55,9 @@ Completed work flows to the refinery for automated code review. Depending on you
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 -->
{% browserFrame url="app.kilo.ai/gastown/town/beads" caption="The beads page — all work items with status, type, and history" %}
{% image src="/docs/img/gastown/gt-beads-page.png" alt="Gas Town beads page showing beads in various states" /%}
{% /browserFrame %}
## Core Concepts
@@ -79,7 +87,9 @@ You can ask the mayor to:
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 -->
{% browserFrame url="app.kilo.ai/gastown/town/rigs/main" caption="Staged convoy detail — review the plan before agents start" %}
{% image src="/docs/img/gastown/gt-rig-page-staged-convoy-detail.png" alt="Gas Town staged convoy detail view" /%}
{% /browserFrame %}
## What You Can Build With Gastown
@@ -19,7 +19,9 @@ The Mayor operates as a technical lead that:
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 -->
{% browserFrame url="app.kilo.ai/gastown/town" caption="The Mayor chat — always available for coordination and questions" %}
{% image src="/docs/img/gastown/gt-town-overview.png" alt="Gas Town Mayor chat interface" /%}
{% /browserFrame %}
## Talking to the Mayor
@@ -15,9 +15,11 @@ This guide walks you through creating your first town, connecting a repository,
## 1. Create a Town
From the Kilo dashboard, click **New Town**. Give it a name — this is just for your reference.
When you first visit Gas Town with no existing towns, you'll be taken directly into the new town onboarding flow. Give your town a name — this is just for your reference.
<!-- TODO: Screenshot — "New Town" button and creation dialog -->
{% browserFrame url="app.kilo.ai/gastown" caption="The new town onboarding flow" %}
{% image src="/docs/img/gastown/gt-new-town-onboarding.png" alt="Gas Town new town onboarding flow" /%}
{% /browserFrame %}
## 2. Connect a Repository
@@ -30,7 +32,9 @@ Add a **rig** to your town. A rig is a connection to a specific repository.
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 -->
{% browserFrame url="app.kilo.ai/gastown/town/rigs/new" caption="Adding a new rig — connect your repository" %}
{% image src="/docs/img/gastown/gt-new-rig.png" alt="Gas Town new rig creation flow" /%}
{% /browserFrame %}
## 3. Add a GitHub Personal Access Token
@@ -46,26 +50,26 @@ Without a PAT, agents use the GitHub App installation token — functional but s
## 4. Sling Your First Task
Now let's give the agents something to do:
Now let's give the agents something to do. The easiest way is to ask the Mayor:
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**
> *"Add a CONTRIBUTING.md file with basic setup instructions"*
<!-- TODO: Screenshot — Sling Work dialog with a sample task -->
Or use the **Sling Work** action in the town header to describe the task directly.
## 5. Watch Agents Work
The reconciler assigns your task to an available polecat agent. You'll see:
The reconciler assigns your task to an available polecat agent. Head to the **rig page** to watch it in action:
1. A **bead** appear in the beads list with status `open`
2. The bead transitions to `in_progress` as a polecat picks it up
1. A **bead** appears in the kanban board's open column
2. It moves 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`
6. The bead lands in the `closed` column
<!-- TODO: Screenshot — bead lifecycle showing the transitions in real-time -->
{% browserFrame url="app.kilo.ai/gastown/town/rigs/main" caption="The rig page — convoy tracker and kanban board showing beads in various states" %}
{% image src="/docs/img/gastown/gt-rig-page-convoy-in-progress.png" alt="Gas Town rig page with an active convoy and beads in progress" /%}
{% /browserFrame %}
The whole cycle typically takes 2-10 minutes depending on complexity and the model you're using.
@@ -79,7 +83,9 @@ Click the **Mayor** chat to interact with your town's coordinator. Try:
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 -->
{% browserFrame url="app.kilo.ai/gastown/town" caption="The Mayor — your conversational interface to the town" %}
{% image src="/docs/img/gastown/gt-town-overview.png" alt="Gas Town overview with Mayor chat" /%}
{% /browserFrame %}
## What's Next?
@@ -9,15 +9,13 @@ description: "Creating tasks and convoys for agents to work on"
## Single Tasks
The simplest way to use Gas Town — describe what needs to be done, and an agent picks it up:
The simplest way to use Gas Town — describe what needs to be done, and an agent picks it up.
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**
Ask the Mayor:
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.
> *"Fix the 404 error on the /settings page — the route is missing from the router config"*
<!-- TODO: Screenshot — Sling Work dialog with a single task -->
Or use the **Sling Work** action in the town header. Either way, 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.
### Writing Good Task Descriptions
@@ -48,54 +46,26 @@ Single-pass agent output has a quality ceiling. The longer an agent works on one
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"
-->
{% flowDiagram name="convoy-execution" height="200px" /%}
### 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 -->
{% browserFrame url="app.kilo.ai/gastown/town/rigs/main" caption="A staged convoy — review the task breakdown before agents begin" %}
{% image src="/docs/img/gastown/gt-rig-page-staged-convoy-detail.png" alt="Gas Town staged convoy detail showing task dependencies" /%}
{% /browserFrame %}
### 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"
-->
{% browserFrame url="app.kilo.ai/gastown/town/rigs/main" caption="Convoy in progress — review bead detail showing the refinery at work" %}
{% image src="/docs/img/gastown/gt-rig-page-convoy-review-bead-detail.png" alt="Gas Town convoy review bead detail" /%}
{% /browserFrame %}
Key behaviors:
- Each polecat starts from the **convoy feature branch**, which accumulates all previously merged work
@@ -135,14 +105,46 @@ Higher priority beads are dispatched first when multiple beads are waiting for a
## Watching Progress
### Rig Page — Convoy Tracker
The best place to observe your town in action is the **rig page**. At the top, active convoys show their progress as a visual tracker — each bead in the convoy displayed with its current status and dependency relationships. You can see exactly where in the DAG execution has reached and which beads are blocking downstream work.
{% browserFrame url="app.kilo.ai/gastown/town/rigs/main" caption="Convoy tracker — see exactly where execution has reached" %}
{% image src="/docs/img/gastown/gt-rig-page-convoy-in-progress.png" alt="Gas Town rig page convoy tracker with beads in various states" /%}
{% /browserFrame %}
### Rig Page — Kanban Board
Below the convoy tracker, a kanban board shows beads organized by status — open, in progress, in review, and closed — updating in real-time as agents move work through the pipeline.
{% browserFrame url="app.kilo.ai/gastown/town/rigs/main" caption="Kanban board — beads flow through columns as agents work" %}
{% image src="/docs/img/gastown/gt-rig-page-convoy-bead-in-review.png" alt="Gas Town rig page kanban board with a bead in review" /%}
{% /browserFrame %}
You can see at a glance:
- What's queued up (open column)
- What agents are actively working on (in progress)
- What's awaiting review (in review)
- What's shipped (closed)
Beads move through columns autonomously as the reconciler dispatches agents and work progresses.
### Beads Page
The beads list shows all work in your town with real-time status updates. Filter by:
For a more detailed, filterable view across all rigs, the beads page shows every bead in your town. 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 -->
{% browserFrame url="app.kilo.ai/gastown/town/beads" caption="Beads page — filterable list of all work items" %}
{% image src="/docs/img/gastown/gt-beads-page.png" alt="Gas Town beads page" /%}
{% /browserFrame %}
Click any bead to see its full detail — description, event history, agent activity, and review feedback:
{% browserFrame url="app.kilo.ai/gastown/town/beads/detail" caption="Bead detail — full history and status" %}
{% image src="/docs/img/gastown/gt-beads-page-detail.png" alt="Gas Town bead detail view" /%}
{% /browserFrame %}
### Town Overview
@@ -153,4 +155,4 @@ The town overview shows a high-level summary:
### 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.
The event timeline shows every state transition as it happens — bead dispatched, review submitted, merge completed. Useful for understanding the flow when you want to see exactly what's happening under the hood.
Binary file not shown.

After

Width:  |  Height:  |  Size: 784 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 625 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 611 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 571 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 347 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 322 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 675 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 687 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 609 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 571 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 650 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 652 KiB