Setup Wizard and Onboarding Plan

Date: 2026-04-01 Status: Draft Milestones: v0.17.2 (first-run detection) -> v0.20.0 (system scanner, wizard UI) -> v0.24.0 (progressive install, guided task) Goal: First useful AI interaction in under 5 minutes from install.

1. Overview

GAIA targets three user personas with very different technical baselines:

Persona	Comfort Level	What They Need
Privacy Paul	Power user, has CLI experience	Skip wizard, `gaia init --profile code --yes`
Curious Carla	Non-technical, first time with local AI	Full wizard with visual feedback and guidance
Enterprise Eric	Technical but compliance-focused	Audit-ready setup, model provenance, offline mode

The setup wizard must satisfy all three. The primary success metric is time from first launch to first useful response — target is under 5 minutes on a broadband connection with an AMD Ryzen AI system.

Design Principles

Never show a blank screen. Every state (loading, downloading, error) has visible feedback.
Every step is skippable. Power users can bail out at any point.
Resume, never restart. Interrupted downloads pick up where they left off.
One shared state file. CLI and UI wizard read/write the same ~/.gaia/setup-state.json.
Hardware-aware defaults. Model recommendations adapt to detected RAM, disk, and NPU.

2. First-Run Detection

Trigger Logic

On any `gaia` CLI command OR Electron app launch:
Check for ~/.gaia/initialized          (file marker)
Check for ~/.gaia/setup-state.json     (partial setup in progress)
If neither exists -> trigger onboarding
If setup-state.json exists but initialized does not -> resume onboarding
If initialized exists -> skip onboarding, proceed normally

State File: `~/.gaia/setup-state.json`

{
  "version": 1,
  "started_at": "2026-04-01T12:00:00Z",
  "completed_at": null,
  "current_step": "model_selection",
  "system_scan": {
    "os": "windows",
    "os_version": "11 Pro 10.0.26200",
    "arch": "x86_64",
    "ram_gb": 32,
    "disk_free_gb": 120,
    "amd_gpu": "Radeon 780M",
    "amd_npu": "Ryzen AI",
    "npu_detected": true,
    "node_version": "20.11.0",
    "python_version": "3.11.8",
    "lemonade_installed": true,
    "lemonade_version": "10.0.0",
    "lemonade_running": false
  },
  "selected_profile": "chat",
  "models_downloaded": ["Qwen3-0.6B-GGUF"],
  "models_pending": ["Qwen3.5-35B-A3B-GGUF", "nomic-embed-text-v1.5-GGUF"],
  "skipped_steps": [],
  "error_log": []
}

CLI Behavior

$ gaia chat
  [First run detected]
  Welcome to GAIA! Run `gaia init` to set up, or pass --skip-setup to proceed manually.

$ gaia init
  [Launches CLI onboarding wizard]

$ gaia init --profile chat --yes
  [Silent mode -- no prompts, uses defaults for the chat profile]

Electron Behavior

On first Electron launch, the main window renders the onboarding wizard instead of the chat view. The wizard is a series of full-screen steps within the existing Electron shell. After completion, the window transitions to the normal chat UI. Related issues: #469 (first-run detection), #597 (Agent UI wizard)

3. System Scanner

The system scanner runs as Step 1 of the wizard and produces the system_scan block in the state file. It must complete in under 5 seconds.

Detection Matrix

Check	Windows	Linux	macOS	Method
OS version	`ver` / registry	`uname -r` / `/etc/os-release`	`sw_vers`	`platform` stdlib
RAM	`wmic` / `GlobalMemoryStatusEx`	`/proc/meminfo`	`sysctl hw.memsize`	`psutil.virtual_memory()`
Free disk	`shutil.disk_usage()`	same	same	stdlib
AMD GPU	`wmic path win32_VideoController`	`lspci`	`system_profiler SPDisplaysDataType`	subprocess
AMD NPU	`lspci` / device enumeration	`lspci`	N/A (no NPU on macOS)	AMD driver query
Node.js	`node --version`	same	same	`shutil.which` + subprocess
Python	`sys.version`	same	same	stdlib
Lemonade installed	`lemonade-server --version`	same	same	`shutil.which` + subprocess
Lemonade running	HTTP GET `http://localhost:13305/api/version`	same	same	`requests.get` with 2s timeout
Models available	Lemonade `/api/models` endpoint	same	same	HTTP GET
Disk write speed	Write 10 MB temp file, measure time	same	same	`tempfile` + `time`

