Legionis: Onboarding User Journey

Version: 1.0 Date: 2026-02-14 Owner: Product Manager Status: Draft Product: Legionis V2V Phase: Phase 3 -- Strategic Commitments Related: PRD v2.1, UX Concepts v1.0, DR-2026-001 (Pricing), Execution Plan v3.0

Design Philosophy

The onboarding flow follows three principles:

Value before configuration. Let users see what they're getting before asking them to set anything up. Show the agents, show the teams, show example output. Then ask for keys.

One decision at a time. Never present team selection + token connection + billing on the same screen. Each step is one screen, one decision.

First value in under 3 minutes. From Clerk signup completion to the first agent response, the clock is ticking. Every step that delays first value needs to justify its existence.

Pricing Context (Source of Truth)

Per the Agent Catalog and Stripe configuration (Feb 14):

Plan	Price	What You Get
Individual	$10/mo	1 user, 1 agent team
Team	$7/seat/mo (min 3)	Shared workspace, 1 agent team
Add-on Team	+$5/mo	Extra agent team (any)
Full Org	$25/mo	All 9 agent teams + Executive

All plans include a 30-day free trial. BYOK (Bring Your Own Key) model -- users provide their own Anthropic or OpenAI API key.

Managed billing option (under consideration): Legionis proxies Claude tokens with markup. Users pay per-use instead of managing their own API key. Simpler for non-technical users, higher cost.

The Flow: Screen by Screen

Overview

[Clerk Sign-Up] --> [Welcome + Role] --> [Team Showcase] --> [Team Selection] --> [Token Fork] --> [Dashboard + Guided First Chat]

Total: 6 screens from signup to first agent interaction. Estimated time: 2-3 minutes.

Screen 1: Clerk Sign-Up

What's on screen: Standard Clerk sign-up component (already built).

Google, Microsoft, LinkedIn, or email/password
Legionis branding: logo, tagline "Your AI workforce"
Dark theme (zinc-950 background, consistent with dashboard)

What happens after: Clerk webhook fires, user row created in Neon DB, redirect to Screen 2.

Route: /sign-up (existing)

No changes needed here. Clerk handles this well.

Screen 2: Welcome + Role Selection

Route: /onboarding (new)

What's on screen:

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│   Welcome to Legionis, [First Name].                        │
│                                                              │
│   Tell us about yourself so we can personalize               │
│   your experience.                                           │
│                                                              │
│   What best describes your role?                             │
│                                                              │
│   ┌───────────────┐  ┌───────────────┐  ┌───────────────┐  │
│   │  Product       │  │  Design       │  │  Engineering  │  │
│   │  Management    │  │               │  │               │  │
│   │  PM, PMM, VP   │  │  UX, UI,     │  │  Architect,   │  │
│   │  Product       │  │  Research     │  │  Developer    │  │
│   └───────────────┘  └───────────────┘  └───────────────┘  │
│                                                              │
│   ┌───────────────┐  ┌───────────────┐  ┌───────────────┐  │
│   │  Marketing     │  │  Leadership   │  │  Operations   │  │
│   │               │  │               │  │               │  │
│   │  Content, SEO, │  │  CEO, COO,   │  │  Finance,     │  │
│   │  Growth        │  │  VP, Director │  │  Legal, IT    │  │
│   └───────────────┘  └───────────────┘  └───────────────┘  │
│                                                              │
│   ┌───────────────────────────────────────────────────────┐ │
│   │  Other / Just exploring                                │ │
│   └───────────────────────────────────────────────────────┘ │
│                                                              │
│                                              [Continue ->]   │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Purpose: This does two things:

Personalizes team recommendation on the next screen (a PM sees Product Org highlighted, a designer sees Design Team highlighted)

Collects lightweight segmentation data for analytics (PostHog, when wired up)

UX details:

Single-select. Clicking one deselects others.
"Other / Just exploring" is always an option. Never force a role.
Selection is stored in the users table (role column -- add to schema).
No skip button. But "Other" serves as the skip path.

