mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(32-01): complete multi-step-onboarding-wizard plan

Browse source 
- OnboardingSummaryStep component with 6 passing tests
- NexusOnboardingWizard updated: 5 steps, skip on 1/2/4, summary on step 5
- Requirements ONBD-04, ONBD-05, ONBD-06 marked complete
This commit is contained in:
Nexus Dev 2026-04-03 21:37:41 +00:00
parent 4032d4d88b
commit dba88cd005
4 changed files with 125 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
.planning/REQUIREMENTS.md
View file

@ -10,9 +10,9 @@
- [x] **ONBD-01**: User can select mode (Personal AI Assistant / Project Builder / Both) during onboarding - [x] **ONBD-01**: User can select mode (Personal AI Assistant / Project Builder / Both) during onboarding
- [x] **ONBD-02**: System auto-detects GPU, RAM, and Apple Silicon unified memory within 5 seconds - [x] **ONBD-02**: System auto-detects GPU, RAM, and Apple Silicon unified memory within 5 seconds
- [x] **ONBD-03**: System recommends best local model from pre-built JSON database based on detected hardware - [x] **ONBD-03**: System recommends best local model from pre-built JSON database based on detected hardware
- [ ] **ONBD-04**: User can skip any onboarding step without blocking subsequent steps - [x] **ONBD-04**: User can skip any onboarding step without blocking subsequent steps
- [ ] **ONBD-05**: User sees summary screen showing configured providers and agent-model pairings - [x] **ONBD-05**: User sees summary screen showing configured providers and agent-model pairings
- [ ] **ONBD-06**: User can go from summary screen directly into chat with one click - [x] **ONBD-06**: User can go from summary screen directly into chat with one click
- [x] **ONBD-07**: Local AI framed as privacy premium ("runs entirely on your machine, no accounts, works offline") - [x] **ONBD-07**: Local AI framed as privacy premium ("runs entirely on your machine, no accounts, works offline")
### Cloud Providers ### Cloud Providers
@ -78,9 +78,9 @@
| CLOUD-03 | Phase 31 | Complete | | CLOUD-03 | Phase 31 | Complete |
| CLOUD-04 | Phase 31 | Complete | | CLOUD-04 | Phase 31 | Complete |
| CLOUD-05 | Phase 31 | Complete | | CLOUD-05 | Phase 31 | Complete |
| ONBD-04 | Phase 32 | Pending | | ONBD-04 | Phase 32 | Complete |
| ONBD-05 | Phase 32 | Pending | | ONBD-05 | Phase 32 | Complete |
| ONBD-06 | Phase 32 | Pending | | ONBD-06 | Phase 32 | Complete |
| ASST-01 | Phase 33 | Pending | | ASST-01 | Phase 33 | Pending |
| ASST-02 | Phase 33 | Pending | | ASST-02 | Phase 33 | Pending |
| ASST-03 | Phase 33 | Pending | | ASST-03 | Phase 33 | Pending |

6
.planning/ROADMAP.md
View file