Hardware Tier Classification

Based on scan results, classify the system into a hardware tier that drives model recommendations:

Tier	RAM	NPU	GPU	Recommended Profile
Tier 1: Full	32+ GB	Yes	Discrete or iGPU	`chat` or `code` (30B model)
Tier 2: Standard	16-31 GB	Yes	iGPU	`chat` (8B model)
Tier 3: Light	8-15 GB	Optional	Any	`minimal` (0.6B model)
Tier 4: Insufficient	<8 GB	—	—	Warning: may not run well

Scanner Output (CLI)

System Scan
-----------
OS:            Windows 11 Pro (10.0.26200)
Architecture:  x86_64
RAM:           32 GB                           [OK]
Free disk:     120 GB                          [OK]
AMD GPU:       Radeon 780M (integrated)        [OK]
AMD NPU:       Ryzen AI                        [OK]
Node.js:       v20.11.0                        [OK]
Lemonade:      v10.0.0 (installed, not running) [WARN]
Models:        None downloaded yet             [--]

Hardware tier: Tier 1 (Full)
Recommended profile: chat (~25 GB download)

Related issues: #466 (system scanner)

4. Onboarding Wizard Flow

The wizard consists of 7 steps. Steps 5 and 6 are optional and can be skipped.

[1] Welcome -> [2] System Scan -> [3] Model Selection -> [4] Model Download
    -> [5] Messaging Setup (optional) -> [6] Persona Interview (optional)
    -> [7] Guided First Task -> [DONE] Setup Complete

Step 1: Welcome

Purpose: Introduce GAIA and set expectations.

