---
phase: 30-hardware-detection-mode-selection
plan: "02"
subsystem: ui
tags: [onboarding, hardware-detection, mode-selection, react-query, wizard]
dependency_graph:
  requires: ["30-01"]
  provides: ["hardware-api-client", "mode-selector-ui", "hardware-summary-ui", "3-step-wizard"]
  affects: ["ui/src/components/NexusOnboardingWizard.tsx"]
tech_stack:
  added: []
  patterns: ["useQuery for hardware probe", "multi-step wizard with step state", "non-blocking hardware probe"]
key_files:
  created:
    - ui/src/api/hardware.ts
    - ui/src/hooks/useHardwareInfo.ts
    - ui/src/components/onboarding/ModeSelector.tsx
    - ui/src/components/onboarding/HardwareSummaryStep.tsx
  modified:
    - ui/src/components/NexusOnboardingWizard.tsx
    - ui/src/lib/queryKeys.ts
decisions:
  - "Hardware probe is non-blocking — wizard step 1 always has an enabled Continue button regardless of probe outcome"
  - "Mode save on wizard completion is wrapped in try/catch — failure is silent, defaults to 'both'"
  - "Pre-existing AgentConfigForm.tsx TypeScript error is out-of-scope; documented here for awareness"
metrics:
  duration: 15
  completed_date: "2026-04-02"
  tasks_completed: 3
  files_changed: 6
---

# Phase 30 Plan 02: Hardware Detection UI + 3-Step Wizard Summary

**One-liner:** Three-step onboarding wizard with hardware probe display (GPU/Apple Silicon/CPU-only), three-card mode selector, and settings persistence via PATCH /api/nexus/settings.

## What Was Built

### Task 1: API client, hook, ModeSelector, and HardwareSummaryStep
- `ui/src/api/hardware.ts` — typed fetch wrappers: `fetchHardwareInfo`, `fetchNexusSettings`, `updateNexusSettings`, plus `HardwareInfo`, `HardwareTier`, `NexusMode`, `NexusSettings` types (local copy — not imported from server)
- `ui/src/hooks/useHardwareInfo.ts` — `useHardwareInfo(enabled)` hook wrapping `useQuery` with 5-minute staleTime and retry: 1
- `ui/src/lib/queryKeys.ts` — added `hardware: { info: ["hardware", "info"] as const }` key
- `ui/src/components/onboarding/ModeSelector.tsx` — three vertical cards with `border-primary bg-primary/5` selected state; modes: Personal AI Assistant, Project Builder, Both (recommended)
- `ui/src/components/onboarding/HardwareSummaryStep.tsx` — skeleton loading (3 rows), error state (non-destructive copy), and success state with tier-appropriate labels (Unified memory for Apple Silicon, GPU VRAM for GPU tier, System RAM for CPU-only), plus privacy frame for local AI tiers

### Task 2: Wire multi-step wizard
- `ui/src/components/NexusOnboardingWizard.tsx` refactored from single-step to 3-step wizard
- Step indicator `Step {step} of 3` shown above content
- Step 1: hardware detection heading changes from "Detecting your hardware..." to "Your hardware" when probe resolves; HardwareSummaryStep displayed; Continue always enabled
- Step 2: ModeSelector with "both" pre-selected; Continue and Back buttons
- Step 3: existing root directory form preserved; Back button added; Get Started submit
- `updateNexusSettings({ mode: selectedMode })` called after company creation, before navigate — wrapped in try/catch (non-blocking)
- Reset effect expanded to also reset `step` to 1 and `selectedMode` to "both" on wizard close

## Checkpoint: Visual Verification

Task 3 (`checkpoint:human-verify`) — **Approved by user on 2026-04-02.**

Visual verification of the complete 3-step onboarding wizard flow was approved. No issues reported.

## Deviations from Plan

None — plan executed exactly as written.

## Known Stubs

None — all data paths are wired. `useHardwareInfo` fetches from `/api/system/providers` (implemented in 30-01). `updateNexusSettings` PATCHes `/api/nexus/settings` (implemented in 30-01).

## Self-Check: PASSED

Files created/modified:
- FOUND: /opt/nexus/ui/src/api/hardware.ts
- FOUND: /opt/nexus/ui/src/hooks/useHardwareInfo.ts
- FOUND: /opt/nexus/ui/src/components/onboarding/ModeSelector.tsx
- FOUND: /opt/nexus/ui/src/components/onboarding/HardwareSummaryStep.tsx
- FOUND: /opt/nexus/ui/src/components/NexusOnboardingWizard.tsx

Commits: f4423546, e1bdb9a8