Data saved: users.role = selected role string.

Screen 3: Team Showcase (The "Wow" Moment)

Route: /onboarding/teams (new)

Purpose: This is where the user first understands what Legionis IS. Before asking them to choose, show them the full picture. This is marketing within the product.

What's on screen:

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│   Your AI Workforce                                         │
│   81 specialists. 9 teams. Built to work together.          │
│                                                              │
│   ┌──────────────────────────────────────────────────────┐  │
│   │  RECOMMENDED FOR YOU                                  │  │
│   │                                                       │  │
│   │  [Product Org]   13 agents, 61 skills                │  │
│   │  PM, VP Product, BizOps, PMM, CI, UX Lead...        │  │
│   │  "Write PRDs, create roadmaps, run PLT sessions"     │  │
│   │                                                 [->] │  │
│   └──────────────────────────────────────────────────────┘  │
│                                                              │
│   MORE TEAMS                                                │
│                                                              │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐     │
│   │ Design   │ │ Arch     │ │Marketing │ │ Finance  │     │
│   │ 7 agents │ │ 7 agents │ │16 agents │ │ 9 agents │     │
│   │          │ │          │ │          │ │          │     │
│   └──────────┘ └──────────┘ └──────────┘ └──────────┘     │
│                                                              │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐     │
│   │ Legal    │ │Operations│ │ Executive│ │ Corp Dev │     │
│   │ 8 agents │ │ 8 agents │ │ 2 agents │ │ 5 agents │     │
│   └──────────┘ └──────────┘ └──────────┘ └──────────┘     │
│                                                              │
│   ┌──────────┐                                              │
│   │ IT Gov   │  + All teams with Full Org ($25/mo)         │
│   │ 6 agents │                                              │
│   └──────────┘                                              │
│                                                              │
│                                              [Continue ->]   │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Interaction details:

The "Recommended for you" card is based on Screen 2 role selection:

- Product Management -> Product Org - Design -> Design Team - Engineering -> Architecture Team - Marketing -> Marketing Team - Leadership -> Product Org (with note: "includes CPO, VP Product, PLT gateway") - Operations -> Operations Team - Other -> Product Org (default recommendation)

Clicking any team card expands it inline to show:

- Full agent roster with emojis and short descriptions - 3 example tasks ("Ask me to..." prompts) - Gateway description ("Use @design to route automatically") - "This team includes [N] agents and [M] skills"

No selection happens here. This is a browse-only screen. The user is learning, not committing.

The "Full Org" callout at the bottom plants the seed for the premium plan.

Why this screen matters: Most users have never seen 81 AI agents organized into functional teams. This is the moment where Legionis differentiates from ChatGPT, Cursor, and every other AI tool. Let them explore. Let them be impressed. Don't rush this.

Screen 4: Team Selection + Plan

Route: /onboarding/select (new)

What's on screen:

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│   Choose your starting team                                  │
│   You'll have full access for 30 days. Add more anytime.    │
│                                                              │
│   ┌──────────────────────────────────────────────────────┐  │
│   │  [x] Product Org           RECOMMENDED               │  │
│   │  13 agents | 2 gateways | 61 skills                  │  │
│   │  $10/mo after trial                                   │  │
│   └──────────────────────────────────────────────────────┘  │
│                                                              │
│   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐       │
│   │ [ ] Design   │ │ [ ] Arch     │ │ [ ] Marketing│       │
│   │ 7 agents     │ │ 7 agents     │ │ 16 agents    │       │
│   │ $10/mo       │ │ $10/mo       │ │ $10/mo       │       │
│   └──────────────┘ └──────────────┘ └──────────────┘       │
│                                                              │
│   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐       │
│   │ [ ] Finance  │ │ [ ] Legal    │ │ [ ] Ops      │       │
│   │ 9 agents     │ │ 8 agents     │ │ 8 agents     │       │
│   │ $10/mo       │ │ $10/mo       │ │ $10/mo       │       │
│   └──────────────┘ └──────────────┘ └──────────────┘       │
│                                                              │
│   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐       │
│   │ [ ] Executive│ │ [ ] CorpDev  │ │ [ ] IT Gov   │       │
│   │ 2 agents     │ │ 5 agents     │ │ 6 agents     │       │
│   │ $10/mo       │ │ $10/mo       │ │ $10/mo       │       │
│   └──────────────┘ └──────────────┘ └──────────────┘       │
│                                                              │
│   ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
│                                                              │
│   OR                                                         │
│                                                              │
│   ┌──────────────────────────────────────────────────────┐  │
│   │  [ ] Full Organization                    BEST VALUE  │  │
│   │  All 81 agents | All 9 teams | All gateways          │  │
│   │  $25/mo after trial (save 60%+ vs individual teams)   │  │
│   └──────────────────────────────────────────────────────┘  │
│                                                              │
│   Your selection:                                            │
│   [Product Org]   $10/mo after 30-day free trial            │
│                                                              │
│                                    [Start Free Trial ->]     │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Interaction details:

Single team selection for the Individual plan: Pick one team, $10/mo after trial.
Full Org option is always visible as the "OR" alternative: all teams, $25/mo after trial.
The recommended team (from Screen 3) is pre-selected. User can change.
Selecting a team changes the summary bar at the bottom in real-time.
Users can select multiple individual teams: each additional team after the first is +$5/mo (the add-on pricing). The summary bar updates: "Product Org + Design: $15/mo after trial."
If they select 3+ teams, a nudge appears: "Tip: Full Org gives you all 9 teams for $25/mo" (since 3 teams at $10 + $5 + $5 = $20, and 4+ exceeds $25).

Why not Team plan here? The Team plan ($7/seat/mo, min 3 seats) is for multi-user workspaces. During solo onboarding, we default to Individual. The Team plan appears in Settings > Billing after they've experienced the product, or if they invite collaborators later.

No credit card required. This is a free trial. Stripe trial starts when they click "Start Free Trial" -- Clerk user linked to Stripe customer, trial_end set to 30 days from now. No payment method collected until trial end approaches (Stripe handles this via email).

Data saved:

subscriptions row: plan = selected team(s), status = trialing, trial_ends_at = now + 30d
users.selected_teams = array of team keys (add to schema)

Screen 5: Token Connection (The Fork)

Route: /onboarding/connect (new)

This is the critical UX fork. The user needs an AI provider key to actually run agents. We present two paths clearly without making one feel "wrong."

