Client onboarding wizard

From "I just got off a call with Acme" to "Susan's whole crew is in RippleCore." One invite email, one guided setup with Rippler (and Bella's voice if you want it), three paths for three kinds of people, and the Academy as the hand-off. Built for Inframark's 456 committed users arriving in waves and for the landscaper whose crew lead sets up in the truck.

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

Update, 9/2 evening. After MJ and Seth's huddle the journey was revised: it now starts in the CRM (deal to subscription), runs a Step 0 intake before any call, uses the call to confirm and decide, then invites into the app, and adds a feature-add loop. The storyline page zooms out: who holds the baton at every step, the handoff at every phase boundary, a direct customer and an Inframark Wave 1 vendor side by side, and life after go-live; the wizard now shows a hat-change screen at every part boundary. The CRM company record now carries a Subscriptions section in its Agreements tab, in the CRM's own styling. The Journey v2 doc has the six phases, the systems map (what is built vs gap, including John's subscription system), the build list with owners, and a 51-question decision interview. The wizard below is already the v2 flow for Susan; Luis and Priya are unchanged.

Where we are today. A new customer gets Clerk's invitation email, creates an account, and lands on a one-field "name your team" page that creates the workspace. Then they are on an empty dashboard with 40 sidebar items and no guide. Every real setting they need exists (Settings > General, Members, Roles, Account > Profile) but nothing walks them there, nothing carries over what the rep learned on the call, and a field worker on a phone gets the exact same screen as an executive. Inframark alone brings 100 users 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: A and B combined, 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 · A + B

Guided setup, two parts, one flow

Part 1, our side (4 screens): set up the company from the kickoff call, plan and seats and modules, security and policy defaults, review and send. Part 2, Susan's journey (13 screens): inbox, account, secure it (two-factor), meet Rippler, company with hours and service area, plan, team, what Acme uses, company policies, about you with landing page, a four-spot tour, done, and then the dashboard with the checklist that stays until it is finished. Luis's Part 1 is the live Members invite composer; Priya's is a Wave 1 send from Onboarding Ops.

New since the first pass: secure-your-account step (Clerk MFA), company policies step (required 2FA, allowed sign-in domain, who can invite, session length, SSO, AI data use, retention), business hours and service area on the company step, landing-page preference, and the onboarding manager's status view after sending.

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

36 clips generated with the Academy's Bella voice (ElevenLabs, same voice id and model as the onboarding videos), one per step per persona including the onboarding manager's screens, about 3 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: A and B as one flow, C later

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

Wave 1 ships: the branded email reconciled on both Clerk instances; the wizard as an extension of the existing `/auth/onboarding` route (which today only names the workspace) with secure-it, company, team, policies (read-only until the policy backend lands), you, tour and done; the onboarding manager's four screens as an expansion of `/admin/clients/new.html`; the Luis and Priya short paths keyed off the Clerk role; Rippler's guide bubble with the static script; the Bella toggle with the 24 clips; and a persisting setup card on the dashboard so anyone who skipped can finish later (build it into the dashboard rework, MJ 2026-09-02). Plus the Client Onboarding tab in Onboarding Ops so the manager watches every company from invite to live. Plan, modules and kickoff-notes fields go on the rep's new-client form so the wizard can prefill.

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.