Synced from the repo — do not edit here

Canonical source: docs/claude/onboarding-signup-flow.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

Onboarding / Sign-in Flow — Design Spec & Build Handoff

Status: DESIGN ONLY. Not implemented. Every screen below exists as a standalone HTML mockup — now committed in-repo at docs/claude/mockups/ready-practice-*.html (portable; the /Users/G/Desktop/ copies are the originals). The live app (hybrid/basisflow-web/app/signup/) is UNCHANGED (last modified 2026-05-05, before this work). Implementing these into the real Next.js app is the open task.

Two pieces of this effort DID ship to production (see §7). Everything else is a proposal.

⚠️ DECISION (George, 2026-07-20): PUBLIC SELF-SERVE SIGNUP STAYS HIDDEN for now. Do NOT expose/ship the public self-serve signup flow yet — it needs refinement first. New clinics are provisioned manually / sales-led (e.g. Optimal Performance was created directly via add_clinic + locations + services, owner set as Admin). The sign-in screen + onboarding-flow designs here are for that net-new-signup work when we DO turn it on; until then, keep the signup route un-linked/gated. Build the pieces, but don't light up the front door.

Product: Ready Practice (public brand; internal = Basis Flow Web). App: hybrid/basisflow-web (Next.js). Signup URL: my.readypractice.com/signup.

1. The flow (final agreed order)

Landing / sign-in
  → Email + OTP (magic-link)
  → Practice basics
  → Meet Atlas (6-slide personalized intro)   [no-data fallback if no website]
  → Connect tools           → Atlas confirms what it learned
  → Import data             → Atlas confirms what it learned
  → Paywall ($999 or custom)
  → Add-ons (post-commit, bundle discount)
  → Dashboard

Collapse /signup + /signup/create-clinic into ONE state-driven /signup wizard. Today they're two routes = two auth states; make it a single route driven by a step index. On load, "logged-in-but-no-clinic" resumes at the right step (the current redirect becomes in-page state) so refresh & magic-link returns land correctly.

2. Screens (each maps to a mockup file on Desktop)

#	Screen	Mockup file	Notes
1	Landing / sign-in	`ready-practice-signup-mockup.html`	Split layout: left = warm gradient + rotating testimonial card (quote + avatar + name/title + carousel dots); right = white auth column. Badges HIPAA · BAA · GDPR at bottom of the right column, centered above the legal footer. ⚠️ Headline currently "Start free." — must change (no free tier / charge up front).
2	Email / OTP	`ready-practice-email-otp-mockup.html`	Same split layout. Two states: enter email → enter 6-digit code. Email/OTP magic-link ONLY — Google removed (its runtime status was never verified; see §6).
3	Practice basics	`ready-practice-basics-mockup.html`	Business name (pre-filled from email domain) · business type (Clinic / Telehealth / Med Spa / Gym & Fitness / Wellness-Coaching / Other, as clean line-icon cards) · team size. Uses "business," not "clinic/practice."
4	Meet Atlas	`ready-practice-atlas-capabilities-mockup.html`	Clickable 6-slide slider. Slide 1 = personalized overview ("I've read marronhealth.com… here's how I'll help") + a live "what I learned about you" panel. Slides 2–6 = one capability each, each with its own testimonial + its own demo visual: (2) onboards & manages clients, (3) scheduling/memberships/payments, (4) monitors health data & documents, (5) runs client programs, (6) recommends revenue/retention/upsells. Headline theme: "Atlas helps you manage and scale your healthcare business."
4b	Meet Atlas — no-data fallback	`ready-practice-meet-atlas-fallback-mockup.html`	Shown when no website / personal email → can't personalize. Headline "Let's build [Business] together," a website-capture field ("paste your site, I'll study it now"), and a "coming online as you set up" panel (website → clients → tools).
5	Connect tools	`ready-practice-tools-mockup.html`	Only real integrations (verified in Settings): Stripe, Zoom, Google Meet, Branded email, Fullscript. NOT Calendly/QuickBooks/Ads/etc. (those were invented and removed). "Skip for now" + "Request an integration."
6	Atlas confirms each step	`ready-practice-atlas-confirm-mockup.html`	Reusable card after Practice-basics / Connect-tools / Import-data. Two states: "here's what I learned" (resolves inline for fast steps) vs "still reviewing the data — I'll let you know" (non-blocking, for slow steps like big imports + website analysis). Never blocks the user.
7	Import data	`ready-practice-import-mockup.html`	Upload CSV/PDF (client lists, intake forms, pricing) → Atlas parses, maps fields, contextualizes so it "learns from day one." Includes a pulsing "Atlas is studying [domain]" website-learning banner (fires at signup for business emails).
8	Paywall	`ready-practice-paywall-mockup.html`	⚠️ Mockup shows Solo/Growth/Scale tiers — SUPERSEDED. Final decision: single $999/mo plan or Custom (no public tiers). Charge up front; annual first-year $8,495 paid upfront (~29% off), renews $9,995. Done-for-you divert: "$25k setup / $100k ACV → Book a call."
9	Add-ons (post-commit)	`ready-practice-addons-mockup.html`	Shown AFTER subscribing ("You're in. Now power up Atlas"). Bundle discount that deepens with more add-ons.
10	In-app upgrade nudge	`ready-practice-upgrade-nudge-mockup.html`	Not onboarding — the expansion mechanic. Atlas surfaces the upgrade at client-cap (e.g. 48/50) or hire triggers.
—	Click-through prototype	`ready-practice-prototype.html`	Harness that plays all screens in sequence (iframes; open in Safari or via `python3 -m http.server`).

