Get Started – Stepper (3 steps)

Route

Path: /get-started
Parent: README.md
Children:
- step-1-select-channels.md
- step-2-connect-channels.md
- step-3-train-conversioniq-ai.md

Historical design reference

These Figma links are kept for legacy context only. If they differ from the onboarding docs or the shipped overlay, follow the docs and current implementation.

Purpose (business goal)

Drive activation by guiding workspace admins through initial setup: selecting channels, connecting channels, and training ConversionIQ with a knowledge base.

User roles & permissions

Primary role: Workspace Admin
Permissions: channels.connect, kb.edit, workspace.manage (TBD exact tokens)

Reference: Roles & Permissions Model

Layout structure

Fullscreen overlay container
- Covers the application shell while onboarding is in progress (TBD exact layering/animation)
- Top-right controls:
  - Persistent hide toggle: Don't show Get Started automatically — see §Persistent hide toggle below
  - Optional pill action: Chatti Live (opens an assistant panel within the overlay)
  - Close icon: exits onboarding overlay
Step header (horizontal stepper)
- Each step shows a number badge + label (e.g., 1 Select channels)
- Steps are connected with a line; active step is visually emphasized (UI-level styling)
- Interactive step badges (clickable navigation controls within the stepper)
Step content region
Footer actions (Back/Next/Finish)
- Step 1 shows a primary Next CTA (Back may be absent on step 1; TBD)
Validation banner/toast area
Optional right-side assistant panel (when Chatti Live is opened from the overlay)
- Docked panel titled Chatti Live with message feed and input box (assistant behavior is UI-level; governance/security applies)

Persistent hide toggle

A toggle switch in the onboarding overlay header allows the user to suppress Get Started permanently (without completing it).

Property	Value
Label	`Don't show Get Started automatically`
Component	`Switch` with adjacent label text
Position	Left side of the top bar, before Chatti Live pill and close icon
Default state	Off (unchecked)

Behavior when toggled ON:

Show a confirmation sonner with explicit Cancel and Confirm actions before mutating any onboarding state.
The confirmation copy must clearly explain that Get Started will stop opening automatically and can be restored later from Chatti Live.
Only when the user clicks Confirm, mutate SetupStatus.persistentlyHidden = true via { type: "set-persistent-hide"; hidden: true }.
If the user clicks Cancel or dismisses the sonner, no onboarding visibility state changes are applied and the switch remains off.
The overlay remains open for the current interaction (the toggle does not dismiss).
On next authenticated entry, the overlay does not auto-open.
The Get started navigation item is removed from the left nav.

Restore path:

Only Chatti Live (assistant sidebar) can restore the hidden flow by sending { type: "set-persistent-hide"; hidden: false }.
Restoring clears persistentlyHidden, re-shows the nav item, and allows the overlay to auto-open on next entry.

Components used

Channel Selector: Component: Channel Selector
Knowledge Base Mapping: Component: Knowledge Base Mapping (step 3)

States

Empty: first-time workspace with no channels/KBs configured
Loading: fetching workspace config + available connectors
Error: connector provider unavailable; permissions denied
Complete: workspace is activated (channels connected + KB ready)

Business logic (high-level)

Compute step completion based on workspace configuration.
Persist progress so users can resume setup.
Step navigation rules:
- Clicking a step badge navigates between steps (same transition checks as Back/Next).
- Users can always navigate to previously completed steps (TBD if any restrictions apply).
- Users must not skip required steps via the header (forward navigation gating is TBD; must not allow bypassing required validations).
Step 1 selection propagation:
- Channel types selected in Step 1 must be reflected in Account > Channels (see Account – Channels).
- Users can add needed channels either by resuming Get Started or directly on the Channels page.
Step 2 staging rule:
- Channel connections created in Get Started Step 2 are session-scoped staged connections, not live workspace channels.
- They must remain visible only within the current Get Started session until the user clicks Complete on Step 3.
- Staged connections survive overlay close / reopen during the same login session.
- Staged connections are discarded on the next login if onboarding was not completed.
- Only the final Complete action commits those staged connections into the real workspace Channels state.
Re-entry:
- If the user dismisses/skips the overlay, they can re-open Get Started from the main menu Get started navigation item (until onboarding is complete or persistently hidden).
- Session dismissal (dismissedForSession) must only be cleared by the Get Started flow itself. Adding a connection from outside the Get Started flow (e.g. the Channels page Add profile dialog, or the combobox) must not re-show the overlay. This is enforced via the addedVia field on the add-connection mutation — see Account – Channels § “Get Started overlay must not re-appear after adding from Channels page”.
- Persistent hide: When the user toggles “Don’t show Get Started automatically” ON, the overlay never auto-opens and the nav item is removed. The only restore path is through Chatti Live.
Post-auth entry rule (MVP):
- After successful sign-in/sign-up verification, users are routed into this onboarding overlay — unless persistentlyHidden is true.
- If the overlay is dismissed/closed, route the user to Account → Dashboard.
- Closing/dismissing the overlay does not complete onboarding; it only exits the overlay for the current session.
- The overlay is shown on every authenticated entry until onboarding is complete or persistently hidden.
- Onboarding is considered complete only after the user completes Step 3: Train ConversionIQ AI.
Overlay close navigation rule (shell behavior):
- Closing the overlay from /get-started: redirect to Account → Dashboard (the user has no other page beneath the overlay).
- Closing the overlay from any other account page (e.g. /account/channels, /account/workspaces): do not navigate. Dismiss the overlay and refresh setup state only. The user remains on the page they were viewing.
- Implementation: in handleOnboardingClose (account-shell), check pathname. Call router.push("/account/dashboard") only when pathname starts with /get-started; otherwise call only postMutation + refreshSetup.
Shell integration:
- The Get started navigation item displays a 3-segment progress indicator derived from this onboarding state (see App Shell (Navigation, Search, Assistant Sidebar)).
- The Get started navigation item is hidden/removed from the left navigation when any of these is true:
  - Onboarding is complete (Step 3 completed).
  - persistentlyHidden is true (user toggled “Don’t show Get Started automatically”).

Domain refs:

API dependencies

GET /workspaces/{id}/setup-status (TBD)
GET /channels/connectors (TBD)
POST /channels/{type}/connect (TBD)
POST /knowledge-bases / PUT /knowledge-bases/{id} (TBD)

Enterprise constraints

Multi-brand support: setup is workspace-specific
Security: channel credentials are sensitive and must not be exposed in logs/UI

Edge cases

User loses permission mid-flow
Connector returns partial scopes (degraded connection)
User dismisses overlay before completing onboarding; activation remains incomplete and must be resumable.

Security & compliance considerations

Enforce permission checks on every step transition
Audit: channel connect + KB publish events

Reference: Security & Compliance

Analytics events (if applicable)

workspace.activation.started
channel.connected
kb.published
workspace.activation.completed

Reference: Analytics Events (MVP)