Chat UI onboarding wizard: visual setup flow with system scan and progress

[kovtcharov]

Summary

Build a visual onboarding wizard in the Chat UI that replaces the static WelcomeScreen on first launch. Card-based persona selection, animated system scan, install progress bar, and guided first task — all driven by the same onboarding agent and executor used in CLI mode.

Design

Step 1: Welcome

• GAIA logo + "Welcome to GAIA"
• Brief description: "Your private AI assistant, running locally on AMD hardware"
• Button: "Get Started" → "Can I scan your system for the best setup?"
• Privacy note: "All data stays on your machine"

Step 2: System Scan (2-3 seconds)

• Animated scan with checkmarks appearing:
  • ✅ Windows 11, 32GB RAM, 120GB free
  • ✅ AMD Ryzen 9 with NPU detected
  • ✅ Docker installed
  • ✅ Git available
  • ❌ Blender not found
  • ❌ Node.js not found
• Progress animation during scan

Step 3: What do you want to do? (Card selection)

• Grid of cards with icons, multi-select:
  • 📄 Chat with Documents
  • 💻 Write Code
  • 🎙️ Voice Assistant
  • 🎨 Generate Images
  • 🐳 Manage Containers (badge: "Docker detected!")
  • 📋 Manage Jira (badge: "Credentials found!")
  • 🌐 Browse the Web
  • 🖥️ Control My Desktop
  • 🔍 Just Exploring
• Cards for detected tools get a highlight/badge

Step 4: Install Plan Confirmation

• Summary panel showing:
  • Selected agents with descriptions
  • Total download size
  • Estimated time
  • Disk space before/after
• "Install" / "Customize" / "Cancel" buttons

Step 5: Installation Progress

• Overall progress bar
• Per-step status (Lemonade → Models → Extras → Validation)
• "New capability unlocked!" notifications as each model finishes
• Cancel button for abort

Step 6: Setup Complete

• Checkmark animation
• "You're all set! Here are some things to try:"
• Context-aware suggested prompts based on installed agents
• "Start Chatting" button

API Endpoints

GET  /api/onboarding/status      → {state: "not_started|scanning|interview|planning|installing|complete"}
POST /api/onboarding/scan        → triggers system scan, returns SystemProfile
POST /api/onboarding/preferences → receives UserProfile selections
GET  /api/onboarding/plan        → returns InstallPlan
POST /api/onboarding/install     → starts installation (SSE stream for progress)
POST /api/onboarding/skip        → marks onboarding complete without installing

Frontend Components

src/gaia/apps/chat/webui/src/components/
├── onboarding/
│   ├── OnboardingWizard.tsx      # Main wizard container with step navigation
│   ├── WelcomeStep.tsx           # Step 1: welcome + scan permission
│   ├── SystemScanStep.tsx        # Step 2: animated scan results
│   ├── PersonaStep.tsx           # Step 3: card-based selection
│   ├── PlanStep.tsx              # Step 4: install plan review
│   ├── InstallStep.tsx           # Step 5: progress tracking
│   ├── CompleteStep.tsx          # Step 6: success + first task
│   └── OnboardingCard.tsx        # Reusable persona card component

Files to Create/Modify

• `src/gaia/apps/chat/webui/src/components/onboarding/` (NEW, 7 components)
• `src/gaia/ui/server.py` (MODIFY) — Add onboarding API endpoints
• `src/gaia/apps/chat/webui/src/App.tsx` (MODIFY) — Route to wizard when uninitialized
• `src/gaia/apps/chat/webui/src/services/api.ts` (MODIFY) — Add onboarding API calls

Acceptance Criteria

• Wizard shows on first launch when `/api/system/status` returns uninitialized
• System scan results displayed with animated checkmarks
• Card-based persona selection with detected tool badges
• Install plan shows accurate sizes and estimates
• Progress bar tracks real-time install status via SSE
• "Setup complete" leads to contextual first-task prompt
• Works in both Electron app and browser
• Responsive layout (desktop and tablet)
• Skip option available at every step

Depends On

• Issue Prevent Users from Installing Hybrid mode on Unsupported Systems #6 (Onboarding Agent), Installer Fails on Some Systems #7 (Executor), v0.7.4 #8 (First-Run Detection)