@ -90,7 +90,7 @@ Plans:
- [x] **Phase 30: Hardware Detection + Mode Selection** — Unauthenticated hardware probe, Apple Silicon unified memory handling, model recommendation database, and mode selector that gates all assistant-specific features (completed 2026-04-02) - [x] **Phase 30: Hardware Detection + Mode Selection** — Unauthenticated hardware probe, Apple Silicon unified memory handling, model recommendation database, and mode selector that gates all assistant-specific features (completed 2026-04-02)
- [x] **Phase 31: Puter.js Zero-Config Cloud** — Server-proxied Puter.js adapter with full cost tracking, Google OAuth PKCE tier, and subscription auto-detection; no API keys required for zero-config path (completed 2026-04-03) - [x] **Phase 31: Puter.js Zero-Config Cloud** — Server-proxied Puter.js adapter with full cost tracking, Google OAuth PKCE tier, and subscription auto-detection; no API keys required for zero-config path (completed 2026-04-03)
- [ ] **Phase 32: Multi-Step Onboarding Wizard** — Assemble all provider tiers and hardware data into a skippable multi-step wizard; summary screen routes directly into chat - [x] **Phase 32: Multi-Step Onboarding Wizard** — Assemble all provider tiers and hardware data into a skippable multi-step wizard; summary screen routes directly into chat (completed 2026-04-03)
- [ ] **Phase 33: Persistent Memory + Personal Assistant Mode** — File-backed memory with write-time sanitization, PersonalAssistantPage, conversation handoff to PM agent - [ ] **Phase 33: Persistent Memory + Personal Assistant Mode** — File-backed memory with write-time sanitization, PersonalAssistantPage, conversation handoff to PM agent
- [ ] **Phase 34: Voice** — Piper TTS with pre-warm progress, Whisper STT wired into voice service, onboarding voice step activated - [ ] **Phase 34: Voice** — Piper TTS with pre-warm progress, Whisper STT wired into voice service, onboarding voice step activated
- [ ] **Phase 35: npx buildthis CLI** — Standalone bootstrapper package with hardware detection and provider tiering parity with web onboarding - [ ] **Phase 35: npx buildthis CLI** — Standalone bootstrapper package with hardware detection and provider tiering parity with web onboarding
@ -144,7 +144,7 @@ Plans:
**Plans**: 1 plan **Plans**: 1 plan
Plans: Plans:
- [ ] 32-01-PLAN.md — Summary step, skip buttons, chat handoff - [x] 32-01-PLAN.md — Summary step, skip buttons, chat handoff
**UI hint**: yes **UI hint**: yes
### Phase 33: Persistent Memory + Personal Assistant Mode ### Phase 33: Persistent Memory + Personal Assistant Mode
@ -226,7 +226,7 @@ All 21 v1.5 requirements are mapped to exactly one phase. No orphans.
| 29. Default Provider & End-to-End | v1.4 | 2/2 | Complete | 2026-04-02 | | 29. Default Provider & End-to-End | v1.4 | 2/2 | Complete | 2026-04-02 |
| 30. Hardware Detection + Mode Selection | v1.5 | 2/2 | Complete | 2026-04-03 | | 30. Hardware Detection + Mode Selection | v1.5 | 2/2 | Complete | 2026-04-03 |
| 31. Puter.js Zero-Config Cloud | v1.5 | 4/4 | Complete | 2026-04-03 | | 31. Puter.js Zero-Config Cloud | v1.5 | 4/4 | Complete | 2026-04-03 |
| 32. Multi-Step Onboarding Wizard | v1.5 | 0/TBD | Not started | - | | 32. Multi-Step Onboarding Wizard | v1.5 | 1/1 | Complete | 2026-04-03 |
| 33. Persistent Memory + Personal Assistant Mode | v1.5 | 0/TBD | Not started | - | | 33. Persistent Memory + Personal Assistant Mode | v1.5 | 0/TBD | Not started | - |
| 34. Voice | v1.5 | 0/TBD | Not started | - | | 34. Voice | v1.5 | 0/TBD | Not started | - |
| 35. npx buildthis CLI | v1.5 | 0/TBD | Not started | - | | 35. npx buildthis CLI | v1.5 | 0/TBD | Not started | - |

27
.planning/STATE.md
View file

