Description
Setup Assistant is the guided first-run journey for buyer deployments. Before authentication it can collect the bundled-versus-self-hosted backend choice and apply the selected endpoint. After sign-in it walks through license activation, workspace provisioning, coding-agent detection, IAGREED installation, concierge progress, and three reveal moments that show dashboard, edge, and repository-graph value using the buyer’s live environment.
The flow is fixed-order and durable. Each step validates whether the user can continue, writes its own answers slice, and records completion only near the end so a restart returns to unfinished work. Desktop and browser-capable buyer builds share the same wizard contract while reading status through different bridges. Deployments where onboarding does not apply skip the state request entirely and render the normal app.
Selling Points
- Converts a multi-system technical setup into a guided product experience a non-developer can complete.
- Persists progress outside transient renderer state, so restarts and installation steps do not force the buyer back to the beginning.
- Detects installed coding agents and offers the appropriate path instead of assuming one universal environment.
- Demonstrates value with live dashboard, edge, and repo-graph reveals rather than ending on a generic success screen.
- Degrades optional instrumentation and agent progress without blocking the core setup journey.
User Story
A first-time desktop buyer selects the bundled backend, signs in, activates a license, chooses a workspace folder, and lets the assistant detect their coding agent. They install IAGREED, watch the concierge progress, and finish by seeing their own repository represented in Dots. The application then opens to a usable Home rather than an unfinished configuration screen.
Extension Surface
The flow is configurable through captured backend, workspace, agent, and installation choices, but its required step order is product-owned. apps/web/src/modules/onboarding/steps.ts is the in-repo registry of steps and completion handlers, while apps/web/src/modules/onboarding/SetupWizard.tsx drives the shared sequence. There is no external step-plugin interface, so configurable is the highest supported rating.
Capabilities & Limits
- Handles pre-session backend selection and post-session buyer onboarding.
- Persists step answers, supports restart recovery, and streams concierge progress.
- Resolves live reveal actions for dashboards, knowledge edges, and repo ingestion.
- Limit: the assistant applies only to deployment shapes explicitly marked for onboarding; hosted sessions and already-complete buyers bypass it.
Implementation Map
apps/web/src/modules/onboarding/BackendSelectionGate.tsxapps/web/src/modules/onboarding/SetupWizard.tsxapps/web/src/modules/onboarding/steps.tsapps/web/src/modules/onboarding/reveals/reveal-actions.ts