+------------------------------------------------------------------+
|                                                                    |
|                     Welcome to GAIA                                |
|                                                                    |
|  Your private AI assistant that runs 100% locally.                 |
|  No data ever leaves your device.                                  |
|                                                                    |
|  What we will do:                                                  |
|    1. Scan your hardware                          (~5 seconds)     |
|    2. Download an AI model                        (~3 minutes)     |
|    3. Run your first query                        (~30 seconds)    |
|                                                                    |
|  Total estimated time: under 5 minutes.                            |
|                                                                    |
|                                                                    |
|  [Get Started]                   [Skip -- I know what I'm doing]   |
|                                                                    |
+------------------------------------------------------------------+

Skip behavior: Jumps to normal chat UI. Writes ~/.gaia/initialized with skipped: true so the user is never prompted again but can run gaia init manually.

Step 2: System Scan Results

Purpose: Show what was detected, flag any problems, build user confidence.

+------------------------------------------------------------------+
|                                                                    |
|  System Scan Results                                               |
|                                                                    |
|  [OK]   AMD Ryzen 9 7945HX with Ryzen AI NPU                     |
|  [OK]   32 GB RAM (recommended: 16+ GB)                           |
|  [OK]   120 GB free disk (need: 25 GB for chat profile)           |
|  [OK]   Lemonade Server v10.0.0 installed                          |
|  [WARN] Lemonade Server is not running (will start automatically) |
|                                                                    |
|  Hardware Tier: Full                                               |
|  You can run the most capable models locally.                      |
|                                                                    |
|  [Continue]                                          [Re-scan]     |
|                                                                    |
+------------------------------------------------------------------+

Error states handled here:

Condition	UI Treatment
RAM < 8 GB	Warning banner: “Your system has limited RAM. We recommend the minimal profile (0.6B model).”
Disk < 5 GB free	Blocking error: “Not enough disk space. Free up space and re-scan.”
Lemonade not installed	Action button: “Install Lemonade Server” (triggers download)
No AMD GPU/NPU	Info banner: “No AMD accelerator detected. GAIA will use CPU inference (slower).”
No internet	Info banner: “No internet detected. Connect to download models, or point to local model files.”

Step 3: Model Selection

Purpose: Let user choose what to download. Defaults are pre-selected based on hardware tier.

+------------------------------------------------------------------+
|                                                                    |
|  Choose Your Setup                                                 |
|                                                                    |
|  Based on your hardware (Tier 1: Full), we recommend:              |
|                                                                    |
|  (*) Chat        Interactive chat + document Q&A     ~25 GB        |
|      Models: Qwen3.5-35B, Nomic-Embed-Text                    |
|                                                                    |
|  ( ) Code        Autonomous coding assistant         ~18 GB        |
|      Models: Qwen3.5-35B                                      |
|                                                                    |
|  ( ) Minimal     Lightweight quick-start             ~400 MB       |
|      Models: Qwen3-0.6B                                           |
|                                                                    |
|  ( ) All         Every model for every agent         ~26 GB        |
|      Models: Qwen3.5-35B, Nomic-Embed, Qwen3-VL-4B           |
|                                                                    |
|  Estimated download time: ~3 min at 100 Mbps                      |
|                                                                    |
|  [Download Selected]                                 [Skip Models] |
|                                                                    |
+------------------------------------------------------------------+

Profile-to-model mapping reuses the existing INIT_PROFILES dict from src/gaia/installer/init_command.py (lines 39-100). No duplication — the wizard reads the same profile definitions the CLI uses.

Step 4: Model Download

Purpose: Download models with clear progress and the ability to resume on failure.

+------------------------------------------------------------------+
|                                                                    |
|  Downloading Models                                                |
|                                                                    |
|  Qwen3.5-35B-A3B-GGUF                                        |
|  [===================>          ]  62%   11.2 / 18.0 GB            |
|  Speed: 45 MB/s    ETA: 2 min 30 sec                              |
|                                                                    |
|  Nomic-Embed-Text-v1.5-GGUF                        [Queued]       |
|                                                                    |
|  Starting Lemonade Server...                        [Waiting]      |
|                                                                    |
|                                                                    |
|  [Cancel]                                                          |
|                                                                    |
+------------------------------------------------------------------+

Download implementation details:

Downloads use HTTP range requests for resume-on-failure.
Each model file is downloaded to ~/.gaia/downloads/ with a .part suffix, renamed on completion.
SHA256 checksum verification after each download.
Parallel downloads when bandwidth allows (configurable, default: 1 concurrent download).
Progress is written to setup-state.json after each chunk so resume works after crash or reboot.
If Lemonade Server is not running, it is started automatically after the first model finishes.

Error handling:

Error	Recovery
Network drop mid-download	Pause, retry 3 times with exponential backoff, then prompt user
Disk full during download	Stop, show “Free X GB and retry” with a [Retry] button
Checksum mismatch	Delete corrupt file, re-download from scratch
Lemonade fails to start	Show error log snippet, link to troubleshooting docs

Step 5: Messaging Platform Setup (Optional, deferred to v0.24.0+)

Purpose: Connect GAIA to Discord, Slack, or Telegram for remote access. This step is skipped by default in the initial release. The wizard shows:

+------------------------------------------------------------------+
|                                                                    |
|  Messaging Integrations (Optional)                                 |
|                                                                    |
|  Connect GAIA to your messaging platforms for remote access.       |
|  You can set this up later in Settings.                            |
|                                                                    |
|  [ ] Discord     Not configured                                   |
|  [ ] Slack       Not configured                                   |
|  [ ] Telegram    Not configured                                   |
|                                                                    |
|  [Configure Later]                                   [Set Up Now]  |
|                                                                    |
+------------------------------------------------------------------+

Related issues: Messaging integrations plan (docs/plans/messaging-integrations-plan.mdx)

Step 6: Persona Interview (Optional)

Purpose: Tailor the experience to the user’s goals. Feeds into system prompt and suggested first tasks.

+------------------------------------------------------------------+
|                                                                    |
|  What will you use GAIA for? (select all that apply)               |
|                                                                    |
|  [x] Chat with AI privately                                       |
|  [ ] Ask questions about my documents (PDFs, code, notes)         |
|  [ ] Generate or edit code                                        |
|  [ ] Automate tasks (Jira, Blender, Docker)                       |
|  [ ] Voice interaction                                            |
|  [ ] Just exploring                                                |
|                                                                    |
|  [Continue]                                          [Skip]        |
|                                                                    |
+------------------------------------------------------------------+

The selections are stored in ~/.gaia/preferences.json and used to:

Customize the guided first task (Step 7).
Set a tailored system prompt for the default chat session.
Pre-enable relevant MCP servers if applicable.

Related issues: #467 (onboarding agent / persona interview)

Step 7: Guided First Task

Purpose: Get the user to their first successful AI interaction immediately. Based on persona selections and profile, present a context-aware starter prompt:

+------------------------------------------------------------------+
|                                                                    |
|  Setup Complete -- Try Your First Task                             |
|                                                                    |
|  Everything is ready. Here are some things you can try:            |
|                                                                    |
|  > "Summarize this PDF for me"          [drag a file here]        |
|                                                                    |
|  > "Write a Python function that sorts a list of dictionaries     |
|     by a given key"                                                |
|                                                                    |
|  > "What can you help me with?"                                   |
|                                                                    |
|  Or type your own question below:                                  |
|                                                                    |
|  +--------------------------------------------------------------+ |
|  |                                                              | |
|  +--------------------------------------------------------------+ |
|  [Send]                                                            |
|                                                                    |
+------------------------------------------------------------------+

The guided first task view transitions seamlessly into the normal chat UI. The message input is the same component used in regular chat — the user is already “in” the app. Related issues: #471 (guided first task)

5. Error States — Full Reference

Error	When	CLI Behavior	UI Behavior
Lemonade not installed	System scan	Print install instructions, offer `gaia init` auto-install	Show “Install Lemonade” button
Lemonade wrong version	System scan	Print upgrade command	Show “Upgrade Lemonade” button
Lemonade won’t start	Post-download	Print stderr, suggest port conflict check	Show log viewer with retry button
RAM < 8 GB	System scan	Warn, suggest minimal profile	Warning banner, pre-select minimal
Disk < 5 GB	System scan	Block with error message	Blocking modal, re-scan button
Download failed (network)	Model download	Retry with backoff, then abort with resume hint	Retry button, show partial progress
Download failed (disk full)	Model download	Abort, print space needed	Modal: “Free X GB”, retry button
Checksum mismatch	Model download	Delete + re-download	Auto-retry once, then manual retry
Model load failed	Verification	Print Lemonade error, suggest `gaia init --force-models`	Show error detail, offer re-download
Node.js missing	System scan (Electron only)	N/A (CLI does not need Node)	Prompt to install Node.js
Python < 3.10	System scan	Block, print version requirement	Block, link to Python download

6. Skip / Power-User Path

Every wizard step includes a skip option. Power users have three fast paths:

Path A: CLI Silent Mode

gaia init --profile chat --yes

Runs the full init sequence non-interactively. Uses defaults for hardware tier. Prints progress to stdout. Returns exit code 0 on success.

Path B: Skip Button in UI

The “Skip — I know what I’m doing” button on the Welcome screen writes the ~/.gaia/initialized marker and jumps directly to the chat UI. The user can then configure everything manually through Settings.

Path C: Environment Variable

export GAIA_SKIP_ONBOARDING=1
gaia chat

Permanently suppresses the onboarding prompt. Useful for CI, Docker containers, and automated testing.

7. Progressive Installation

Resume After Interruption

The setup-state.json file tracks progress at a granular level:

User starts wizard, reaches Step 4 (downloading Qwen3.5-35B at 62%)
User closes laptop / loses power / kills process
On next launch, GAIA reads setup-state.json
Finds current_step = "model_download", models_downloaded = [], partial file exists
Resumes download from byte offset using HTTP Range header
Continues wizard from Step 4

Rollback on Failure

If a step fails and cannot be recovered:

The failed step is logged in setup-state.json.error_log.
Previously completed steps are NOT rolled back (models already downloaded stay).
The user is offered: [Retry This Step] or [Skip and Continue].
If the failure is in Lemonade installation, the cleanup removes partially extracted files but preserves any existing working installation.

Parallel Downloads

When the user selects a profile that requires multiple models (e.g., chat needs both a language model and an embedding model):

Download the primary model first (it is needed to verify the setup works).
Queue secondary models to download in the background after the primary completes.
In future versions (v0.24.0+), allow true parallel downloads with bandwidth sharing.

Related issues: #468 (setup executor with resume, rollback, parallel downloads)

8. CLI vs UI Onboarding

Both CLI and UI onboarding share the same backend logic and the same state file.

Shared Components

Component	Location	Used By
`InitCommand`	`src/gaia/installer/init_command.py`	CLI, UI (via API)
`LemonadeInstaller`	`src/gaia/installer/lemonade_installer.py`	CLI, UI (via API)
`INIT_PROFILES`	`src/gaia/installer/init_command.py`	CLI, UI (via API)
`setup-state.json`	`~/.gaia/setup-state.json`	CLI, UI (shared state)
System scanner	`src/gaia/installer/system_scanner.py` (new)	CLI, UI (via API)

CLI-Specific (`gaia init`)

Rich terminal output with progress bars (via rich library).
Interactive prompts for profile selection and confirmations.
--yes flag for non-interactive mode.
--profile flag to skip profile selection.
--skip-models and --skip-lemonade for partial setup.

UI-Specific (Electron wizard)

Full-screen wizard steps rendered in the Electron window.
API calls to a local onboarding endpoint (e.g., POST /api/setup/scan, POST /api/setup/download) that delegates to the same InitCommand backend.
Real-time progress via Server-Sent Events (SSE) or WebSocket.
Drag-and-drop for document upload in the guided first task.

Handoff Between CLI and UI

A user who starts setup via CLI and later opens the Electron app (or vice versa) should see consistent state:

User runs `gaia init --profile chat` in terminal
Downloads complete, Lemonade running, models loaded
User opens Electron app
App reads ~/.gaia/initialized -> skips wizard, goes to chat

User opens Electron app first, starts wizard
Closes app mid-download at 40%
Runs `gaia init` in terminal
CLI reads setup-state.json, resumes download from 40%

9. Post-Onboarding

Guided First Task (Expanded)

After setup completes, the system offers context-aware starter prompts based on the persona interview and detected capabilities:

Persona Selection	Suggested First Task
Chat privately	”Ask me anything — your conversation stays on this device.”
Document Q&A	”Drag a PDF here and ask a question about it.”
Code generation	”Describe a function you need and I will write it.”
Task automation	”Try: ‘List my open Jira tickets’ or ‘Create a Docker container‘“
Voice interaction	”Click the microphone icon to talk to me.”
Just exploring	”Ask me ‘What can you do?’ to see my capabilities.”

Settings Reminder

After the first session, show a non-intrusive banner:

Tip: Visit Settings to customize your model, enable voice, or add document folders.
[Open Settings]  [Dismiss]

Telemetry Opt-In (Optional, v0.24.0+)

After the first successful interaction, optionally ask:

Help improve GAIA by sharing anonymous usage statistics?
No personal data or conversation content is ever sent.
[Yes, help improve GAIA]  [No thanks]

Default is opt-out. Stored in ~/.gaia/preferences.json.

10. Cross-Platform Considerations

Windows (Primary)

Lemonade Server installed via MSI from GitHub releases.
gaia init handles MSI download and silent install.
PATH refresh uses Windows registry read (see init_command.py line 289-337).
NPU detection via AMD driver device enumeration.
Desktop installer via NSIS (docs/plans/desktop-installer.mdx). Related: #530.

Linux

Lemonade Server installed via ppa:lemonade-team/stable (Ubuntu 24.04+).
gaia init detects distro and uses appropriate package manager.
NPU detection via lspci and /sys/class/ device tree.
Desktop packaging via AppImage.

macOS

Lemonade Server installed via Homebrew or pip.
No NPU support (Apple Silicon uses Metal, not AMD NPU).
GPU detection via system_profiler.
Desktop packaging via DMG.
System scanner notes: “AMD NPU not available on macOS. Using CPU inference.”

Platform-Specific UI Differences

Feature	Windows	Linux	macOS
System tray icon	Yes (native)	Yes (AppIndicator)	Yes (menu bar)
Auto-start on login	Registry entry	`.desktop` autostart	Launch Agent plist
Admin required	No (user-space install)	No	No
Default install path	`%USERPROFILE%\.gaia\`	`~/.gaia/`	`~/.gaia/`

11. Implementation Phases

Phase 1: v0.17.2 — Foundation

First-run detection (~/.gaia/initialized check)
gaia init improvements: resume support, better progress output
State file (setup-state.json) read/write
Desktop installer (NSIS for Windows) — #530

Phase 2: v0.20.0 — Scanner and Wizard UI

System scanner module (src/gaia/installer/system_scanner.py) — #466
Hardware tier classification
Electron onboarding wizard (Steps 1-4, 7) — #470
API endpoints for setup operations (/api/setup/*)
Persona interview (Step 6) — #467

Phase 3: v0.24.0 — Progressive Install and Guided Tasks

Parallel model downloads with bandwidth management — #468
Full resume-on-failure with byte-level tracking — #468
Rollback on failure — #468
First-run auto-trigger on any gaia command — #469
Context-aware guided first task — #471
Messaging platform setup step (optional) — deferred

12. GitHub Issue Cross-References

Issue	Title	Milestone	Covered In
#597	Agent UI first-run setup wizard / onboarding flow	v0.17.2	Sections 2, 4
#466	System Scanner: detect hardware, OS, installed tools	v0.20.0	Section 3
#467	Onboarding Agent: persona interview and smart install	v0.20.0	Section 4 (Step 6)
#468	Setup executor: progressive install with resume/rollback	v0.24.0	Section 7
#469	First-run detection: auto-trigger on initial gaia command	v0.24.0	Section 2
#470	Chat UI onboarding wizard: visual setup flow	v0.20.0	Section 4
#471	Guided first task: context-aware onboarding prompt	v0.24.0	Section 4 (Step 7), Section 9
#530	Desktop installer: NSIS, DMG, AppImage + auto-update	v0.17.2	Section 10

13. Open Questions

Model storage location. Should models live in ~/.gaia/models/ (GAIA-managed) or defer to Lemonade Server’s own model cache? Current: Lemonade manages its own cache. Wizard should show where models are stored regardless.
Offline-first mode. For Enterprise Eric, the wizard should support a mode where model files are provided on a USB drive or network share instead of downloaded from the internet. Needs a “Load from file” option in Step 3.
Multi-user systems. On shared Linux/macOS machines, each user has their own ~/.gaia/ directory. On Windows with multiple user profiles, same approach. But Lemonade Server is system-wide — how to handle version conflicts?
Telemetry. The opt-in telemetry question (Section 9) needs legal review before shipping. Consider deferring to v0.24.0+.

​Setup Wizard and Onboarding Plan

​1. Overview

​Design Principles

​2. First-Run Detection

​Trigger Logic

​State File: ~/.gaia/setup-state.json

​CLI Behavior

​Electron Behavior

​3. System Scanner

​Detection Matrix

​Hardware Tier Classification

​Scanner Output (CLI)

​4. Onboarding Wizard Flow

​Step 1: Welcome

​Step 2: System Scan Results

​Step 3: Model Selection

​Step 4: Model Download

​Step 5: Messaging Platform Setup (Optional, deferred to v0.24.0+)

​Step 6: Persona Interview (Optional)

​Step 7: Guided First Task

​5. Error States — Full Reference

​6. Skip / Power-User Path

​Path A: CLI Silent Mode

​Path B: Skip Button in UI

​Path C: Environment Variable

​7. Progressive Installation

​Resume After Interruption

​Rollback on Failure

​Parallel Downloads

​8. CLI vs UI Onboarding

​Shared Components

​CLI-Specific (gaia init)

​UI-Specific (Electron wizard)

​Handoff Between CLI and UI

​9. Post-Onboarding

​Guided First Task (Expanded)

​Settings Reminder

​Telemetry Opt-In (Optional, v0.24.0+)

​10. Cross-Platform Considerations

​Windows (Primary)

​Linux

​macOS

​Platform-Specific UI Differences

​11. Implementation Phases

​Phase 1: v0.17.2 — Foundation

​Phase 2: v0.20.0 — Scanner and Wizard UI

​Phase 3: v0.24.0 — Progressive Install and Guided Tasks

​12. GitHub Issue Cross-References

​13. Open Questions