Client onboarding wizard

One story, six phases, from the deal in the CRM to a customer living in the platform: closed-won becomes a subscription, our onboarding manager sets up the instance and sends a Step 0 intake link, the customer gathers everything before any call, the call confirms and invites, Rippler walks them in (Bella narrates if they want), and adding a feature later runs the same loop for just that feature. Two tracks: a direct customer (Acme) and company number one in Inframark's Wave 1.

The storyline, start to finish Journey v2 doc Click through v2 Subscription admin (hybrid)

Where to start. The storyline is the zoomed-out map: who holds the baton at every step and the handoff between phases. The Journey v2 doc has the systems map (built versus gap, including John's subscription system), the build list with owners, and the 51-question decision interview. The wizard is the click-through of the same six phases, with a hat-change screen at every part boundary. The admin-side screens use the admin reskin; the CRM screens use the CRM; Onboarding Ops screens use the IOO console.

Where we are today. A won deal spawns a draft subscription, but nothing carries it to onboarding: the manager retypes the company, the customer gets Clerk's default invite, lands on a one-field "name your team" page and then an empty dashboard with 40 sidebar items and no guide. There is no intake before the call, no call sheet, no place that shows every company from invite to live, and John's subscription system has no active plan yet. Inframark brings 100 vendors on Oct 1 and 356 more from Dec 1.

1 · What best-in-class onboarding does

Every great first-run has the same six moves

Slack, Notion, Linear, HubSpot, Gusto and the field-service tools (Jobber, ServiceTitan) all land on the same pattern. Nobody in our market does the last two.

Ask "who are you" first, then branch

Slack and Notion ask your role and what you will use it for before anything else, then show a different path. Admins configure; everyone else just joins. Three paths, not one wizard.

Both concepts

Land in the product with a checklist

Linear, HubSpot and Stripe put you on the real home page in under a minute with a progress card that stays until done. No 12-screen gate before you see anything.

Dashboard checklist

Get a first win in two minutes

Duolingo's first lesson, Notion's first page, Jobber's first job. RippleCore's version: "Create your first project" or "See today's tasks" as the last card, with the Academy video right next to it.

Done screen, all concepts

Prefill everything you already know

Gusto and ServiceTitan pre-populate from the sales call and the import. We know the company, the owner, the plan and the modules before Susan opens the email. Ask her to confirm, not to type.

Part 1, our side

A guide that talks, not a tooltip

Intercom and Pendo ship product tours. Duolingo and Headspace add a voice. Almost no B2B tool has a named guide with a voice you can turn on. Rippler already exists; Bella already narrates the Academy.

The gap: Rippler + Bella

Onboard cohorts, not just companies

Enterprise tools (Workday, Okta) invite by wave with a start date and a named specialist. Inframark's IOO already plans waves and specialists; the invite should say "Wave 1 · starts Oct 1 · your specialist is...".

The gap: IOO-aware invites

Thirteen best-in-class moves, and where each one shows up here

Role-based paths. Admin 6 min, field 2 min, wave user 3 min.

Guided setup, C

Progress and a time estimate on every screen.

Guided setup, C

Skip anything, come back later. Nothing is a gate except the account.

Guided setup, C

Prefilled from the kickoff call. Confirm, do not type.

Part 1

Named guide with optional voice. Rippler on screen, Bella in your ear.

Guided setup, C

Checklist that persists, then disappears. Lives on the dashboard until 100%.

Spotlight tour of the real screen, four stops, not forty.

Tour + dashboard

First win at the end. First project, today's tasks, open work orders.

Done screens

One-minute welcome video (already shipped in the Academy).

Done screens

Phone install for field crews. Add to home screen, text me the link.

Luis path

Human hand-off. "Talk to a person" on every screen; wave specialist for Inframark.

Rail, Priya path

Least-privilege defaults. Field Team is the default access; nobody sees money by accident.

Team step

Reminder if the invite sits. Clerk invites expire in 7 days; nudge on day 3 and day 6.

Proposed, not mocked

2 · The slice that makes RippleCore's version better

The rep already knows Acme. Rippler already knows RippleCore. Put them together.

Most onboarding starts from zero because the product does not know the customer. RippleCore does: the kickoff call, the proposal, the plan set in Platform Billing, and for Inframark the whole wave plan in Onboarding Ops. The slice is: carry that context into the first run so the customer confirms instead of types, and let the assistant that already lives in the product (Rippler, with confirm cards before any write) do the walking. Bella's voice is the accessibility layer for the demographic we actually sell to: an office manager, a crew lead in a truck, and an Inframark community manager, all on the same platform.

Susan Alvarez · Office Manager, Acme LandscapingCompany admin. Gets the invite after MJ's kickoff call. Confirms the company, plan and modules, invites 3 people.

About 6 minutes · 11 screens

Luis Ortega · Crew Lead, Acme LandscapingInvited by Susan as Member + Field Team. Name, photo, phone install, today's tasks. Nothing about money.

About 2 minutes · 7 screens

Priya Natarajan · Community Manager, InframarkWave 1, one of the first 100 (Oct 1 to Nov 30). Inframark is already set up; she confirms her profile and communities.

About 3 minutes · 6 screens

Pilot17
Aug 1 to Sep 30 · active

Wave 1 · First 100100
Oct 1 to Nov 30 2026

Wave 2 · Tier 1439
Dec 1 to Mar 31 · 356 count toward 456

Tier 2 · MSA2,003
Apr to Dec 2027

real Wave plan read from the Inframark tenant of Onboarding Ops (`/api/waves`) on 2026-09-02. 456 committed = 100 + 356.

3 · Three clickable directions, plus the email

The pick: one six-phase flow, Concept C kept for later

MJ's call (2026-09-02): one flow in two parts. Part 1 is the inviting side (the DataRipple onboarding manager for a new company; the company admin for a teammate; Onboarding Ops for an Inframark wave). Part 2 is the invited person's journey, ending on the real dashboard with the persisting setup checklist (the former Concept B). Concept C stays as the later direction. Switch persona in the top bar. Every card is labelled real today, proposed or needs backend.

The pick · six phases

Guided setup, six phases, one story

Phase 0, the deal (CRM): closed-won spawns the subscription, the agreement is signed. Phase 1, our side (admin, 4 screens): new client from the opportunity, subscription read-only, security defaults, send the Step 0 link. Phase 2, Step 0 intake (Susan, 8 screens, before any call): prep email, company, team spreadsheet with role suggestions, payment, security preferences, connect QuickBooks and Stripe and inbox and calendar, plan-driven videos, book the call. Phase 3, the call (1 screen): confirm, decide, invite. Phase 4, inside RippleCore (13 screens): account, two-factor, a three-minute confirm with Rippler, tour, done, dashboard checklist. Phase 5, three months later: adding Meeting Studio. Luis (field) and Priya (Inframark Wave 1) have their own short paths.

Hat changes are explicit: five handoff screens in Susan's flow name who hands to whom, what crosses over, and the event that triggers the next phase. Same handoffs on the storyline.

Open the guided setup

Concept C

Chat with Rippler

Onboarding as a conversation on the existing Ask Rippler surface. Rippler asks one thing at a time, the same forms appear as cards in the thread, chips answer the easy ones, and free text goes to the real agent with confirm cards. Progress sits on the right.

Best when: Rippler is the brand and you want onboarding to feel like the rest of the product, not a form.

Open Concept C

Onboarding Ops · Client Onboarding tab

The bubble timeline from the review-and-send screen, promoted to a tracker: every company from invite to live, stage, owner, days in stage, health, pings and nudges, with the full journey in a drawer. Styled on the live IOO console. Includes the recommendation on where the CRM fits: Onboarding Ops owns the tracker, the CRM reads the status onto the company record, RippleCore emits the events. No CRM move.

Open the tab

The invite email study

The proposed branded template for all three invite types, side by side with what the Clerk dev instance sends today (Clerk's default: read live from the Clerk API, `is_custom: false`). Subject, sender path, variables and the 7-day expiry are real. MJ's branded template lives on the production Clerk instance, which the dev key cannot read, so the proposed design is the thing to reconcile against it.

Open the email study

Bella narration

65 clips generated with the Academy's Bella voice (ElevenLabs, same voice id and model as the onboarding videos): one per step per persona, one per tour spot, one per hat change, about 5.5 MB total. Off by default; the toggle sits top-right on every concept and remembers your choice. When a clip is missing the browser's own voice reads the same line, so the toggle always works. The script is the same text Rippler shows on screen.

real clips, shipped as static files

4 · Good / better / best

What ships in Wave 1, what is partial, what is gated, and why

Verdicts come from what is actually in v3 (`ripplecore-frontend-react-v3`) and the receptionist worker today, checked on 5199 and 8787 on 2026-09-02.

Tier	Piece	Verdict	The real blocker, or why it is fine
Must	Branded invite email	OK Wave 1	Clerk template `organization_invitation` on the production instance already carries MJ's branding. Work = reconcile it to the proposed layout and copy the same template onto the dev instance (still Clerk default there). Persona copy needs `invitation.public_metadata` set by the backend's `createInvitation` (one field).
Must	Account creation and verify	OK Wave 1	Clerk sign-up on `/auth/sign-up` is live. Google sign-in depends on the Clerk social connection being enabled on prod; check, do not assume.
Must	Company profile step	OK Wave 1	Same fields and endpoint as Settings > General (`settings-workspace-panel.tsx`, contractors profile). Legal name, postal code and country are already flagged "backend field required" on the live page; leave them off the wizard.
Must	Invite your team step	OK Wave 1	The Members invite composer (`settings-users-panel.tsx`, `/api/team`, Clerk invitations, access-role assignment with Field Team default) is live with idempotency keys. The wizard reuses it.
Must	Your profile and notifications	OK Wave 1	Account > Profile and per-user notification preferences are live. Text-message channel is a placeholder today (shown disabled, as on the real page).
Must	Dashboard tour and done screen	OK Wave 1	Frontend only: a spotlight overlay component plus the Academy `start` lessons (4 exist; 3 are "Soon" in the library). Welcome to RippleCore (1:09) is already published.
Should	Rippler as the guide (bubble + chat concept)	Partial	The agent and confirm cards exist. Scripted guide text is static and ships with the FE. Letting Rippler act on setup ("invite dana as finance") needs an onboarding intent in `ask-ripple-interactive-prompt.ts` and the tool mappings; not in place.
Should	Bella narration toggle	OK Wave 1	Static MP3s generated offline (this mock's `gen-vo.mjs`), served as FE assets. No runtime TTS, no key in the browser. Regenerate when the script changes.
Should	Setup checklist that persists (Concept B)	Partial	Needs a per-user onboarding state (`onboarding_progress` table or KV keyed by contractor + user) and one `GET/PATCH` route. Small backend PR; nothing exists today.
Should	Kickoff notes prefill the wizard	Partial	`/admin/clients/new.html` has name, slug and owner email only. Plan, modules and notes are new columns on the tenant record plus three fields on that form; then the wizard reads them. Small.
Should	Customer-facing "what you use" module toggles	Gated	Per-tenant feature flags exist but only DataRipple staff set them (`/admin/feature-flags`). Exposing `nav.*` flags to an org admin means a tenant-scoped write route plus the guard rules. Wave 1: the rep sets them on the invite form; the step becomes read-only "here is what is on".
Should	Secure your account (two-factor) step	Partial	Clerk user MFA is real (Account > Security, "Set up MFA", TOTP). The wizard step just fronts it. "Required by company policy" needs an org setting plus a sign-in check; SMS codes wait on the SMS channel.
Should	Company security and policy defaults	Gated	Two of eight exist (admin-only invites, closeout retention). Org-enforced MFA, verified sign-in domains with request-to-join, session length, SSO and the AI data-use opt-out all sit behind Settings > Security and Data & Privacy, which read "Soon" in v3. Clerk provides domains, enforced MFA and SAML as org features; RippleCore has no UI or policy table for them yet.
Should	Client Onboarding tab in Onboarding Ops (+ CRM chip)	Partial	The IOO journey engine (stage ladder, specialists, tasks, nudges, undo, waves) is real and gets pointed at customers. Needs a `client_journeys` table fed by RippleCore events (Clerk invitation webhook, team member status, wizard step saves) and a read-only Onboarding chip on the CRM company record. Closed-won creates the row.
Should	"Ping your onboarding manager" and add-on asks	Partial	Frontend is a modal. The send needs one route that creates a task in Onboarding Ops and a thread in Ask Rippler; the manager's reply goes back by email. Add-on and seat-gated modules read from the plan set in Part 1 (Platform Billing lines + feature flags).
Must	Setup checklist card on the dashboard	Partial	MJ: keep it. The dashboard home is due a rework anyway, so the checklist card ships as part of that rework, reading the same onboarding progress table the wizard writes. Frontend card + one GET route.
Differentiator	Plan and payment step	Gated	No customer-side billing backend (Settings > Billing shows "Soon"; the settings refresh spec files it as a gap). Subscriptions exist only in the internal Platform Billing module. Wave 1 = show the plan from the proposal and "DataRipple invoices you"; card capture waits on the billing PR.
Differentiator	Inframark single sign-on	Gated	Settings > Security is "Soon"; SSO/SAML is not configured. Priya signs in with email + password today. Clerk supports SAML per org; it is configuration plus a Clerk plan check, not code.
Differentiator	Wave-aware invites at scale (IOO to RippleCore)	Gated	IOO knows waves, specialists and vendors; RippleCore knows invitations. There is no bridge. Needs a bulk-invite endpoint on the receptionist worker (wave id, list of emails, metadata) that IOO calls, plus the auth bridge already designed for the IOO embed. Without it, 100 Wave 1 invites are 100 clicks in Members.
Differentiator	Text-message invite and alerts for field crews	Gated	Twilio is wired in the receptionist worker but only for receptionist traffic. SMS notifications are a placeholder in Settings. A "text me the install link" is one Twilio send; SMS task alerts are the bigger notification-channel job.

5 · What this means for Wave 1

Recommendation, now the plan: schema first, Onboarding Ops second, then the intake and the in-app confirm

Build the two-part flow as the first run, with the checklist card living on the dashboard afterward

Wave 1 ships: the schema call with John (activation writes Platform Billing and System B together, one base plan for the 550); Onboarding Ops first (client rows and events, the Client Onboarding tab, the batch intake sender, the call sheet); the Step 0 intake app reusing the import wizard, Connect QuickBooks, the booking page and the Academy player; the in-app confirm on /auth/onboarding with the Rippler bubble, Bella toggle and the dashboard checklist inside the dashboard rework; the Subscriptions section on the CRM company record. Full list with owners in Journey v2.

Deliberately gated: card capture (billing backend), org-enforced MFA and the policy set (security backend), SSO (Clerk config), IOO-to-RippleCore bulk invites (new endpoint), SMS (notification channel). Each is one row above with its real blocker; none of them stops Wave 1.

Concept C is the direction once Rippler can act on setup intents. Keep the same step cards so it is a re-skin of the flow, not a rebuild.

Honest cost: frontend about 2.5 weeks (route + 9 step screens, the 4 admin screens that wrap the existing settings panels, spotlight overlay, voice player, checklist card); backend about 1 week (onboarding progress table + route, 3 tenant fields, invitation metadata, template sync on the dev Clerk instance). The IOO bridge is a separate 1 to 2 week backend item and is the one that matters for 100 users on Oct 1. Two repos, so two PRs per slice (v3 FE + receptionist worker BE). Ranges are estimates, not commitments.

Gate 1 deliverable. Sample client data lives only in this mockup; the real build wires real data from line one. Local: node mockups/onboarding-wizard/_serve.mjs then http://localhost:4780/. No em dashes were used in the making of this document.