Problem
New users who launch Gaia without completing setup have no in-app guidance. The welcome screen looks identical whether or not models are downloaded or MCP servers are configured. Users can spend significant time confused before realizing they need to complete prerequisites. On a fresh install, this needs to be a polished guided flow — not just a checklist modal.
Current State
initialized flag exists in /api/system/status but is only surfaced as a text hint (interim fix)- Welcome screen is static regardless of system state
- No hardware detection, model selection, or MCP configuration in the onboarding flow
- The only full guidance is in documentation, not in-app
Proposed Solution
Implement a first-run onboarding wizard:
1. System Requirements Check
On first launch, automatically detect and report:
- NPU/GPU availability and compatibility
- Available memory and disk space
- OS version and platform capabilities
- Display results as a checklist (pass/fail per requirement)
2. Model Setup
- If no model is present, guide the user through model selection and download
- Show download progress with estimated time remaining
- If the model was bundled with the installer, skip this step and confirm it is ready
- Validate model integrity after download (checksum verification)
3. MCP Server Configuration
- Present the MCP configuration UI as part of the onboarding flow
- If default MCP servers are pre-configured via a deployment profile, show them and confirm
- Allow the user to add/remove MCP servers before completing setup
4. Agent Selection
- Show available agents from the agent registry and let the user pick a default
- If a deployment profile specifies a default, pre-select it but allow override
5. Completion
- Summary of what was configured
- Optional: quick interactive demo showing agent capabilities
- Agent boots into the selected default configuration
Profile-Awareness
If Gaia is launched with a deployment profile (--profile <name>), the onboarding flow pre-fills settings from the profile. The user can override any pre-filled value through the wizard UI.
Technical Notes
The flow should be:
- Resumable: If interrupted (e.g., model download fails), pick up where it left off
- Skippable: Power users can skip to manual configuration
- Non-blocking: Steps that are already complete are shown as complete and skipped
Files Likely Affected
src/gaia_ui/frontend/ — onboarding wizard components (step UI, progress indicators)src/gaia_ui/backend/ — system detection API, onboarding state managementsrc/gaia/ — hardware detection, model validation logic
Acceptance Criteria
References
Problem
New users who launch Gaia without completing setup have no in-app guidance. The welcome screen looks identical whether or not models are downloaded or MCP servers are configured. Users can spend significant time confused before realizing they need to complete prerequisites. On a fresh install, this needs to be a polished guided flow — not just a checklist modal.
Current State
initializedflag exists in/api/system/statusbut is only surfaced as a text hint (interim fix)Proposed Solution
Implement a first-run onboarding wizard:
1. System Requirements Check
On first launch, automatically detect and report:
2. Model Setup
3. MCP Server Configuration
4. Agent Selection
5. Completion
Profile-Awareness
If Gaia is launched with a deployment profile (
--profile <name>), the onboarding flow pre-fills settings from the profile. The user can override any pre-filled value through the wizard UI.Technical Notes
The flow should be:
Files Likely Affected
src/gaia_ui/frontend/— onboarding wizard components (step UI, progress indicators)src/gaia_ui/backend/— system detection API, onboarding state managementsrc/gaia/— hardware detection, model validation logicAcceptance Criteria
initialized === falseReferences