@ -2,15 +2,15 @@
gsd_state_version: 1.0 gsd_state_version: 1.0
milestone: v1.5 milestone: v1.5
milestone_name: Smart Onboarding + Personal AI Assistant milestone_name: Smart Onboarding + Personal AI Assistant
status: executing status: verifying
stopped_at: Completed 31-puter.js-zero-config-cloud/31-04 (verification plan, auto-approved) stopped_at: Completed 32-multi-step-onboarding-wizard/32-01
last_updated: "2026-04-03T21:23:02.558Z" last_updated: "2026-04-03T21:37:28.251Z"
last_activity: 2026-04-03 last_activity: 2026-04-03
progress: progress:
total_phases: 6 total_phases: 6
completed_phases: 2 completed_phases: 3
total_plans: 6 total_plans: 7
completed_plans: 6 completed_plans: 7
percent: 0 percent: 0
--- ---
@ -21,13 +21,13 @@ progress:
See: .planning/PROJECT.md (updated 2026-04-02) See: .planning/PROJECT.md (updated 2026-04-02)
**Core value:** A fresh onboard asks for ONE thing (root directory), auto-creates PM + Engineer agents, and drops you in the dashboard. **Core value:** A fresh onboard asks for ONE thing (root directory), auto-creates PM + Engineer agents, and drops you in the dashboard.
**Current focus:** Phase 31 — puter.js-zero-config-cloud **Current focus:** Phase 32 — multi-step-onboarding-wizard
## Current Position ## Current Position
Phase: 32 Phase: 32 (multi-step-onboarding-wizard) — EXECUTING
Plan: Not started Plan: 1 of 1
Status: Ready to execute Status: Phase complete — ready for verification
Last activity: 2026-04-03 Last activity: 2026-04-03
Progress: [__________] 0% Progress: [__________] 0%
@ -58,6 +58,7 @@ Progress: [__________] 0%
| Phase 31-puter.js-zero-config-cloud P02 | 202 | 3 tasks | 4 files | | Phase 31-puter.js-zero-config-cloud P02 | 202 | 3 tasks | 4 files |
| Phase 31-puter.js-zero-config-cloud P03 | 5 | 2 tasks | 6 files | | Phase 31-puter.js-zero-config-cloud P03 | 5 | 2 tasks | 6 files |
| Phase 31-puter.js-zero-config-cloud P04 | 1 | 1 tasks | 0 files | | Phase 31-puter.js-zero-config-cloud P04 | 1 | 1 tasks | 0 files |
| Phase 32-multi-step-onboarding-wizard P01 | 4 | 2 tasks | 3 files |
## Accumulated Context ## Accumulated Context
@ -82,6 +83,8 @@ Key constraints for v1.5 (established at roadmap):
- [Phase 31-puter.js-zero-config-cloud]: pendingTokens pattern: callback parks tokens by stateId, claim endpoint links to real companyId post-company-creation - [Phase 31-puter.js-zero-config-cloud]: pendingTokens pattern: callback parks tokens by stateId, claim endpoint links to real companyId post-company-creation
- [Phase 31-puter.js-zero-config-cloud]: Provider heading in wizard wrapper (not ProviderSelectionStep) for consistency with ModeSelector pattern; credentials captured in React state and posted after company creation - [Phase 31-puter.js-zero-config-cloud]: Provider heading in wizard wrapper (not ProviderSelectionStep) for consistency with ModeSelector pattern; credentials captured in React state and posted after company creation
- [Phase 31-puter.js-zero-config-cloud]: Plan 04 is verification-only — auto-approved under workflow.auto_advance=true; full UAT deferred to manual QA session - [Phase 31-puter.js-zero-config-cloud]: Plan 04 is verification-only — auto-approved under workflow.auto_advance=true; full UAT deferred to manual QA session
- [Phase 32-multi-step-onboarding-wizard]: createWorkspace() helper extracted so both handleSubmit and handleStartChat share workspace creation without duplication
- [Phase 32-multi-step-onboarding-wizard]: Step 4 form submit removed — replaced with button advancing to step 5; actual workspace creation deferred to summary CTA
### Pending Todos ### Pending Todos
@ -96,6 +99,6 @@ None yet.
## Session Continuity ## Session Continuity
Last session: 2026-04-03T21:22:33.808Z Last session: 2026-04-03T21:37:28.248Z
Stopped at: Completed 31-puter.js-zero-config-cloud/31-04 (verification plan, auto-approved) Stopped at: Completed 32-multi-step-onboarding-wizard/32-01
Resume file: None Resume file: None

101
.planning/phases/32-multi-step-onboarding-wizard/32-01-SUMMARY.md Normal file
View file

