diff --git a/packages/kilo-docs/components/BrowserFrame/index.tsx b/packages/kilo-docs/components/BrowserFrame/index.tsx new file mode 100644 index 00000000000..bc96def1cf3 --- /dev/null +++ b/packages/kilo-docs/components/BrowserFrame/index.tsx @@ -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 ( +
+
+ {/* Title bar */} +
+ {/* Traffic lights */} +
+
+
+
+
+ {/* URL bar */} + {url && ( +
+ {url} +
+ )} +
+ {/* Content */} +
{children}
+
+ {caption && ( +
+ {caption} +
+ )} +
+ ) +} diff --git a/packages/kilo-docs/components/index.js b/packages/kilo-docs/components/index.js index 40ff1e95f43..96e12f01af8 100644 --- a/packages/kilo-docs/components/index.js +++ b/packages/kilo-docs/components/index.js @@ -17,3 +17,4 @@ export * from "./TopNav" export * from "./VideoEmbed" export * from "./YouTube" export * from "./FlowDiagram" +export * from "./BrowserFrame" diff --git a/packages/kilo-docs/markdoc/tags/browser-frame.markdoc.ts b/packages/kilo-docs/markdoc/tags/browser-frame.markdoc.ts new file mode 100644 index 00000000000..eec24ead458 --- /dev/null +++ b/packages/kilo-docs/markdoc/tags/browser-frame.markdoc.ts @@ -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", + }, + }, +} diff --git a/packages/kilo-docs/markdoc/tags/index.ts b/packages/kilo-docs/markdoc/tags/index.ts index 3fa56d079b0..e158a64b895 100644 --- a/packages/kilo-docs/markdoc/tags/index.ts +++ b/packages/kilo-docs/markdoc/tags/index.ts @@ -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" 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 8c4fbd1564d..cc4d312190d 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 @@ -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: - +{% 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: - +{% 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**: 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 00ad5e3ffdd..b5a9fad5626 100644 --- a/packages/kilo-docs/pages/code-with-ai/gastown/concepts.md +++ b/packages/kilo-docs/pages/code-with-ai/gastown/concepts.md @@ -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: - +{% 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 - +{% 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 | |---|---| 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 0dae8954a8e..fdc190713c4 100644 --- a/packages/kilo-docs/pages/code-with-ai/gastown/index.md +++ b/packages/kilo-docs/pages/code-with-ai/gastown/index.md @@ -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. - +{% 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. - +{% 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). - +{% 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. - +{% 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. - +{% 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 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 1092eb7d93c..739c4a30bed 100644 --- a/packages/kilo-docs/pages/code-with-ai/gastown/mayor.md +++ b/packages/kilo-docs/pages/code-with-ai/gastown/mayor.md @@ -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. - +{% 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 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 c194cdc1ef7..5ef48909913 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 @@ -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. - +{% 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. - +{% 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"* - +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 - +{% 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. - +{% 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? 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 f481421395a..53c7086877f 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 @@ -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"* - +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 - +{% 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. - +{% 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: - +{% 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) - +{% 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. diff --git a/packages/kilo-docs/public/img/gastown/gt-beads-page-detail.png b/packages/kilo-docs/public/img/gastown/gt-beads-page-detail.png new file mode 100644 index 00000000000..01722c3f1fe Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-beads-page-detail.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-beads-page.png b/packages/kilo-docs/public/img/gastown/gt-beads-page.png new file mode 100644 index 00000000000..baed8ac1a15 Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-beads-page.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-merge-queue-page-review-detail.png b/packages/kilo-docs/public/img/gastown/gt-merge-queue-page-review-detail.png new file mode 100644 index 00000000000..349af417c87 Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-merge-queue-page-review-detail.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-merge-queue-page.png b/packages/kilo-docs/public/img/gastown/gt-merge-queue-page.png new file mode 100644 index 00000000000..368f8ac3255 Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-merge-queue-page.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-new-rig.png b/packages/kilo-docs/public/img/gastown/gt-new-rig.png new file mode 100644 index 00000000000..7cb3444e535 Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-new-rig.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-new-town-onboarding.png b/packages/kilo-docs/public/img/gastown/gt-new-town-onboarding.png new file mode 100644 index 00000000000..d1a3e6ac8f2 Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-new-town-onboarding.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-rig-page-convoy-bead-in-review.png b/packages/kilo-docs/public/img/gastown/gt-rig-page-convoy-bead-in-review.png new file mode 100644 index 00000000000..210e5aaa674 Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-rig-page-convoy-bead-in-review.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-rig-page-convoy-in-progress.png b/packages/kilo-docs/public/img/gastown/gt-rig-page-convoy-in-progress.png new file mode 100644 index 00000000000..8880690dc1e Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-rig-page-convoy-in-progress.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-rig-page-convoy-review-bead-detail.png b/packages/kilo-docs/public/img/gastown/gt-rig-page-convoy-review-bead-detail.png new file mode 100644 index 00000000000..43dae48328f Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-rig-page-convoy-review-bead-detail.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-rig-page-staged-convoy-detail.png b/packages/kilo-docs/public/img/gastown/gt-rig-page-staged-convoy-detail.png new file mode 100644 index 00000000000..ec185145d02 Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-rig-page-staged-convoy-detail.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-rig-page-staged-convoy.png b/packages/kilo-docs/public/img/gastown/gt-rig-page-staged-convoy.png new file mode 100644 index 00000000000..fdb9f9251fe Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-rig-page-staged-convoy.png differ diff --git a/packages/kilo-docs/public/img/gastown/gt-town-overview.png b/packages/kilo-docs/public/img/gastown/gt-town-overview.png new file mode 100644 index 00000000000..12306817e5a Binary files /dev/null and b/packages/kilo-docs/public/img/gastown/gt-town-overview.png differ