docs(kilo-docs): scaffold Gastown documentation section#9754
Open
docs(kilo-docs): scaffold Gastown documentation section#9754
Conversation
Add initial page structure for /code-with-ai/gastown/ with overview, quick-start, concepts, mayor, sling-work, code-review, settings, and troubleshooting pages. Register the section in the sidebar nav config.
Flesh out all 7 sub-pages with comprehensive content: - Quick Start: town creation, PAT setup, first task flow - Concepts: towns, beads, convoys, rigs, agents, micro-adversarial loops - The Mayor: capabilities, tools, communication tips - Sling Work: single tasks, convoys, staged convoys, DAG execution - Code Review: refinery pipeline, adversarial loops, merge strategies - Settings: models, GitHub PAT, merge strategy, env vars, custom instructions - Troubleshooting: common failure modes and fixes Includes React Flow diagram placeholders (TODO comments) describing what each interactive diagram should visualize. Also moves Gastown nav link under Platforms section with sub-links and updates page title to 'Gas Town by Kilo'.
Integrate @xyflow/react for interactive architecture diagrams:
- FlowDiagram component with lazy loading (dynamic import)
- Markdoc tag: {% flowDiagram name="..." height="..." /%}
- Three initial diagrams: bead-lifecycle, adversarial-loop, convoy-execution
- Diagrams registry pattern for easy addition of new diagrams
- Replace TODO placeholders in concepts and code-review pages
The diagrams visualize the bead lifecycle state machine, the
micro-adversarial write/review/revise loop, and convoy DAG execution.
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.
Contributor
Author
Screenshots of the docs pagesScreenshots showing how the documentation renders with the BrowserFrame component and React Flow diagrams: |
- Add preventScrolling={false} and panOnScroll={false} to ReactFlow
so mouse wheel events pass through to the page instead of being
captured by the diagram
- Set explicit sourcePosition/targetPosition on all nodes so edges
connect from right→left for the main horizontal flow
- Use bottom→top routing for failure/rejection transitions so lines
don't overlap nodes
- Reposition 'failed' node and adjust spacing for cleaner layout
Main flow edges (open→in_progress→in_review→closed) now exit and enter from the top of each node, arcing above. Failed/rejected transitions exit from bottom of source to top of target, dropping below.
… error) Edge objects in React Flow don't have sourcePosition/targetPosition — those properties only exist on Node. Remove them from all edge definitions in bead-lifecycle, adversarial-loop, and convoy-execution diagrams. The smoothstep edge type handles routing based on the node positions instead.
Replace the abbreviated 6-tool table with the complete list of all 21 gt_* tools grouped by category: Work Creation, Convoy Management, Bead Management, Agent Management, and Town & UI.
… models Replace Claude Opus/Sonnet/Auto Free recommendations with Kilo Auto Frontier (recommended) and Kilo Auto Balanced (minimum). Remove the per-role model recommendation table since Auto handles routing.
The docs site is served under kilo.ai/docs so all internal links need the /docs prefix to avoid 404s.
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
Contributor
Code Review SummaryStatus: No Issues Found | Recommendation: Merge Files Reviewed (3 files)
Reviewed by gpt-5.5-2026-04-23 · 380,213 tokens |
- Move diagram caption outside the overflow:hidden container so it's no longer clipped by the fixed-height wrapper - Recommend fine-grained PATs scoped to the connected repository instead of classic repo-scope tokens (quick-start.md + settings.md) - Add callout noting agents act on the user's behalf, so limiting token scope is a best practice
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Scaffolds and fully writes the Gas Town by Kilo documentation section at
/code-with-ai/gastown/. Includes 8 pages of content, interactive React Flow diagrams, a BrowserFrame component for screenshot presentation, and all screenshots placed.Pages
Technical Additions
FlowDiagramcomponent — lazily loads@xyflow/reactvia dynamic import. Markdoc tag:{% flowDiagram name="..." height="..." /%}components/FlowDiagram/diagrams/) — 3 diagrams:bead-lifecycle,adversarial-loop,convoy-executionBrowserFramecomponent — wraps screenshots in abstract browser chrome (traffic lights, URL bar). Markdoc tag:{% browserFrame url="..." caption="..." %}...{% /browserFrame %}