3. Invite emails (separate from the wizard)

Email	Mockup	Status
Client invite (patient → consumer "Ready" app)	`ready-practice-invite-email-mockup.html`	Before/after redesign. NOT deployed. Fixes: clinic-branded header, one-tap deep-link join (code → fallback), value-forward perks, "on Ready" not "Basis Health."
Staff invite (staff → Ready Practice web platform)	`ready-practice-staff-invite-email-mockup.html`	DEPLOYED — see §7.

4. Onboarding email sequence (behavioral — mapped, NOT built)

Modeled on a 5-email activation nurture. Triggers are behavioral, not just time-based:

#	Trigger	Goal / milestone
1	Account created (Day 0)	"Atlas is already studying your practice" → open dashboard
2	Day 0 +2h	"Three things that set Atlas up" → connect a tool / import clients
3	After first import/action	"Your clients are in — here's what Atlas sees"
4	+24–48h, no first Atlas message	idle-nudge (only fires if not activated)
5	+4–5 days, active user	"Teach Atlas your way" → create a skill → retention

Email system lives in basis-functions (templates are inline f-strings in functions_clinic.py, not email_templates.py).

5. Automated Atlas actions during onboarding (mapped only — for the other agent to build)

Atlas lives INSIDE Ready Practice (not Slack). Guardrail: read/context-building autonomous; anything client-facing or write needs approval.

Trigger	Atlas action	Guardrail
Signup with business email	Studies the business website → builds context	Autonomous (public web)
Data imported	Reads files → proposes field mapping + business model	Human approves import
Workspace ready	Posts intro + 3 starter prompts	Autonomous (informational)
Observed pattern (unconnected payments, unreviewed labs, idle clients)	Offers to set up a digest/automation	Human approves
Needs access it lacks	"Pending action → Approve/Reject" card	Explicit approve
Revenue signal (at-risk client, upsell-ready)	Suggests action (win-back draft, offer)	Human approves before client-facing

6. Key decisions locked

