In-App Onboarding Wizard

Pre-requisite: The tenant has completed self-signup and payment. This doc covers what happens inside the Dashboard after the account is created.

Full Flow

Self-Signup + Payment (see self-signup.md)
    → Contract Acceptance Gate
        → 6-Step Onboarding Wizard (/onboarding)
            → Setup Chain (background agents)
                → Workspace Active

Part 1 — Contract Acceptance Gate

After payment, before accessing the Dashboard, the user sees a contract acceptance modal. Auth middleware checks tenants.contract_accepted_on IS NOT NULL on every request — until accepted, all routes redirect here.

On accept: contracts.accepted_on, contracts.accepted_by, contracts.accepted_ip set; tenants.contract_accepted_on updated. Redirect to /onboarding.

Part 2 — In-App Onboarding Wizard

A 7-step wizard at /onboarding. Collects the information needed to generate the client context file and activate agents. Every step has a Skip option — users can return to fill in details later.

The dashboard layout gate (layout.tsx) redirects any authenticated user to /onboarding if tenant.onboardingCompletedAt is null.

Steps Overview

Step 1 — Connect Channels

Links marketing channels so Leadmetrics can pull real performance data. Channels open in a new tab — the wizard saves state so the user can come back and click Continue.

Supported channels: Facebook, Instagram, LinkedIn, Google Analytics, Google Search Console, Google Ads, Google Business Profile, Bing Webmaster Tools, GitHub, WordPress, Website.

Step 2 — Brand Voice

Defines how the brand sounds across all AI-generated content.

Saves to brand_voice table. Used in every agent prompt that generates copy.

Step 3 — Brand Assets

Colors, fonts, and visual style that guide AI-generated content.

Auto-prefill from website crawl: When the tenant provides a website URL during signup, the crawler runs extractBrandAssets() on the homepage before any DOM mutation. If brand signals are detected (confidence > 0), they are written to brand_assets — but only if primaryColor is currently null (never overwrites manual input).

Because the crawl runs in the background after signup and the wizard loads immediately, the Brand Assets step fetches the latest DB state on mount via the getBrandAssets() server action. When data is found, an indigo banner reads “Prefilled from your website — review and adjust anything that looks off.”

A “Refresh from website” button is always visible in the step header. On click:

• If brand data is already in the DB → populates the form immediately.
• If nothing in DB yet → automatically queues a fresh crawl via POST /tenant/v1/channels/:id/webcrawl/start and shows “Crawl queued — hit Refresh again when done.”

Extraction priority (in order):

1. CSS custom properties on :root — hex, rgb(), and HSL (--primary: 239 84% 67%) formats all handled
2. Computed styles on all header/nav buttons and links (scans every element, skips transparent ghost buttons)
3. Broader fallback: hero/banner/CTA sections, main > div backgrounds
4. Google Fonts <link> hrefs + @import in <style> tags
5. @font-face names in inline <style> tags (catches Next.js next/font inlined fonts)
6. Computed font-family on body / h1 (non-system fonts only)

Code: packages/agents/src/utils/brand-extractor.ts

Step 4 — Documents

Document upload is planned but not yet built. The step shows a placeholder. Users can upload brand docs from Settings → Documents after setup.

Step 5 — Baseline (Current Performance)

Current marketing metrics used to set realistic goals in the strategy.

Website & SEO: monthly visitors, organic clicks, avg search position, monthly leads, top keywords.

Paid Advertising: toggle + platform selection (Google Ads, Meta Ads, LinkedIn Ads) + per-platform metrics (monthly spend, CPL, monthly leads).

Social Media: toggle + platform selection (LinkedIn, Facebook, Instagram, GBP) + per-platform metrics (followers, engagement rate; GBP uses impressions + calls).

Auto-filled from connected channels — on mount, calls getBaselinePrefill() server action which reads from connected channel data. Shows a green banner listing which channels were synced, with a Refresh button. Falls back to manual entry if channels can’t be fetched.

Saves to brand_voice table (baselineData JSONB field).

Step 6 — Budget

Collects the client’s marketing budget so the strategy writer can produce a realistic Budget & Resource Allocation table.

An amber callout explains that a budget acceptance prompt will appear on the strategy review page after generation — the client can confirm or adjust before approving.

Saves to tenant_strategy_config table: monthly_budget (null when flexible), budget_flexible, budget_horizon. The budget_confirmed flag (also on this model) is set later via the strategy review acceptance prompt.

Strategy generation modes (triggered from the strategy page, informed by this step):

• “Generate with Ideal Budget” — ignores monthly_budget; AI proposes optimal allocation for goals.
• “Generate with My Budget” — injects monthly_budget as a hard constraint; AI works within it and notes trade-offs.

Step 7 — Launch

Summary screen. Clicking Generate My Context calls completeOnboarding() which:

1. Sets tenant.onboardingCompletedAt = now()
2. Enqueues the setup chain via BullMQ

The setup chain then runs automatically in the background.

Part 3 — Setup Chain (Background Agents)

After the wizard completes, three agents run sequentially via BullMQ:

Implemented in: packages/agents/src/workers/setup.worker.ts

Status transitions: pending → generating → completed → approved

When the context-file-writer completes, a context_ready email is sent to the tenant admin. Template slug: context_ready. Variables: firstName, companyName, contextUrl, currentYear.

Approval flow

1. Admin logs into dashboard → navigates to Context page
2. Amber “Review and approve” banner with Approve Context button is shown
3. Admin clicks Approve → status updated to "approved" via server action
4. All agents now use this context file in every prompt

Generated context file structure

## Company Overview
## Products & Services
## Target Audience
## Brand Voice & Tone
## Competitors
## Geographic Focus
## Key Messages
## What NOT to Do

Sections with insufficient data are marked: [Requires update — visit Settings → Context]

Part 4 — Post-Onboarding

After the context file is approved:

• User lands on / (main dashboard)
• All configured agents are active
• Empty-state guidance: “Submit Your First Campaign →”

Time from registration to first campaign submission: < 10 minutes for a motivated user.