Skip to main content

AI Onboarding

Replaces the manual setup wizard for new company owners. Mia leads a multi-step conversation that creates the company, roles, integrations, and initial schedule template.

Where it lives​

  • Frontend route: /ai-onboarding → src/routes/AIOnboarding/
  • Main shell: src/routes/AIOnboarding/index.tsx (around line 26)
  • Page state hook: src/routes/AIOnboarding/hooks/useAiOnboardingPage
  • Backend orchestrator: functions/pivotAiAgent/onboarding-pipeline.ts
  • Prompts: functions/pivotAiAgent/onboarding-prompts.ts (large file — all system messages and step transitions)
  • Intent classifier: functions/pivotAiAgent/onboarding-intent.ts
  • Tools available: the 20-tool onboarding set (8 onboarding-only + 12 shared) — see Tool Catalog.

The onboarding pipeline is invoked from functions/pivotAiAgent/index.ts via runOnboardingPipeline(...) instead of the standard chat pipeline when the route is /ai-onboarding. The same pipeline serves the MIA Tips configuration UI, differentiated by a flow parameter.

Call pattern. Onboarding tools follow the standard rule — call internal HTTP endpoints with a forwarded token. create_company, for example, hits POST /companiesApi/companies and several PATCH /companies/{id} endpoints. The one twist: Mia uses her own privileged identity (getMiaIdToken(), custom claim isMiaAgent: true) for these requests so she can operate cross-tenant during new-customer setup; the new owner's identity travels via onBehalfOfUserId in the body so the company is owned by them, not Mia.

The tools fall back to direct Admin-SDK RTDB writes only for paths that aren't on the public API yet — AIOnboardingSessions/{userId} (session state), Users/{userId}/signupPhase (legacy flag), Companies/{cid}/businessProfile (not in the PATCH schema). This is tech debt to migrate, not an architectural choice. See Agent SDK: exceptions.

Flow​

Side-panel orchestration​

Some steps need richer UI than a chat bubble (selecting a POS, configuring a weekly schedule). The chat bubble Mia produces contains a link that the frontend interprets as a side-panel directive:

  • "Configure your POS" → frontend opens /account-settings/integrations?openModal=<name> in the side panel.
  • "Set your weekly schedule" → frontend opens /schedule?week=... in the side panel.

User completes the side-panel action, then continues the conversation.

Data produced​

PathCreated by
Companies/{companyId}Final step of onboarding
Companies/{companyId}/jobs/{jobId}Each role added
Employees/{companyId}/{employeeId}If integrations sync employees during onboarding
OnboardingState/{userId}Progress tracker (so reload doesn't lose state)
Companies/{companyId}/miaSettingsPersona + per-company AI config

Resumability​

The frontend persists progress to OnboardingState/{userId} after each step. A reload picks up at the last completed step. The conversation history (for the LLM) is reconstructed from this state plus a short transcript stored locally.