What's on screen:

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│   Last step: Connect your AI                                 │
│   Legionis agents are powered by Claude or GPT.              │
│   Choose how you'd like to connect.                          │
│                                                              │
│   ┌──────────────────────────┐  ┌──────────────────────────┐│
│   │                          │  │                          ││
│   │  Use My Own Key          │  │  Let Legionis Handle It  ││
│   │  ─────────────           │  │  ──────────────────────  ││
│   │                          │  │                          ││
│   │  Best if you already     │  │  Best if you want the    ││
│   │  have an Anthropic or    │  │  simplest setup. We      ││
│   │  OpenAI account.         │  │  handle everything.      ││
│   │                          │  │                          ││
│   │   You control your      │  │   No API key needed     ││
│   │    usage and billing     │  │  * Usage-based pricing   ││
│   │   Use your existing     │  │   Pay as you go         ││
│   │    volume discounts      │  │  * Start immediately     ││
│   │  * No markup             │  │                          ││
│   │                          │  │  Pricing: ~$0.XX per     ││
│   │  [Choose This ->]        │  │  agent interaction       ││
│   │                          │  │                          ││
│   └──────────────────────────┘  │  [Choose This ->]        ││
│                                  │                          ││
│                                  └──────────────────────────┘│
│                                                              │
│   Not sure? You can change this anytime in Settings.         │
│                                                              │
│   ┌──────────────────────────────────────────────────────┐  │
│   │  [Skip for now -- I'll set this up later]             │  │
│   └──────────────────────────────────────────────────────┘  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Path A: "Use My Own Key" (BYOK)

Clicking this expands inline (or navigates to a sub-step):

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│   Connect your API key                                       │
│                                                              │
│   [Anthropic tab]  [OpenAI tab]                             │
│                                                              │
│   Paste your Anthropic API key:                              │
│   ┌──────────────────────────────────────────────┐          │
│   │ sk-ant-...                                    │          │
│   └──────────────────────────────────────────────┘          │
│                                                              │
│   [Validating...]  or  [Valid key -- Claude Opus available]  │
│                                                              │
│   Your key is encrypted at rest and never logged.            │
│   Get a key from console.anthropic.com/settings/keys         │
│                                                              │
│                                    [Save & Continue ->]      │
│                                                              │
└──────────────────────────────────────────────────────────────┘

On paste, the system makes a lightweight API call (e.g., list models) to validate the key.
Show which models are available on their key (Haiku, Sonnet, Opus).
Key is encrypted and stored in api_keys table.

Path B: "Let Legionis Handle It" (Managed Billing)

Clicking this shows:

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│   Managed AI Billing                                         │
│                                                              │
│   We'll provide AI access so you don't need your own key.    │
│                                                              │
│   How it works:                                              │
│   1. You use agents normally                                 │
│   2. AI usage is metered and billed monthly                  │
│   3. Added to your Legionis subscription                     │
│                                                              │
│   Estimated cost:                                            │
│   * Light use (5-10 interactions/day): ~$15-25/mo            │
│   * Moderate use (20-40/day): ~$50-80/mo                     │
│   * Heavy use: scales with usage                             │
│                                                              │
│   [Enable Managed Billing ->]                                │
│                                                              │
│   You can switch to your own key anytime.                    │
│                                                              │
└──────────────────────────────────────────────────────────────┘

NOTE: Managed billing may not be available at MVP launch. If not ready, this path shows:

   Managed billing is coming soon.
   For now, you'll need an Anthropic or OpenAI API key.   [Set up my own key ->]     [Notify me when available ->]

Path C: "Skip for now"

User lands on the dashboard. A persistent but dismissible banner appears:

┌──────────────────────────────────────────────────────────────┐
│ Connect an AI key to start using agents.  [Set up now ->]    │
└──────────────────────────────────────────────────────────────┘

Agents are visible but disabled. Attempting to chat shows: "Connect an API key in Settings to start." This is acceptable -- some users want to browse the interface before committing a key.

Why token AFTER team selection (not before)?

Three reasons:

Emotional sequence: Choose your team (exciting) before pasting a key (tedious). If we lead with "paste your API key," we lose users who came to see the product, not configure infrastructure.

The skip path works: If they skip token setup, they can still explore the dashboard, see agents, read descriptions, browse teams. They just can't chat. This is still value.

Managed billing needs context: Users need to know what they're paying for (their selected team) before deciding how to pay for AI usage.

Screen 6: Dashboard + Guided First Chat

Route: /dashboard (existing, enhanced)

After completing onboarding, the user lands on the dashboard. But it's not the empty dashboard we have today. The first-time experience is special.

What's on screen (first visit only):

┌──────────────────────────────────────────────────────────────┐
│ [Sidebar]                                                    │
│ ┌────────┐  ┌────────────────────────────────────────────┐  │
│ │        │  │                                            │  │
│ │  Your  │  │  You're all set. Let's try something.      │  │
│ │  Team: │  │                                            │  │
│ │        │  │  Here are 3 things you can do right now:    │  │
│ │ Product│  │                                            │  │
│ │  Org   │  │  ┌──────────────────────────────────────┐  │  │
│ │        │  │  │  "Write a PRD for [your feature]"    │  │  │
│ │ ────── │  │  │  Uses: PM agent + /prd skill          │  │  │
│ │ PM     │  │  │  Time: ~2 minutes                     │  │  │
│ │ VP Prod│  │  │                        [Try this ->]  │  │  │
│ │ BizOps │  │  └──────────────────────────────────────┘  │  │
│ │ Dir PM │  │                                            │  │
│ │ Dir PMM│  │  ┌──────────────────────────────────────┐  │  │
│ │ ...    │  │  │  "Review my product strategy"         │  │  │
│ │        │  │  │  Uses: VP Product + context layer     │  │  │
│ │        │  │  │                        [Try this ->]  │  │  │
│ │        │  │  └──────────────────────────────────────┘  │  │
│ │        │  │                                            │  │
│ │        │  │  ┌──────────────────────────────────────┐  │  │
│ │        │  │  │  "Help me decide between X and Y"    │  │  │
│ │        │  │  │  Uses: @product gateway (Meeting)     │  │  │
│ │        │  │  │                        [Try this ->]  │  │  │
│ │        │  │  └──────────────────────────────────────┘  │  │
│ │        │  │                                            │  │
│ │        │  │  Or just type anything below.              │  │
│ │        │  │                                            │  │
│ │        │  │  ┌──────────────────────────────────────┐  │  │
│ │        │  │  │ Type here or use /skill, @agent...   │  │  │
│ │        │  │  └──────────────────────────────────────┘  │  │
│ │        │  │                                            │  │
│ └────────┘  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

The suggested prompts are personalized based on role (Screen 2) and team (Screen 4):

Role	Suggested Prompts
Product Management	"Write a PRD", "Create a roadmap", "Run a PLT session"
Design	"Review my design system", "Create user personas", "UI component specs"
Engineering	"Review API architecture", "Security threat model", "Cloud infra plan"
Marketing	"Write landing page copy", "Plan a campaign", "SEO keyword analysis"
Leadership	"Portfolio status review", "Strategic planning session", "QBR deck"
Operations	"Process optimization review", "Risk assessment", "Program governance"
Other	"Write a PRD", "Help me decide something", "What can you do?"

Clicking "Try this" pre-fills the chat input with the prompt text and auto-submits. The user sees their first agent response streaming in real-time. This is the first value moment.

After the first interaction, the guided prompts collapse and the dashboard shows the normal conversation interface. The sidebar shows their team's agents. The user is onboarded.

State Transitions & Edge Cases

Onboarding State Machine

SIGNED_UP -> ROLE_SELECTED -> TEAMS_VIEWED -> TEAM_SELECTED -> TOKEN_CONNECTED -> ONBOARDED




                                                   +-> TOKEN_SKIPPED -> ONBOARDED (limited)

Store state in users.onboarding_step (enum). The onboarding route reads this state and redirects to the correct screen. If a user navigates directly to /dashboard before completing onboarding, redirect to their current onboarding step.

What if they close the browser mid-onboarding?

When they return:

If they completed team selection (Screen 4), skip to Screen 5 (token).
If they completed role selection (Screen 2), skip to Screen 3 (showcase).
State is persisted in the DB, not in browser storage.

What if they want to change their team later?

Settings > Subscription > "Change team" link. This goes to Stripe billing portal for plan changes. Also accessible from the sidebar (team name is clickable).

What about the Team plan (multi-user)?

The Team plan ($7/seat/mo) is not part of the solo onboarding flow. It appears:

In Settings > Billing (post-onboarding)

When a user clicks "Invite team member" (triggers an upgrade prompt)

On the marketing website's pricing page

What about returning users who already have a subscription?

If users.onboarding_step = ONBOARDED, always go to /dashboard. Skip the onboarding flow entirely.

Token Fork: Decision Matrix

User Signal	Recommend	Rationale
Role = Engineering	BYOK	Engineers likely already have API keys
Role = Product Management	Either (neutral)	Mixed -- some have keys, some don't
Role = Design, Marketing, Ops	Managed billing (when available)	Less likely to have API accounts
Role = Leadership	Managed billing (when available)	Definitely not managing API keys
Role = Other	Neutral	Don't assume

On Screen 5, subtly highlight the recommended path based on role. Not a hard push -- just a "Recommended for you" badge on one of the two options.

Metrics & Success Criteria

Metric	Target	Measurement Point
Signup-to-team-selection	>80%	Screen 2 -> Screen 4 conversion
Team-selection-to-token	>60%	Screen 4 -> Screen 5 completion
Token-setup-to-first-chat	>90%	Screen 5 -> first agent interaction
Overall signup-to-first-value	>45%	Clerk signup -> first agent response
Time to first value	<3 minutes	Timestamp delta
Skip rate on token setup	<30%	"Skip for now" clicks / total
Managed billing uptake	[TBD]	Path B selections / total (when launched)

Schema Changes Required

Add to src/lib/db/schema.ts:

// Add to users table
role: text('role'),                    // From Screen 2
selectedTeams: text('selected_teams'), // JSON array of team keys
onboardingStep: text('onboarding_step').default('signed_up'),
// Enum: signed_up | role_selected | teams_viewed | team_selected | token_connected | onboarded// Add to api_keys table (if not already present)
validated: boolean('validated').default(false),
validatedAt: timestamp('validated_at'),
availableModels: text('available_models'), // JSON array: ['haiku', 'sonnet', 'opus']

Implementation Notes

New Routes

Route	Type	Description
`/onboarding`	Page (server)	Reads onboarding_step, renders correct screen
`/onboarding/teams`	Page (server)	Team showcase
`/onboarding/select`	Page (client)	Team selection + plan calculation
`/onboarding/connect`	Page (client)	Token fork (BYOK vs managed)
`/api/onboarding/role`	API route	POST: saves role selection
`/api/onboarding/team`	API route	POST: saves team selection, creates Stripe trial
`/api/onboarding/validate-key`	API route	POST: validates API key against provider

Middleware Update

Update src/middleware.ts to:

Check onboarding_step for authenticated users

Redirect to /onboarding if step != onboarded

Allow /onboarding/* routes for non-onboarded users

Block /dashboard for non-onboarded users (redirect to onboarding)

Component Reuse

Team cards from Screen 3/4 should be a shared component
The token input from Screen 5 is very similar to the existing api-keys/page.tsx -- extract into a shared component
Plan summary bar from Screen 4 is a new component

Sequence: What Happens When

Step	User Action	System Action
1	Clicks "Sign up"	Clerk creates account, webhook creates DB user
2	Selects role	`users.role` updated, `onboarding_step` = role_selected
3	Browses teams	`onboarding_step` = teams_viewed (on "Continue")
4	Selects team, clicks "Start Free Trial"	Stripe customer created, trial subscription started, `onboarding_step` = team_selected
5a	Pastes API key	Key validated, encrypted, stored. `onboarding_step` = token_connected, then = onboarded
5b	Chooses managed billing	Managed billing flag set. `onboarding_step` = token_connected, then = onboarded
5c	Clicks "Skip for now"	`onboarding_step` = onboarded (limited). Dashboard banner shown.
6	Lands on dashboard	First-time guided prompts shown. Clicking one creates first conversation.
6+	First agent response streams in	First value achieved. Guided prompts collapse. Normal dashboard experience.

Open Questions

Managed billing pricing: What's the markup? This needs a pricing decision before we can populate Screen 5 Path B with real numbers. Recommend a separate pricing exercise for managed billing.

Team trial scope: During the 30-day trial, does the user get access to ONLY their selected team, or ALL teams? I recommend ALL teams during trial (let them experience the full product), then narrow to their selected team when trial converts. This maximizes wow factor and drives Full Org upgrades.

Google Drive connection: Where does this fit? Currently not in the onboarding flow. My recommendation: defer to post-onboarding. Add a prompt after the first conversation: "Want to save this to Google Drive? Connect your storage." Storage setup is friction that doesn't block first value.

IT Governance team visibility: The IT Governance team is niche. Should it be visible in the main team grid, or collapsed under "More teams"? Leaning toward keeping it visible -- 10 cards in a grid is manageable, and hiding things feels dishonest.