Auth = email/OTP magic-link only. Google is coded (signInWithGoogle) but its runtime status (Firebase authorized-domains / provider enabled) was never verified — treat as unavailable until tested. For staff (PHI), first-login likely needs an identity/MFA step before chart access.
Charge up front, no free tier (premium cash-cow strategy). The "Start free" landing copy must be replaced.
Single /signup state-driven wizard.
Personalization: Atlas learns from the business website at signup; Meet Atlas opens personalized; graceful fallback when no website/personal email.
Atlas confirms after each step (learned / still-reviewing).
Public plan = $999 or custom (paywall mockup's Solo/Growth tiers are superseded).
Wearables included in base.

7. What actually shipped to production (real code, deployed)

Staff invite email — rebranded + email-safe HTML. functions_clinic.py (2 send sites: initial invite ~line 10736, resend ~line 13398), deployed via firebase deploy --only functions:clinic_service. Rebrand "Basis Health → Ready Practice"; link kept at platform.basishealth.io (until domain cutover). Header is a dark bar (clinic brand color not available in that code path — a follow-up).
submit_offer_request Cloud Function — functions_slack_bot.py, registered in main.py, deployed. Public HTTP endpoint (https://us-central1-basis-hybrid.cloudfunctions.net/submit_offer_request) that posts a configured quote to Slack #growth (C7DMFHMPE) via the existing bot token. Requires the bot to be invited to #growth or it returns not_in_channel. Powers the "Request this offer" button in the quote builder (ready-practice-quote-builder.html).

8. Implementation targets (when building for real)

hybrid/basisflow-web/app/signup/page.tsx — auth/landing (currently the original design).
hybrid/basisflow-web/app/signup/create-clinic/page.tsx — the wizard (collapse into /signup).
hybrid/basisflow-web/components/signup/ — AtlasOnboardingChat.tsx, PricingTiers.tsx, LegalAgreementModal.tsx.
Backend capabilities the flow depends on: Atlas website-learning at signup, magic-link/first-login MFA, import-data parsing, active-client-cap enforcement.

9. Open items / decisions still needed

Verify or remove Google auth; confirm the my.readypractice.com domain + its known CORS issues.
Replace "Start free" copy for charge-up-front.
Deploy the client invite email redesign (email-safe HTML; not done).
Build the onboarding email sequence (§4) and the automated Atlas actions (§5).
Billing/pricing (paywall, add-ons, metering) — see docs/claude/billing-pricing.md.

10. Consolidated build-task checklist (nothing built unless flagged)

Structure

Collapse /signup + /signup/create-clinic into one state-driven /signup wizard (resume "logged-in-but-no-clinic" at the right step).

Screens (in flow order)

Backend capabilities the flow depends on

Atlas website-learning at signup (business email → study site).
Magic-link/one-tap improvements + first-login MFA decision for PHI.
Active-client-cap enforcement (also the margin/cost-control lever).

Email updates

Staff invite — DONE & deployed (rebranded, email-safe HTML; link kept at platform.basishealth.io). See §7.
Client invite — redesign NOT built/deployed: email-safe HTML, rebrand Basis Health → Ready, one-tap deep-link join (code → fallback). Lives at functions_clinic.py:10082 (+ resend :13312).
Onboarding email sequence (5 behavioral emails — §4) — not built.
Auth / magic-link email (the sign-in-link email itself) — check it's rebranded (functions_auth_emails.py).
Staff invite polish (optional) — use the clinic's brand color in the header instead of the current dark bar.

Open decisions blocking "real" work

Final prices + processing/RCM take-rates + active-client cap (see billing doc; some now set).
Role label source for the staff invite (Admin/Manager/Medical/Customer Service/Coach).
Domain: my.readypractice.com vs platform. + its known CORS issues.
Whether the full Basis Health → Ready Practice cutover (domain + remaining copy) ships together or piecemeal.
Verify or remove Google auth.

1. The flow (final agreed order)​

2. Screens (each maps to a mockup file on Desktop)​

3. Invite emails (separate from the wizard)​

4. Onboarding email sequence (behavioral — mapped, NOT built)​

5. Automated Atlas actions during onboarding (mapped only — for the other agent to build)​

6. Key decisions locked​

7. What actually shipped to production (real code, deployed)​

8. Implementation targets (when building for real)​

9. Open items / decisions still needed​

10. Consolidated build-task checklist (nothing built unless flagged)​