[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: 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 4: Watch it work

Redirect to town home. Mayor chat shows message being processed. Right pane shows 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)
• Existing GitHub/GitLab integration infrastructure

Acceptance Criteria

• Multi-step wizard (name → repo → task → watch)
• Repo connection via existing GitHub/GitLab integrations
• 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)