V1 Web PWA · Journey

Journey: Onboarding wizard, ten steps

A source-reconciled journey record for V1 Web PWA — shipped behavior, state boundaries, failure modes, and the automation evidence available today.

automated · 3 specs verdict: pass· 2026-05-29
9sections5 minread
Markdown source
On this page
Journey at a glance
ActorsNew memberPrivacy-conscious memberAccessibility userReturning member
Systems exercisedonboarding.mdprofile.md03-pwa-behavior.md04-auth-session.md
Automation3 E2E spec(s) · verdict: pass· 2026-05-29

Journey flow#

Generated from the authored steps below — click a node to jump to that section.

flowchart TD s1["1. Welcome and resume"] s2["2. Choose required goals and domains"] s3["3. Choose optional interests and a routine"] s4["4. Choose one guide family"] s5["5. Configure notifications"] s6["6. Configure accessibility"] s7["7. Configure memory and consent"] s8["8. Complete and inspect synchronization"] s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 click s1 href "#1-welcome-and-resume" click s2 href "#2-choose-required-goals-and-domains" click s3 href "#3-choose-optional-interests-and-a-routine" click s4 href "#4-choose-one-guide-family" click s5 href "#5-configure-notifications" click s6 href "#6-configure-accessibility" click s7 href "#7-configure-memory-and-consent" click s8 href "#8-complete-and-inspect-synchronization" s8 --> v(["verdict: pass"]) click v href "../results/onboarding-ten-steps.html" style v stroke:#3fb950,color:#3fb950

The authenticated onboarding wizard ships ten ordered steps, browser-persisted draft/resume, required-field gates, a local preference projection, and a best- effort BFF preference sync. The current controls are narrower than the original journey described: guide style is one persona-family choice, notification settings do not include SMS or a quiet-hours window, accessibility has four toggles, and memory offers three modes plus five categories. The wizard does not currently emit its declared onboarding analytics events.

Personas#

  • New member — completes required goals, domains, and routine choices.
  • Privacy-conscious member — chooses memory mode, categories, and consent.
  • Accessibility user — selects reduced motion, high contrast, larger text, or haptics.
  • Returning member — resumes a locally saved draft after leaving the flow.

Pre-conditions#

  • Sign in before visiting /onboarding; the route is protected and an anonymous request redirects through authentication.
  • Start with a supported browser storage context. Draft state is stored under oshun.onboarding.
  • The canonical step order in ONBOARDING_STEPS is welcome, goals, domains, interests, routine, guide, notifications, accessibility, memory, complete.
  • Keep browser completion separate from server synchronization. A completed local wizard can exist even when the preference API is unavailable or not configured.

Steps#

1. Welcome and resume#

The welcome step introduces the flow. OnboardingResumeBanner appears only when a draft exists; it is not a universal onboarding banner. Continuing uses the stored current step and selected values.

2. Choose required goals and domains#

Goals and domains are required before advancing. The wizard validates these steps locally and keeps the draft current after each change. A missing required selection prevents forward navigation without inventing a server validation request.

3. Choose optional interests and a routine#

Interests expose eight broad topics. The sensitive-context controls are two separate toggles—wellbeing signals and sensitive traits—not eight per-interest consent switches. Routine is required and captures the supported cadence/time choice in the onboarding draft.

4. Choose one guide family#

The guide step selects one persona family. Teacher style and content tone are derived through resolveAssistantPreferenceDefaults; they are not independent controls on this screen. This choice updates the local preference projection when the wizard completes.

5. Configure notifications#

The current step offers four topics—daily, events, research, and achievements— plus push, email digest, and quiet-hours toggles. It does not offer in-app/SMS delivery, sample-content previews, or a quiet-hours time range. The quiet-hours toggle is therefore a preference flag, not a complete scheduling policy.

6. Configure accessibility#

Choose among reduced motion, high contrast, larger text, and haptics. The wizard does not currently expose screen-reader or caption controls. Verify those four fields in the resulting local preference state rather than mapping them to unrendered options.

Choose off, session, or profile, decide whether to grant consent, and select from the five displayed memory categories. The screen does not promise 30- or 90-day retention. Its normal UI keeps sensitive traits off during onboarding; automation can still exercise explicit sensitive-category payloads at the underlying contract boundary.

8. Complete and inspect synchronization#

completeWizard marks the browser wizard complete, patches the local preference store, and then attempts profile-preference synchronization. If the browser is already offline and a service-worker controller/token are present, it queues PATCH /v1/preferences. An online transport/5xx failure displays an error after local completion, but that failed online request is not automatically placed into the queue. A 4xx not-configured result is treated as non-blocking and the member proceeds.

No display-name field exists on the ready step. The declared onboarding_step_completed and onboarding_completed names exist elsewhere, but the audited wizard does not call an analytics emitter.

Post-conditions#

  • The local wizard records completion and its selected preference projection.
  • Required goals, domains, and routine fields passed local validation.
  • Offline completion is queued only when the explicit controller/token/offline conditions are met.
  • Server read-back is claimed only after a successful preference request or replay; local completion alone is not treated as that proof.
  • No onboarding telemetry, display-name capture, SMS delivery, or retention duration is claimed.

Failure modes#

  • Anonymous route access — the member is redirected instead of receiving a resumable wizard.
  • Storage unavailable — draft/resume cannot be guaranteed; the active UI may still work for the current page lifetime.
  • Required choice missing — goals, domains, or routine blocks progress.
  • Offline queue prerequisites missing — no service-worker controller or token means the preference patch cannot be queued.
  • Online sync fails after local completion — an error is shown, but the request is not automatically scheduled for replay.
  • Not-configured API — expected 4xx handling permits local completion; do not report a server profile write.
  • Analytics overclaim — declared event names are mistaken for emissions from this component.

E2E coverage#

Per-view files touched#

Cross-references#

Open questions#

  • Should an online preference-sync failure be queued automatically, or should local completion remain visibly pending?
  • Which notification service will turn the quiet-hours flag into a time-zone- aware schedule?
  • Should guide style and content tone become independent, explainable controls?
  • Where should retention duration and sensitive-memory policy be explained?
  • Should the wizard emit the existing onboarding event vocabulary, with consent and retry semantics defined?