Agent Setup Onboarding

Overview

/onboarding is one account-level conversation with the agent. It does not ask the visitor to select Talent, Brand, Agency, Bouncer, Scout, or Roster. The visitor starts as a guest and signs in near the end.

The agent learns three things, in order, in its own words:

1. Who they are — "What's your name?"
2. Where to read up on them — a site, a social profile, any link, or a short description. A link is never mandatory. Each new link starts the research card: see Research Tool and Findings Card.
3. What they want the agent to do — handling incoming offers, finding partners or talent, managing people or IP, in their own words.

Then it asks whether they have any question before it moves on. That line is not one of the canned question types. It can still show the generic Proceed pill. A confirm ("is that right?") can show the canned pair, That's right / Let me fix something. See Canned chips. When they acknowledge, the persona marks the setup goal in its reply and the page moves on to the photo card and sign-up.

The landing page also opens three interviews chosen by who they are claiming (ZLY-2026): /onboarding/talent, /onboarding/brand and /onboarding/agency. Same chat, same research card, same photo card and sign-up; only the questions and their order differ. Each has its own page: Talent Onboarding, Brand Onboarding and Agency Onboarding.

Every account receives two capabilities:

• Bouncer — inbound offers and negotiation
• Scout — outbound partner and talent search

Roster is conditional. At finalization, AI determines whether the transcript explicitly establishes that this account manages offers for other people, brands, teams, or properties. If yes, it enrolls Roster. It never infers a fixed user type.

See Capabilities, Seats, and Derived Role.

Funnel

One home room

Onboarding creates or resumes one home room for the account-level agent:

• one host participant
• service = agent
• No background memory pass after each interview turn; the persona marks the setup goal in its reply
• one declared goal: account-setup
• lifecycle state under memory.onboarding

const room = await createZAgentRoom({
  title: "Your agent",
  kind: ROOM_KIND_HOME,
  service: "agent",
  goalConfig: [ONBOARDING_SETUP_GOAL],
  memory: {
    onboarding: {
      service: "agent",
      serviceRevision: randomUUID(),
      status: "active",
      setupStarted: false,
      coverage: {},
    },
  },
});

There are no separate Bouncer, Scout, or Roster home rooms.

Information areas

The areas live in packages/z-agent/srv/src/onboarding-questions.ts and are injected into the persona's runtime instruction (onboarding-instructions.ts). They describe what to learn, not a form:

The agent asks one question at a time, in that order, and never stalls on a missing link. Completion is semantic: irrelevant or contradictory text is not evidence, and a short or informal answer still counts.

The talent, brand and agency interviews use the wording from the Question and Flow Framework (ZLY-2022). What code does for each of them (opening lines, names, the talent phone, whose links count, the account type) is on its page: Talent, Brand and Agency.

The setup goal

Interview turns skip the background memory pass. The persona rules the setup goal itself, in its own reply:

• it marks goals.account-setup met once the areas are answered and the person has acknowledged the "any question before I move on?" line
• a reply written against an obsolete serviceRevision is dropped
• onboarding.coverage is not written during the interview; the persona reads the chat itself

When the goal is met the room view returns interviewReady: true and the page leaves the chat for the photo card. Continue or skip there opens the integrated authentication modal. A guest who reaches the message cap is asked to sign in early (overMessageCap).

During the interview the agent only ever answers. It never messages on its own — no "Your agent reached out", no re-asking after a pause — and going quiet triggers nothing: the next question waits for the person. Reaching out becomes possible only after sign-up, on the dashboard.

Profile research: the research card

Research runs only when the agent asks for it. In the onboarding chat the persona has a researchTool instead of scrapePublicUrl, and calls it for every new link. The call shows in the chat as a card: "Doing the homework..." while the existing profile research runs, then the findings, each line approved until the visitor presses Not me, then Done. The chat input stays hidden while the card is open. Only what they confirm reaches the profile and the agent. Pasting a link never starts research on its own.

The full flow, the hidden input, what is saved and the edge cases are on Research Tool and Findings Card.

Claim, capability defaults, and roster inference

claimOnboardingRoom binds the guest host seat to the authenticated account. Finalization then, inside the claim request:

1. Ensures bouncer and scout rows exist in account_service.
2. Marks the agent live and writes the Z link into onboarding memory.

Everything left is model work, so the request does not wait for it. Claim returns first, then Next.js after() posts to /api/z-agent/onboarding/promotion/callback. Posting from inside the claim request kept that response open until Planner and Arvist finished. That invocation:

3. Runs a narrow AI classification over the transcript:
   • true only when the user explicitly manages commercial offers for others
   • false for someone handling only their own opportunities
   • no guessing from job titles
4. Enrolls roster only when that classification is true.
5. Records the roster decision and evidence in onboarding memory for audit.
6. Runs Planner + Arvist promotion and enables normal room planning.

Awaiting steps 3-6 in the claim request left the visitor on the live spinner for the length of two model calls, and could exhaust the route's time budget. Promotion carries a retryable lease, so a claim that arrives while an earlier attempt is still running is a no-op, and an attempt that died mid-flight is picked up by the next claim.

Roster can also be enabled later. My roster is always shown in the menu; an unenrolled account that opens it is asked the focused representation question and enrolled only after answering yes.

One durable account memory

Arvist promotes the completed setup into one free-form z_agent_object_memory document for the account. Identity, inbound preferences, outbound goals, and roster context share that document.

There are no shared or services.<key> intelligent-memory branches. Exact physical settings such as a Bouncer minimum offer remain in account_service.settings.

When another room binds the account, the complete durable document seeds the room's host branch — or the home room's host branch when that document is newer (Update Agent Distil before the next Arvist). Visitor account memory is never seeded into someone else's deal room. After the agent is live, each Update Agent Distil runs Arvist for the host so a new preference is durable before they test z-link.

Photo, sign-up, and after

1. Photo — when the setup goal is met, the chat gives way to a photo card. The visitor can add a profile image or skip it. Brand and agency see the logo wording; nothing is taken from their site.
2. Sign up — continuing opens the authentication modal. A guest's photo is kept and saved once the account exists.
3. Claim — signing in claims the guest room (see above).
4. After — every flow opens that user's own dashboard (welcome): talent, brand or agency, on the same device.

After onboarding

The profile is thin right after onboarding. So in the weeks that follow, Z asks up to ten short questions, one at a time by email or SMS, and saves each answer on the account, most of them where matching reads them. The series only runs once the team has switched it on. See First 10.

Key files and endpoints