@ -0,0 +1,101 @@
---
phase: 32-multi-step-onboarding-wizard
plan: 01
subsystem: ui
tags: [react, onboarding, wizard, vitest, testing-library]
requires:
- phase: 31-puter.js-zero-config-cloud
provides: provider selection step, puter/google/apiKey credential capture in wizard state
provides:
- OnboardingSummaryStep component — read-only review card showing hardware, mode, provider, root dir
- Skip buttons on steps 1 and 2 (step 3 already had skip via ProviderSelectionStep)
- Step 4 "Review & finish" + "Skip to summary" buttons advancing to step 5
- Step 5 summary screen wired into NexusOnboardingWizard
- handleStartChat function creating workspace then opening chat panel (ONBD-06)
- Step indicator shows "Summary" on step 5 instead of "Step 5 of 4"
- deriveProviderLabel helper for human-readable provider display
affects: [onboarding, chat-panel, dashboard-navigation]
tech-stack:
added: []
patterns:
- OnboardingSummaryStep uses SummaryRow internal subcomponent for label-value pairs
- createWorkspace() refactored out of handleSubmit/handleStartChat to avoid duplication
- renderToStaticMarkup + fireEvent pattern for jsdom component tests without jest-dom
key-files:
created:
- ui/src/components/onboarding/OnboardingSummaryStep.tsx
- ui/src/components/onboarding/OnboardingSummaryStep.test.tsx
modified:
- ui/src/components/NexusOnboardingWizard.tsx
key-decisions:
- "createWorkspace() helper extracted so both handleSubmit and handleStartChat share workspace creation without duplication"
- "Tests use renderToStaticMarkup for static assertions + @testing-library/react fireEvent for click tests (no jest-dom or user-event available)"
- "Step 4 form submit removed — replaced with button advancing to step 5; actual workspace creation deferred to summary CTA"
patterns-established:
- "SummaryRow: internal non-exported subcomponent rendering label-value pair with optional mono font"
- "deriveProviderLabel: pure function mapping provider state to display string, placed outside component"
requirements-completed: [ONBD-04, ONBD-05, ONBD-06]
duration: 4min
completed: 2026-04-01
---
# Phase 32 Plan 01: Multi-Step Onboarding Wizard Summary
**5-step onboarding wizard with skip buttons on steps 1/2/4, summary screen as step 5, and "Start chatting" CTA that creates workspace then opens chat panel.**
## Performance
- **Duration:** 4 min
- **Started:** 2026-04-03T21:32:00Z
- **Completed:** 2026-04-03T21:36:00Z
- **Tasks:** 2
- **Files modified:** 3
## Accomplishments
- Created `OnboardingSummaryStep` component rendering hardware tier, mode, provider, and root directory in a bordered card with "Start chatting" CTA
- Added skip buttons on steps 1 (hardware), 2 (mode), and 4 (root dir) — fulfilling ONBD-04
- Wired summary as step 5 in `NexusOnboardingWizard` with step indicator showing "Summary" instead of "Step 5 of 4"
- Implemented `handleStartChat` that calls `createWorkspace()` then `setChatOpen(true)` after navigation — fulfilling ONBD-06
- Refactored shared workspace creation into `createWorkspace()` helper used by both submit paths
- 6 unit tests pass covering rendering, conditional root dir row, error display, click handler, loading/disabled state
## Task Commits
1. **Task 1: Create OnboardingSummaryStep component and tests** - `c0d7ea5a` (feat)
2. **Task 2: Wire summary step into wizard, add skip buttons, connect chat handoff** - `47630e53` (feat)
**Plan metadata:** (docs commit follows)
## Files Created/Modified
- `ui/src/components/onboarding/OnboardingSummaryStep.tsx` — Read-only summary card with SummaryRow subcomponent and Start chatting CTA
- `ui/src/components/onboarding/OnboardingSummaryStep.test.tsx` — 6 unit tests using renderToStaticMarkup + fireEvent
- `ui/src/components/NexusOnboardingWizard.tsx` — 5-step wizard with skip on 1/2/4, summary on step 5, createWorkspace helper, handleStartChat with setChatOpen(true)
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 1 - Bug] Replaced @testing-library/user-event with fireEvent**
- **Found during:** Task 1
- **Issue:** `@testing-library/user-event` is not installed in the project; only `@testing-library/react` and `renderToStaticMarkup` patterns are used
- **Fix:** Rewrote tests to use `renderToStaticMarkup` for static rendering assertions and `fireEvent.click` from `@testing-library/react` for interaction tests; also added `cleanup()` after each test to isolate renders
- **Files modified:** `ui/src/components/onboarding/OnboardingSummaryStep.test.tsx`
- **Commit:** c0d7ea5a
## Known Stubs
None — all rows display live wizard state passed as props.
## Self-Check: PASSED