Onboarding Overview

Overview

Zooly has four chat onboardings. The landing page sends each visitor to the one for who they are: talent, brand or agency. /onboarding is the open interview for everyone else, and the one used to add someone to a roster. The chat itself never asks for a user type.

All four run on the same page and chat, with the same research card, photo card and sign-up. What changes is the list of questions and a few rules that code enforces. Every account gets Bouncer and Scout. An agency also gets Roster.

Two older flows remain: the Fast Signup wizard for mobile ads, and the legacy setup wizard.

---

The three interviews at a glance

How the chat onboardings work

• One page. OnboardingPage reads the flow from the URL (onboardingFlowFromPath) and sends it with every room request. Each flow keeps its own guest draft in the browser.
• Opening lines from code. The first bubbles are posted by code, so they are word for word and show at once. Everything after is written by the agent.
• One config per flow. LANDING_FLOWS in onboarding-instructions.ts holds the questions, the setup goal, the persona instructions and what the memory pass may record. The questions live in onboarding-questions.ts.
• The persona marks the setup goal. No memory pass runs during the interview. When every area is answered and the visitor says they are ready, the agent rules account-setup met in its reply and the page shows the photo card. Names typed in the talent, brand and agency interviews are saved by code.
• Research card. A link or @handle makes the agent call researchTool. The chat input is hidden while the card is open: while it looks things up, and until the visitor presses Done. See Research Tool and Findings Card.
• Claim. Signing up claims the guest room, enables Bouncer and Scout, and copies the onboarding to the account. Brand and agency also set the account type.
• Canned chips. When Z asks a known question, pills appear above the text box and a tap sends that answer. The highlighted pill is a suggestion, not a selection. A reply that is not one of those questions can still get a generic pill, such as Proceed. See Canned chips.

---

Onboarding Journeys

1. Agent Setup Onboarding

The open onboarding at /onboarding. Instead of choosing a user type or service card, a visitor has one conversation with the agent: their name, where to read up on them, and what they want the agent to do.

• Single interview: The agent asks one question at a time, in its own words. No memory pass runs after each message.
• Research card: A link makes the agent call researchTool; what it finds shows as a card the visitor confirms with Not me and Done, with the chat input hidden until they do. See Research Tool and Findings Card.
• Goal-driven sign-in: When goals.account-setup is met, the chat gives way to the photo card and then sign-up.
• Default capabilities: Signing in claims the guest room and ensures Bouncer and Scout are enabled.
• Roster inference: AI decides only whether the transcript explicitly establishes that the person manages offers for others.
• Durable promotion: Planner + Arvist promote the interview into one account memory.

2. Talent Onboarding

The interview for talent at /onboarding/talent.

• Handle first: The research card fills in the name, so the name is asked only when research found none.
• Phone from the chat: Code saves it to the account, and the welcome SMS goes to it.
• Deal preferences: Deal types, smallest offer and dream brands.
• Ends on the talent dashboard.

3. Brand Onboarding

The interview for brands at /onboarding/brand.

• Website first: The account is named after the brand.
• The person is the contact: Their name is saved as contactName.
• Ideal talent, formats and budget: Ideal talent is typed. Formats and budget show canned chips. No phone question.
• Ends on the brand dashboard: The account type is brand.

4. Agency Onboarding

The interview for agencies at /onboarding/agency.

• Website first: The account is named after the agency.
• Agency kind: Asked only when research cannot tell whether they represent talent or buy for brands.
• No roster question: The roster is added from the dashboard after sign-up.
• Ends on the agency dashboard: The account type is agency, with Roster on.

5. Fast Signup Flow

A mobile-optimized wizard at /talent/fast-signup designed for rapid conversion from social channels and ads.

• Late Authentication: Users select target brands and enter social links as guests before signing in.
• Social Profile Verification: Validates handles across Instagram, TikTok, YouTube, and X before advancing.
• Draft Buffer & Flush: Buffers progress in localStorage and automatically flushes to the account upon authentication. Account creation already enables Bouncer and Scout.

6. Legacy Setup Wizard

The original component-based setup flow implemented as SetupScreen in packages/client/src/screens/SetupScreen.tsx.

• Step-by-step forms: Profile, Campaigns, Terms/Licensing (Voice, Image, Merch), Samples, Z-Link, and Stripe Connect.
• Direct Account APIs: Queries /api/account and /api/account/payout-route to track completion checkboxes.

---

Onboarding Routes & Pages

---

Legacy Setup Wizard Reference

The legacy SetupScreen component accepts navigation callbacks from the host application:

interface SetupScreenProps {
  onGoToProfile: () => void;
  onGoToDashboard: () => void;
  onGoToVoiceLicense?: () => void;
  onGoToImageLicense?: () => void;
  onGoToMerchLicense?: () => void;
}

Steps