feat(gastown): Redesign onboarding — seeded working town, mayor-guided setup, user-assigned beads

[jrf0110]

Summary

The current guided onboarding flow doesn't give users the "ah-ha" moment — they have to commit to setup before they can see what Gastown actually is. We need a path that drops users directly into a working town so the system explains itself through its own objects.

Onboarding Paths

Users should be able to choose between:

1. Existing guided onboarding — step-by-step repo connection, settings, etc.
2. Blank town — skip onboarding, start from scratch
3. Working town (NEW) — pre-seeded town with history, staged work, and onboarding beads

The "Working Town" Experience

Seeded Town Contents

A pre-configured town connected to a Kilo-owned sample repo (e.g. Kilo-Org/gastown-sample-project), pre-loaded with:

Object	Purpose
1 closed bead ("Create a town")	Shows what completion looks like. Description includes welcome/onboarding material explaining what beads are.
1 staged convoy	Simple work (e.g., "Add deployment docs to README"). User can un-stage and watch agents work immediately. Shows what planned orchestrated work looks like.
User-assigned onboarding beads (open)	"Review your town settings", "Start a conversation with the mayor", "Un-stage the convoy and watch agents work", etc. These teach by doing.
Mayor	Ready to chat, greets the user contextually

Configuration

• Model: Kilo Auto Free — zero friction, no API key needed
• GitHub App pre-installed on the sample repo
• Merge strategy and refinery configured with sensible defaults

Mayor-Guided Experience

When the user first opens the mayor chat, the mayor greets them:

"Welcome! I'm the Mayor — I coordinate the agents that work on your code. Want me to help you get set up? I can walk you through how things work, update settings based on your preferences, or you can just explore on your own."

The mayor can run a lightweight questionnaire:

• What kind of projects do you work on?
• How aggressive should code review be?
• Do you prefer PRs or direct merges?

Based on answers, the mayor updates town settings and explains what it changed. The user learns settings through conversation rather than forms.

Bail-out

• Persistent but unobtrusive "onboarding mode" indicator (banner or badge)
• "Exit onboarding" action that: closes/hides remaining onboarding beads, tells the mayor to stop guided flow, removes onboarding UI chrome
• User can always dismiss the mayor's guidance ("I'll figure it out")

New Feature: User-Assigned Beads

Beads that are assigned to the human operator rather than dispatched to an agent. The reconciler skips these for agent dispatch.

Requirements

• assigned_to_user: boolean or assignee_type: 'user' | 'agent' field on beads
• Reconciler ignores user-assigned beads in dispatch rules
• Visual distinction in the UI (different icon, badge, or section)
• Simple "Mark done" button (not gt_done — just a status transition to closed)
• Mayor can create user-assigned beads (for onboarding or general coordination)

Beyond Onboarding

User-assigned beads are useful generally:

• Manual approval gates in convoys
• Beads requiring human judgment/decision
• Team leads assigning themselves review tasks
• "Human-in-the-loop" checkpoints

Implementation Considerations

Seeded Town Creation

• Could use the Fork Town feature (feat(gastown): Fork Town — create a new town from an existing town's settings and bead history #2368) — maintain a "template town" and fork it for each new user
• Or: a dedicated seedOnboardingTown() function that creates the town + inserts pre-defined beads/convoys directly
• The fork approach is cleaner if the template evolves over time

Sample Repo

• Kilo-owned public repo with simple, readable code
• GitHub App pre-installed (Kilo org controls both sides)
• Small enough that agents complete work quickly (immediate gratification)

Open Questions

• When the user is ready for their real repo, do they add a rig to the onboarding town or create a new town? (Probably add a rig — keeps their learned context and settings)
• Should the sample repo beads be deletable/archivable once the user moves to real work?
• How do we convey that the system is autonomous? Maybe the staged convoy auto-un-stages after a timer if the user doesn't act? Or the mayor proactively offers to kick it off?

Related

• feat(gastown): Fork Town — create a new town from an existing town's settings and bead history #2368 — Fork Town (could be used to create onboarding towns from a template)
• feat(gastown): Simplify Sling Work button — demote to secondary action, remove model selector, add Mayor prompt #1445 — Simplify Sling Work button
• feat(gastown): Custom per-role prompt instructions in town settings #1794 — Custom per-role prompt instructions (mayor onboarding personality)