Skip to content

Onboarding Design — Flow & UX

Status: Capture / pre-design. Not built. Companion to v3-redesign-draft.md (which owns the scenarios); this doc owns the flow, sequencing, gating, and nudges.

Source: June 1 2026 Beacon all-hands ([[2026-06-01-beacon-all-hands-weekly]]) + onboarding-UX research pass (June 2 2026).

At a glance

What this decides: how a brand-new user moves from signup → first aha, where the MCP connect step sits, and how we handle the skip path. Status: direction agreed (value-first), details open.

  • Value-first, not connect-first. Play game 1 and see insights before the connect ask — research says don't ask for the scariest step before the user understands why they care.
  • Aha stays in session 1. Pre-written, scenario-tied prompts let one thin game ($20 loan) produce a recognizable "the AI got me" moment. We assume users may not play a second game.
  • Connect is skippable, never a hard wall. Skipping leaves games low-value, so the skipped state is first-class: persistent checklist + banner + every-few-games nudge.
  • Gate the flow, not the app. Resume mid-flow if the user leaves before finishing game 1 + insights; then drop them to the dashboard.
flowchart TD
    A[Welcome screen<br/>one line of payoff, no tour] --> B[Game 1<br/>thin $20-loan scenario]
    B --> C[2-3 'potential pattern' insights<br/>first micro-aha — no connection needed]
    C --> D{Connect now?}
    D -->|Yes| E[Connect step — dedicated screen<br/>read-only reassurance, copy buttons, per-provider path]
    E --> F[Paste pre-written scenario-tied prompt<br/>BIG aha: AI gets the situation + names the pattern]
    F --> G[Dashboard / keep playing]
    D -->|Skip| H[Dashboard<br/>empty-state: 'profile does nothing until you connect']
    H -.persistent checklist + banner + nudge every few games.-> E

Why connect moves to step 4 (not step 1): the meeting's original plan was connect-first (rationale: it's the most boring step, get it out of the way). Research pushed back — leading with the heaviest, scariest step before any value is the classic activation killer. The fix: the connect step doesn't have to precede game 1, only the paste. So game 1 + insights deliver a first hit of self-recognition, which earns the motivation to connect, which unlocks the bigger aha. (Confirmed with CoachJ June 2.)

Gating model

  • Gate the flow, not the app. Onboarding is a dedicated full-screen flow through game 1 + insights. If the user leaves mid-flow, resume at the exact step (persist state; visible progress).
  • Connect = skippable, never hard-gated. Hard-walling the scariest step is where activation dies. Skip → dashboard.
  • Skipped state is designed, not an afterthought. MCP calls are date-stamped, so we can detect non-connectors and nudge. Persistent checklist item + dashboard empty-state copy + a reminder every few games with a one-click route back into the connect flow.
  • We are 100% "new customers" (Krystal Higgins' 4-states model) — the one state where some gating is justified, but with an optional skip on the heavy step.

Captured detail items (from the all-hands)

Time & cognitive load - Time-to-play indicator on the scenario-select screen ("~N min" at a glance) so users match scenario to mood/availability. Onboarding starts thin (Tay liked thin scenarios; governance = "mental tax") and ramps.

Connection mechanics (reduce friction) - Copy button on the API key when shown. - Generate-URL step — onboarding hands over the fully-formed URL with key already embedded; user does not assemble it. - Surface the API-key flow — currently buried ~5 steps deep in settings; needs a front-door path. - Minimize number of things to copy — every extra paste reads as "am I leaking a secret?" to non-technical users. - Investigate path-of-least-resistance connectors (the Obsidian/Claudian one-click pattern James mentioned).

Trust / reassurance - Safety copy in the moment at the connect step: read-only, "we're not taking your data, only enhancing your profile." Not buried.

Provider paths - Per-provider onboarding (Claude / ChatGPT / Hermes), each its own short path; possibly a CLI copy-paste command for OpenAI. Let users pick what they're comfortable with.

Insight framing (game-1 output) - 2–3 insights in "potential pattern" language — potential, not definitive — so it reads as "huh, interesting," not "you are X."

Open decisions (not yet resolved)

# Decision Notes
1 Connection method default Embedded-API-key (~4 clicks, current) vs. provider OAuth (James investigating). Leaning "offer both"; OAuth lifts conversion 20–40% and gives Beacon the identity mapping, but is finicky. Default path for a non-technical user not yet picked.
2 Exact nudge cadence "Every few games" — needs a concrete number + escalation rule.
3 Pre-written prompt set The scenario-tied prompts for the $20-loan game: one that mirrors this situation, one that elicits the underlying pattern. To be drafted.

Punted to "later" (not onboarding)

  • The 20-game "ta-da" reveal — ticker flips from reward-only to coherence %. Belongs with the scoring-system work, happens well after onboarding.

Research basis (June 2 2026)

  • Lead with value, then guide — don't trigger the heavy step before the user cares.
  • Short flows win — 3 steps ~72% completion, 7 steps ~16%, 15 steps <20%.
  • Speed of aha is the game — aha within 5 min → ~40% higher 30-day retention; first-session aha → 2–3× more likely to stay active; ~90% churn without week-1 value.
  • New users justify gating-with-optional-skip — but not hard-walling the scariest step.
  • Persist & resume — return drop-offs to their exact step; keep a visible progress indicator.
  • Connection steps need in-the-moment reassurance + fewer copies — OAuth/one-tap lifts conversion 20–40% over manual key-pasting.

Sources: Appcues — choosing the right pattern · Krystal Higgins — 4 user states · ProductLed — aha moments · Genesys Growth — product-led onboarding 2026 · UserGuiding — onboarding statistics · Userpilot — progress-bar psychology · Prove — frictionless onboarding