Legionis UX Journey Audit V3

Full User Journey Review: Alignment with General-Purpose AI Workforce Positioning

Document ID: DOC-2026-033 Owner: UX Lead Date: 2026-02-17 Status: Active Product: Legionis Scope: End-to-end journey audit across all existing components Supersedes: UX Concepts v1.0 (DOC-2026-017), UX Guidelines v1.0

Executive Summary

This audit maps every user touchpoint from discovery to expert usage, identifying exactly what needs to change in built components given five alignment shifts: (1) repositioning from "Product Org OS" to general-purpose AI workforce, (2) agent roster expansion from 13 to 81, (3) new team-based pricing model, (4) brand token migration from zinc/teal to stone/amber, and (5) Week 5 features (BYOT, context layer, conversation persistence).

Total components audited: 18 files across 5 categories Critical changes (P0): 12 items that block Week 5 delivery Alignment changes (P1): 23 items needed for brand/positioning coherence Polish changes (P2): 9 items for post-Week 5 refinement

Table of Contents

1. End-to-End Journey Map

Stage 1: Discovery (Landing Page to Signup Intent)

Current state: No landing page built in the app yet. Auth pages (sign-in/page.tsx, sign-up/page.tsx) show bare Clerk components centered on bg-zinc-950. The root layout.tsx metadata says "Legionis - Your AI Workforce" (correct), but the description mentions "Product, engineering, design, marketing and more" which is acceptable for general-purpose framing.

Required changes:

• Auth pages background: bg-zinc-950 must become bg-stone-900 (see token migration)
• Clerk theme: Currently uses dark base theme. Needs custom Clerk appearance with stone/amber token overrides for buttons, links, and focus rings
• Sign-up page should include a brief tagline above the Clerk component: "Assemble your AI workforce" or equivalent, using Space Grotesk display font
• No old "product org" copy exists in auth pages (clean)

Priority: P1 (brand alignment, not blocking Week 5 features)

Stage 2: Registration (Sign-Up via Clerk)

Current state: Clerk handles the entire registration flow. Auth layout is a passthrough <>{children}. Sign-up page is a centered Clerk component on zinc-950 background.

Required changes:

• Clerk appearance customization needs brand tokens: primary color should be amber (#d97706), background stone-900, surfaces stone-800
• Social auth buttons (Google, Microsoft, LinkedIn) remain Clerk-managed
• Post-signup redirect: currently goes straight to /dashboard. Week 5 needs this to redirect to an onboarding flow instead (see Stage 3)
• No copy changes needed in Clerk components (they are configuration-driven)

Priority: P0 for redirect change (blocks onboarding flow), P1 for brand tokens

Stage 3: Onboarding (Connect Storage, Connect API Key, Workspace Setup)

Current state: No onboarding flow exists. After signup, users land directly on the dashboard chat interface. Storage connection exists only as a settings page (settings/storage/page.tsx). API key setup exists only as a settings page (settings/api-keys/page.tsx). The text "V2V context structure" in the storage page is product-org-specific terminology.

Required changes:

• NEW onboarding wizard needed (see Section 4 for full redesign)
• Post-signup redirect must go to /dashboard/onboarding (new route)
• Steps: Welcome -> Connect API Key (required) -> Connect Storage (recommended) -> Choose Your First Team (progressive disclosure of 81 agents) -> First Interaction
• Storage page copy: "V2V context layer" language must become domain-neutral. Replace "V2V context structure" with "workspace structure" or "organizational memory"
• Storage page: References to "Legionis Workspace" as default folder name are fine
• API keys page: Copy is already neutral ("Bring your own AI provider keys") -- good
• "V2V context layer" references in the folder structure preview must be generalized

Priority: P0 (onboarding is a Week 5 requirement)

Stage 4: First Value (First Skill/Agent Use, First Document Created)

Current state: EmptyState in chat-container.tsx shows:

• Greeting: "Welcome, [name]" (good)
• Subtitle: "Your AI workforce, ready to deploy." (good for general-purpose)
• Four hint cards with product-org examples:

• Hint cards use border-zinc-800, text-zinc-200, text-zinc-500, text-zinc-600

• Hint card examples must become domain-diverse:

• Subtitle could be: "Your AI workforce, ready to deploy." (already good)
• Hint card examples should dynamically match the user's selected "starter team" from onboarding
• All zinc tokens need stone migration (see Component Change Register)
• Skill count reference: "Type / to browse 80+ skills" -- currently correct

Priority: P1 (copy alignment + brand tokens)

Stage 5: Habit Formation (Week 1 -- Skill Discovery, Context Accumulation)

Current state: The skill palette (skill-palette.tsx) groups skills by V2V phase category. The agent selector (agent-selector.tsx) groups agents by team with TEAM_ORDER defining 10 groups. Chat input placeholder says "Message your AI workforce... (/ for skills, @ for agents)" (good).

Required changes:

• Skill palette: V2V phase grouping is product-org-specific. For general-purpose users, a more intuitive grouping would be by FUNCTION (Strategy, Finance, Legal, Marketing, Product, etc.) or by ACTION TYPE (Create, Analyze, Review, Plan). The current phase labels ("Strategic Foundation", "Strategic Decisions", etc.) will confuse non-product users.
• Skill palette: Add "Recently Used" section at top (from UX concepts, not yet implemented)
• Skill palette: Currently max-h-64 -- with 80+ skills this needs to be taller or have better section collapsing
• Agent selector: Team grouping is already implemented correctly with 10 teams. The structure works for 81 agents. But the flat list within each team section could become long (Marketing team has 16 agents). Need sub-grouping or role-based filtering within teams.
• Selected state: bg-teal-600/20 text-teal-300 in both palettes needs amber migration
• Sticky headers: bg-zinc-800 needs stone migration

Priority: P1 (functional for Week 5 as-is, but confusing for non-product users)

Stage 6: Team Discovery (Discovering 81 Agents Across 9 Teams)

Current state: The agent selector already has team-based grouping via TEAM_ORDER array with 10 entries. The API endpoint /api/agents serves agent metadata including source, team, emoji, displayName, and description. The selector opens as a dropdown above the input area with max-h-72.

Required changes:

• Progressive team discovery: When user first encounters the agent selector, don't show all 81 agents at once. Instead:

• Team gateway shortcuts: At the top of each team section, show the gateway (e.g., "@design -- routes to the right specialist") as a recommended entry point for users who don't know which specific agent they need
• Search behavior: Current fuzzy search across id, displayName, and emoji is good but should also search description (already partly there -- description shown but not fully searched)
• max-h-72 (288px) is too short for 81 agents. Increase to max-h-96 (384px) or use a modal/panel for the full roster
• Auto-routing explanation: Add a subtle footer in the selector: "Not sure who to pick? Just describe what you need -- we'll route to the right agent."

Priority: P0 (81 agents in current flat-per-team list is information overload)

Stage 7: BYOT Setup (Connecting API Keys, Understanding Cost Model)

Current state: API keys page (settings/api-keys/page.tsx) shows two provider cards (Anthropic and OpenAI). Each card shows: provider name, description, docs link, configured/not-configured status badge, key input or masked key display, save/remove buttons. All copy is neutral and accurate.

Required changes:

• This page needs to also appear as an onboarding step (see Stage 3 / Section 4)
• Add a brief explanation of the BYOT cost model: "You pay your AI provider directly. Legionis subscription covers the platform -- AI usage is on your own API key."
• Add a "Test Key" button after saving -- validates the key works before the user tries to chat
• Consider showing estimated cost per operation: "Typical operation: ~$0.01-0.10 depending on complexity and model"
• Status badge: bg-teal-500/10 text-teal-400 needs amber migration: bg-amber-500/10 text-amber-400
• Focus ring on input: focus:border-teal-500 needs focus:border-amber-600
• Save button: bg-teal-600 hover:bg-teal-500 needs bg-amber-600 hover:bg-amber-500
• Docs link: text-teal-500 hover:text-teal-400 needs text-amber-500 hover:text-amber-400
• Card borders: border-zinc-800 bg-zinc-900 needs border-stone-700 bg-stone-800

Priority: P0 (BYOT is Week 5 feature), P1 for token migration

Stage 8: Upgrade Decision (Free to Pro/Team/Org, Understanding New Pricing)

Current state: Billing page (billing-client.tsx) shows:

• Current plan status card
• 4-column plan grid: Individual ($10/mo), Team ($7/seat/mo), Add-on Team (+$5/mo), Full Org ($25/mo)
• Feature lists per plan with teal checkmarks
• "Start free trial" / "Manage Subscription" buttons
• Highlighted plan: Full Org with border-teal-600 bg-teal-950/20
• Footer: "All plans use BYOT (Bring Your Own Token)..."
• Status badges use teal and standard semantic colors

• Pricing is already updated to the new model ($10/$7/+$5/$25). No structural changes needed here.
• Feature descriptions could be more domain-diverse. Instead of "39 agents, 61 skills" for Individual, consider "Product Org team (13 agents, 61 skills)" to make it clear what's included vs. add-on
• The Add-on card lists "Design, Arch, Marketing, Finance, or Legal" -- this is correct and domain-diverse
• Highlighted plan border: border-teal-600 -> border-amber-600
• Highlighted plan background: bg-teal-950/20 -> bg-amber-950/20
• Highlighted CTA: bg-teal-600 hover:bg-teal-500 -> bg-amber-600 hover:bg-amber-500
• Checkmarks: text-teal-500 -> text-amber-500
• Current plan badge: bg-teal-600/20 text-teal-400 -> bg-amber-600/20 text-amber-400
• Trial status badge: bg-teal-500/10 text-teal-400 -> bg-amber-500/10 text-amber-400
• All border-zinc-800 bg-zinc-900 -> border-stone-700 bg-stone-800

Priority: P1 (pricing structure is correct, just needs token migration)

Stage 9: Power Usage (Keyboard Shortcuts, Batch Operations, Meeting Mode)

Current state: Chat input supports Enter to send, Shift+Enter for newline, Escape to dismiss palettes. Skill palette and agent selector support arrow key navigation. No Cmd+K global shortcut implemented yet (the skill palette only opens via / trigger in the input). No Meeting Mode rendering exists in the current message component.

Required changes:

• Cmd+K global shortcut: Not implemented. Need to add a global keyboard listener that opens the skill palette as a centered modal (not just above the input). This is the power user's primary entry point.
• Meeting Mode rendering: The message.tsx component renders all assistant messages the same way. When a PLT or gateway response contains multiple agent voices, it should render with:

• Keyboard shortcut help: No Cmd+/ shortcut help panel exists
• Stop generating button: Not visible in current UI during streaming. Only a "Thinking..." indicator shows.

Priority: P1 (Cmd+K), P2 (Meeting Mode rendering, keyboard help)

Stage 10: Context Compounding (3+ Months, Switching Cost Established)

Current state: No context panel exists. The file explorer (file-tree.tsx, file-preview.tsx) allows browsing Drive files but has no dedicated context dashboard. The sidebar shows file explorer and settings links but no context section. ROI tracking is not visible in the UI.

Required changes:

• Context panel (right sidebar): New component needed (see Section 3). Should surface:

• Status bar: Need a bottom status bar showing:

• Portfolio view: A dedicated route /dashboard/context for the full context dashboard (decisions, bets, feedback, learnings in tabbed view)
• File explorer folder icon color: text-teal-400 -> text-amber-400

Priority: P0 for context panel (Week 5 feature), P2 for full context dashboard

2. Component Change Register

2.1 Root Layout: app/layout.tsx

Copy changes: None needed. Description is already general-purpose.

2.2 Dashboard Layout: app/dashboard/layout.tsx

Structural change: Week 5 introduces the context panel as a right sidebar, requiring the dashboard layout to become a three-column flex container with the right panel togglable via state.

2.3 Sidebar: components/shared/sidebar.tsx

Copy changes: None. Sidebar text is generic ("Legionis", "Conversations", "File Explorer", "Settings").

Structural changes: The conversations placeholder must be replaced with a real conversation list component that loads from the database and supports:

• List of past conversations with title (first message or auto-generated) and timestamp
• Active conversation highlighted
• Click to switch conversations
• Right-click or swipe for delete/rename
• "New conversation" creates a fresh conversation and navigates to it

2.4 Chat Container: components/chat/chat-container.tsx

Copy changes needed:

• HintCard example 1: "Help me write a PRD for authentication" -> "Help me draft a project plan"
• HintCard example 2: "/prd, /decision-record, /business-case" -> "/prd, /campaign-brief, /business-case, /contracts-review"
• HintCard example 3: "@competitive-intelligence, @bizops" -> "@pm, @cfo, @general-counsel, @cmo"
• HintCard example 4: "Analyze our pricing strategy" -> "Help me think through our go-to-market"

2.5 Message: components/chat/message.tsx

Structural changes:

• Agent identity rendering: When the assistant response includes an agent identity header (emoji + display name), the message component should render it with a subtle left-border in the agent's accent color and the agent emoji as an avatar
• Meeting Mode: Multi-agent responses need a distinct rendering path with collapsible sections (see Section 3.4)

2.6 Chat Input: components/chat/chat-input.tsx

2.7 Skill Palette: components/chat/skill-palette.tsx

2.8 Agent Selector: components/chat/agent-selector.tsx

2.9 Tool Indicator: components/chat/tool-indicator.tsx

2.10 Markdown Renderer: components/chat/markdown.tsx

2.11 File Tree: components/explorer/file-tree.tsx

2.12 File Preview: components/explorer/file-preview.tsx

2.13 Settings Layout: app/dashboard/settings/layout.tsx

2.14 Settings Profile: app/dashboard/settings/page.tsx

2.15 Settings Billing: app/dashboard/settings/billing/billing-client.tsx

Copy changes:

• Individual features: "39 agents, 61 skills" -> "Product Org team: 13 agents, 61 skills" (clearer about what's included)
• Consider adding "BYOT: you control AI costs" prominently in each card

2.16 Settings API Keys: app/dashboard/settings/api-keys/page.tsx

(Token changes listed in Stage 7 above)

2.17 Settings Storage: app/dashboard/settings/storage/page.tsx

Copy changes:

• Line 208-209: "Legionis will create the V2V context structure inside it." -> "Legionis will create the workspace structure inside it."
• Line 265: "including the V2V context layer (decisions, bets, feedback, learnings)" -> "including organizational memory (decisions, bets, feedback, learnings)"

2.18 Auth Pages: app/(auth)/sign-in/page.tsx, app/(auth)/sign-up/page.tsx

2.19 Globals CSS: app/globals.css

3. New Components Needed for Week 5

3.1 Conversation List (Sidebar)

Location: components/shared/conversation-list.tsx Replaces: Placeholder in sidebar.tsx

Requirements:

• Fetch conversations from /api/conversations (new API route)
• Display: truncated title (auto-generated from first message), relative timestamp ("2h ago", "Yesterday")
• Active conversation highlighted with bg-stone-700
• Click to switch (loads conversation messages)
• Hover shows a muted delete/rename icon
• Grouped by date: "Today", "Yesterday", "This Week", "Older"
• Scroll area matching sidebar style
• Empty state: "Start a conversation to see it here"

Priority: P0

3.2 Context Panel (Right Sidebar)

Location: components/shared/context-panel.tsx Integrated into: app/dashboard/layout.tsx

Requirements:

• Toggle-able right panel (320px width on desktop)
• Keyboard shortcut: Cmd+] to toggle
• Sections:

• Collapsed state: On screens narrower than 1280px, hidden by default. Accessible via toggle button.
• Stone palette: bg-stone-800 border-stone-700
• Section headers in text-stone-400 with font-display (Space Grotesk)

Priority: P0

3.3 Onboarding Flow

Location: app/dashboard/onboarding/page.tsx + components/onboarding/ Steps (see Section 4 for full redesign):

Priority: P0

3.4 Meeting Mode Renderer

Location: components/chat/meeting-mode.tsx Used by: message.tsx when detecting multi-agent responses

Requirements:

• Detects structured gateway/PLT responses (look for agent emoji headers pattern)
• Renders each agent section in a collapsible card with:

• After individual agents: Alignment, Tension, Synthesis sections with distinct icons and subtle background tints
• Aggregate ROI line at bottom

3.5 Token Count / Usage Display (Status Bar)

Location: components/shared/status-bar.tsx Integrated into: app/dashboard/layout.tsx

Requirements:

• Thin bar at bottom of dashboard layout
• Shows: Operation count (N / limit), session token cost estimate, context health dot
• Upgrade prompt at 80%: amber warning text
• At 100%: blocks input with upgrade CTA
• Stone palette: bg-stone-800 border-stone-700 text-stone-400

3.6 Enhanced Agent Selector (Modal Mode)

Location: Update components/chat/agent-selector.tsx or create components/chat/agent-roster-modal.tsx

Requirements:

• When invoked via Cmd+Shift+A or clicking a "Browse all agents" link, opens as a centered modal instead of inline dropdown
• Team cards in a grid layout (3 columns on desktop)
• Each team card shows: team emoji, team name, agent count, gateway shortcut
• Click team to expand and show agents
• Search bar at top filters across all teams
• Subscribed teams are full-color; unsubscribed teams are muted with "Unlock" badge

4. Onboarding Flow Redesign

Current State

No onboarding exists. Users go directly from Clerk signup to the dashboard chat interface. Storage and API key setup are buried in Settings.

Problem

Without onboarding, users hit the chat interface without:

Proposed Flow

Sign Up (Clerk)

    v
Step 1: Welcome
    "Welcome to Legionis"
    "Your AI workforce is ready to assemble."
    Brief animated Formation L logo
    [Get Started ->]

    v
Step 2: Connect Your AI Provider (REQUIRED)
    "Legionis agents need an AI brain."
    "Bring your own API key -- you control costs."
    [Anthropic card -- input key]
    [OpenAI card -- optional]
    "Don't have a key? Get one from Anthropic Console (link)"
    [Continue ->] (only enabled after valid Anthropic key)

    v
Step 3: Connect Storage (RECOMMENDED, skippable)
    "Where should your agents save their work?"
    [Connect Google Drive -- recommended]
    [Skip for now -- files won't persist]

    v
Step 4: Choose Your First Team
    "Which team do you want to assemble first?"
    Grid of 9+1 team tiles:
    - Product Org (13 agents) -- "PRDs, roadmaps, strategy"
    - Design (7 agents) -- "UI specs, research, prototypes"
    - Architecture (7 agents) -- "API design, security, cloud"
    - Marketing (16 agents) -- "Campaigns, SEO, content"
    - Finance (9 agents) -- "Budgets, forecasting, fundraising"
    - Legal (8 agents) -- "Contracts, compliance, privacy"
    - Operations (8 agents) -- "Programs, process, risk"
    - Executive (2+ agents) -- "Strategy, board prep"
    - Corp Dev (5 agents) -- "M&A, partnerships"
    - IT Governance (6 agents) -- "Security policy, data governance"
    User selects one. Others become "available add-ons".
    [Start with [Team Name] ->]

    v
Step 5: First Interaction (Dashboard)
    Chat opens with a pre-populated prompt based on selected team:
    - Product: "Help me write a product requirements document"
    - Design: "Review these UI mockups and suggest improvements"
    - Marketing: "Plan a launch campaign for my new feature"
    - Finance: "Build a financial model for my SaaS product"
    - Legal: "Review this vendor contract for risks"
    - etc.
    EmptyState hint cards also tailored to selected team.

Key Design Decisions

Why API Key first? Without it, the entire product is non-functional. Unlike storage (which has a graceful degradation path), no API key = no agent responses = immediate churn.

Why team selection? With 81 agents, showing all at once is overwhelming. Letting users choose their "first team" creates a manageable entry point (7-16 agents instead of 81) while implicitly communicating the breadth of the platform.

Why "AI workforce" framing throughout? Every step uses workforce/team/assemble language, not product-management-specific terminology. A marketing lead signing up will see "campaigns, SEO, content" not "PRDs, roadmaps, V2V phases."

Copy Guidelines for Onboarding

5. Critical UX Risks

Risk 1: 81 Agents = Information Overload

Severity: High Impact: Users abandon agent selector, default to auto-routing only, never discover specialist agents

Mitigation Strategy (Layered):

Risk 2: BYOT Friction -- Users Must Provide API Keys

Severity: High Impact: Users who don't have an API key may churn at onboarding. Users who misconfigure keys will get cryptic errors.

Mitigation Strategy:

Risk 3: Context Panel -- When to Show/Hide

Severity: Medium Impact: Right panel takes valuable horizontal space. Showing it at the wrong time distracts; hiding it at the wrong time loses organizational memory visibility.

Mitigation Strategy:

Risk 4: Skill Palette Taxonomy Confusion

Severity: Medium Impact: Non-product users encounter V2V phase labels ("Strategic Foundation", "Strategic Commitments") and have no idea what they mean.

Mitigation Strategy:

Risk 5: Brand Token Migration Breaks Consistency

Severity: Medium Impact: Partial migration creates visual inconsistency (some components zinc, some stone, some mixed).

Mitigation Strategy:

Risk 6: Conversation Persistence UX

Severity: Medium Impact: Users expect conversations to persist like ChatGPT. If the conversation list is empty or buggy, trust drops immediately.

Mitigation Strategy:

Appendix A: Token Migration Quick Reference

Zinc to Stone Mapping

Teal to Amber Mapping

Font Migration

Appendix B: Priority Summary

P0 -- Blocks Week 5 (12 items)

P1 -- Brand/Positioning Alignment (23 items)

1-18. Token migration across all 18 component files (zinc -> stone, teal -> amber)

P2 -- Polish (9 items)

Document Status: Active Next Step: Prioritize P0 items for Week 5 sprint, batch P1 token migration as a single PR Review: Dir PM + Dir Design before implementation