[Gastown] Onboarding Flow — Zero to Agent in Under 2 Minutes

[jrf0110]

Parent: #204 | Phase 4

Revised (Feb 2026): Redesigned around the chat-first product vision. Target: user goes from sign-in to watching an agent write code in under 2 minutes.

Goal

A user with zero Gastown knowledge should go from sign-in to watching an agent write code in under 2 minutes.

"Create Your First Town" Wizard

Step 1: Name your town

Single text input with sensible default (e.g., user's name + "-town"). One click.

Step 2: Connect a repo

• If GitHub App already installed: show repo picker (existing PlatformRepository search)
• If not: "Install GitHub App" button → OAuth flow → return to picker
• GitLab path identical
• Manual git URL as escape hatch

Step 3: Choose your model configuration

A preset selector with cards — not a raw model picker. Each preset is a curated combination of per-role models (mayor, refinery, polecat) that suits a different use case. The presets should favor Kilo auto-models (kilo/frontier, kilo/balanced, kilo/free) since they route to the best available model automatically.

Presets

Preset	Mayor	Refinery	Polecat	Description
Maximum Frontier	kilo/frontier	kilo/frontier	kilo/frontier	Best quality across the board. Highest cost.
Balanced (default)	kilo/balanced	kilo/frontier	kilo/balanced	Smart default — frontier model for code review where quality matters most, balanced for everything else.
Cost-Effective	kilo/balanced	kilo/balanced	kilo/balanced	Good results at lower cost. Suitable for high-volume work.
Free Tier	kilo/free	kilo/free	kilo/free	For trying Gastown without spending credits. Quality trade-offs.
Custom	(picker)	(picker)	(picker)	Advanced: choose specific models per role.

Note: Exact preset compositions are TBD and will likely evolve as model capabilities change. Anthropic models (Claude Opus, Sonnet) generally work best for Gastown agents. The kilo/frontier and kilo/balanced auto-models already favor Anthropic by default.

UI treatment:

• Cards laid out horizontally (or 2x2 grid on mobile)
• Each card shows: preset name, one-line description, estimated cost indicator ($ / $$ / $$$ / free)
• Default selection: Balanced
• "Custom" card expands to show three per-role model dropdowns (same component from feat(gastown): Replace default model text input with model selector dropdown in town settings #1430 / feat(gastown): Per-role model configuration in town settings — mayor, refinery, polecat #1512)
• Selecting a preset sets townConfig.default_model and townConfig.role_models accordingly
• Users can change this later in Settings → Agent Defaults

Data flow:

• Presets map directly to the role_models config from feat(gastown): Per-role model configuration in town settings — mayor, refinery, polecat #1512:

  // "Balanced" preset
  { default_model: "kilo/balanced", role_models: { refinery: "kilo/frontier" } }
  
  // "Maximum Frontier" preset
  { default_model: "kilo/frontier" }  // no overrides needed, all roles use default

• The wizard writes the config on town creation — no separate migration

Step 4: First task

Pre-populated prompt: "Describe something you'd like done in this repo."
Large textarea, feels like the start of a conversation. Submit says "Tell the Mayor".

Step 5: Watch it work

Redirect to town home. Mayor chat shows message being processed. Activity feed lighting up: agent spawning, bead created, work starting. The "aha moment" — the machine comes alive.

Progressive Feature Discovery

After the first task completes:

• Tooltip on convoy: "This tracked your task. Create convoys to batch related work."
• Tooltip on agent card: "This polecat worked on your task. Click to see its full conversation."
• Tooltip on merge queue: "Your code changes are reviewed here before merging."
• Prompt in Mayor chat: "You can also ask me to work on multiple things at once, check on progress, or coordinate across repos."

Dependencies

• [Gastown] Dashboard UI Overhaul — Town Home, Mayor Chat, Rig Workbench #346 (Dashboard UI Overhaul)
• [Gastown] PR 8.5: Mayor Tools — Cross-Rig Delegation (P0 — #1 Priority) #339 (Mayor Tools)
• [Gastown] Agent Streaming Endpoint — Container WebSocket/SSE for Live Agent Observation #343 (Agent Streaming)
• feat(gastown): Per-role model configuration in town settings — mayor, refinery, polecat #1512 (Per-role model configuration — provides the role_models config the presets write to)
• feat(gastown): Replace default model text input with model selector dropdown in town settings #1430 (Model selector dropdown — used in the "Custom" preset's per-role pickers)
• feat(gastown): GitHub OAuth Device Flow for user-scoped git identity and attribution #1350 (GitHub OAuth Device Flow — alternative to GitHub App for repo connection)
• Existing GitHub/GitLab integration infrastructure

Random notes

• If a user wants to get rid of the intro tooltips altogether, they should be able to click something like "stop showing me these"
• The model preset selection should feel lightweight — not a wall of options. Most users should pick Balanced and move on in <5 seconds.
• Custom model selection is an advanced escape hatch, not the primary path.

Acceptance Criteria

• Multi-step wizard (name → repo → model preset → task → watch)
• Repo connection via existing GitHub/GitLab integrations
• Model preset selector with at least 4 presets + Custom option
• Default preset is Balanced
• Custom preset shows per-role model dropdowns (mayor, refinery, polecat)
• Selected preset writes to townConfig.default_model and townConfig.role_models
• First message routes through Mayor
• Auto-redirect to town home after submission
• Progressive tooltips on first task completion
• Under 2 minutes from sign-in to agent running (timed)

References

• feat(gastown): Per-role model configuration in town settings — mayor, refinery, polecat #1512 — Per-role model configuration
• feat(gastown): Replace default model text input with model selector dropdown in town settings #1430 — Model selector dropdown component
• feat(gastown): GitHub OAuth Device Flow for user-scoped git identity and attribution #1350 — GitHub OAuth Device Flow