feat(agent-ui): first-run onboarding wizard — hardware pre-flight, in-app model download, connect-on-install

[kovtcharov-amd]

Why this matters

Before: a first-time user had no guided path — models and connectors could only be set up from the terminal (gaia init), a machine that couldn't meet an agent's requirements only found out at runtime, and a failed model download was swallowed silently. After: opening the Agent UI on a fresh machine launches an in-app wizard that scans the hardware and gates on real capability (RAM/disk/NPU/GPU), downloads the recommended model with visible progress and retry, and offers to connect an app (e.g. Google for Email triage) before first run. A non-technical user reaches a working chat without touching a terminal.

Bundles the two first-run issues since they share one flow: #1726 (onboarding wizard + in-app model download) and #1727 (hardware pre-flight gating + connector-on-install).

Every failure state is loud and actionable — a hardware blocker disables Continue and names the shortfall, a failed download shows the backend's message with a Retry, and a missing OAuth credential shows exactly which env vars to set. Nothing silently skips to leave a half-set-up app.

What's in it

• Hardware pre-flight (Hardware pre-flight gating + connector-on-install flow #1727): detected NPU / GPU VRAM now feed hub.compatibility.check_compatibility, so a no-NPU machine gets a real warning instead of a blanket "cannot verify" (values default to None to preserve the conservative fallback). New GET /api/onboarding/preflight runs the same shared checker the hub install path uses, so blockers match.
• Onboarding state: /api/onboarding/status + /complete over the existing ~/.gaia/chat/initialized marker the CLI and agent-loop already read — UI and CLI stay in lock-step, and completing once suppresses the wizard for good.
• In-app model download (First-run onboarding wizard + in-app model download #1726): reuses POST /api/system/download-model and its status-fed SSE progress — no new download backend. Visible progress bar + Retry on failure.
• Connect-on-install (Hardware pre-flight gating + connector-on-install flow #1727): reuses the existing connector authorize flow; does not rebuild grant logic (that lives in the connectors framework, feat(ui): connecting a mailbox must grant it to the email agent in the same flow #2117/fix(webui): agent discovery/launch is broken on consumer installs — hub button opens nothing, no agent picker exists #2118) — coded against today's authorize/getConnector interface.
• Wizard UI: new components/onboarding/ (welcome → pre-flight → download → optional connector → done), driven by a pure, unit-tested useOnboarding state machine. Isolated to new files; App.tsx edits are minimal (mount + first-run check).

Test plan

• Backend unit tests — python -m pytest tests/unit/test_onboarding_router.py tests/unit/test_hub_compatibility.py (36 passed): pre-flight tiers/blockers/warnings, NPU present/absent/unknown, GPU VRAM below/meets requirement, status/complete marker round-trip.
• Frontend unit tests — npm run test in src/gaia/apps/webui (195 passed, incl. 13 new): useOnboarding state machine (advance/back/guard/skip/goTo) + wizard flow (welcome skip, scan, blocker gating, advance).
• Type-check + build — npm run build (tsc + vite) clean.
• Lint — black / isort / flake8 / pylint clean on changed files.
• Manual first-run walkthrough (Playwright, real backend on a fresh ~/.gaia): welcome → hardware check (Tier: Full, RAM/disk/NPU all green, Continue enabled) → model download (Continue correctly gated until the model is ready; explicit "Set up later" escape) → Google connector (optional; loud "OAuth credentials not configured" with the exact env vars) → "You're all set". Screenshots captured for each step.

To verify locally:

# Terminal 1 — backend
python -m gaia.ui.server --port 4200 --host 127.0.0.1
# Terminal 2 — build + open (fresh machine: no ~/.gaia/chat/initialized)
cd src/gaia/apps/webui && npm ci && npm run build
# open http://127.0.0.1:4200 — the wizard overlays until setup completes

Part of #2014
Closes #1726
Closes #1727

[github-actions]

Verdict: Approve with suggestions — safe to merge after a look at the one maintainability point below.

This adds a first-run onboarding wizard to the Agent UI: a hardware pre-flight that gates on real capability (RAM/disk/NPU/GPU), an in-app model download with progress + retry, and an optional connect-an-app step, all backed by three new /api/onboarding/* endpoints. It's cleanly isolated to new files, reuses the shared compatibility checker and existing download/connector flows rather than rebuilding them, fails loudly on every error path, and ships with solid tests on both sides.

The one thing worth a second look: the backend's Lemonade device probe (NPU/GPU/VRAM parsing) is a near-copy of logic that already lives in the system-status router. It's not a bug, but the two copies have already drifted slightly in how they treat a missing NPU, so they'll keep drifting unless one calls the other. Nothing here blocks merge.

No security concerns. No breaking changes — the init marker stays compatible with the existing .exists() readers.

🔍 Technical details

🟡 Important (non-blocking)

Duplicated Lemonade device probe — drift risk (src/gaia/ui/routers/onboarding.py:1688 vs src/gaia/ui/routers/system.py:607-625)
Both parse /system-info devices for GPU name / vram_gb / NPU availability. The two implementations already diverge: system.py never yields a definite "no NPU" (absence just omits npu from detected_devices), while the new probe distinguishes False (seen-but-unavailable) from None (unprobed). That richer three-state semantics is exactly what the pre-flight needs — so the cleaner fix is to lift it into one shared helper (e.g. probe_lemonade_devices() returning {lemonade_running, npu_detected, gpu_name, gpu_vram_gb}) and have the system router consume it too, so the NPU logic can't silently diverge again. Extract-and-share, not two copies. Not blocking, but a maintainer will thank you later.

🟢 Minor / nits

First download poll is delayed ~2s (ModelDownloadStep.tsx:326-327)
After downloadModel resolves, startDownload sets up setInterval(poll, POLL_MS) but doesn't fire poll() once immediately, so the progress bar sits empty for up to 2s after the click. One eager call tightens the feedback:

            stopPolling();
            poll();
            pollRef.current = setInterval(poll, POLL_MS);

New user-facing feature likely wants a doc line — the wizard and the /api/onboarding/* surface aren't mentioned in docs/guides/agent-ui.mdx. Per CLAUDE.md ("every new feature must be documented") a short note on the first-run flow would close the loop; the internal endpoints themselves don't need a reference page.

Strengths

• Genuine reuse over reinvention: pre-flight runs the same check_compatibility the hub install path uses, download rides the existing POST /api/system/download-model + status SSE, and the connector step is explicit about not rebuilding grant logic. The detected_npu/detected_gpu_vram_gb wiring into the shared checker (with None preserving the conservative "cannot verify" path) is the right shape.
• Fail-loudly throughout: the marker-write 500 with an actionable message (onboarding.py:1877), the download/preflight error banners with retry, and the "can't verify → keep the guard on" default all match the no-silent-fallback rule.
• Well-tested both sides: the pure useOnboarding state machine, the wizard flow (blocker gating, advance), and the router (tiers, blockers, NPU present/absent/unknown, marker round-trip incl. the legacy empty-marker case) are all covered — and the marker stays .exists()-compatible with system.py:686 / agent_loop.py:216.

[kovtcharov]

The first-run golden path can dead-end frozen: ModelDownloadStep only creates its poll interval inside startDownload(); the mount effect calls poll() exactly once. If the user starts the multi-GB download and then remounts the step (page refresh — the wizard re-shows since the init marker isn't written yet — or Back/return), the single poll sees state === 'downloading', renders the progress bar, and never polls again. Progress stays frozen and Continue never enables even after the download completes; the only escape is skipping setup.

Fix: start the interval from the mount effect whenever the initial poll reports an active download (and clear it on unmount, as startDownload already arranges). Note this polling lifecycle is exactly the untested slice — the 36 backend + 13 frontend tests cover the router and wizard navigation, but not remount-mid-download; worth a test with the fix.

[kovtcharov]

The frozen-download flaw is fixed: polling is now extracted into beginPolling(), and the mount effect restarts it whenever the initial status reports an active download (downloading/starting) — so a remount mid-download resumes instead of freezing. Backed by a new 127-line ModelDownloadStep.test.tsx covering the remount-resume path. Verified on the PR branch.