From dba88cd005c88dd35c8eff96a79de807126569b5 Mon Sep 17 00:00:00 2001 From: Nexus Dev Date: Fri, 3 Apr 2026 21:37:41 +0000 Subject: [PATCH] docs(32-01): complete multi-step-onboarding-wizard plan - 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 --- .planning/REQUIREMENTS.md | 12 +-- .planning/ROADMAP.md | 6 +- .planning/STATE.md | 27 ++--- .../32-01-SUMMARY.md | 101 ++++++++++++++++++ 4 files changed, 125 insertions(+), 21 deletions(-) create mode 100644 .planning/phases/32-multi-step-onboarding-wizard/32-01-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index ccaf285b..5cb04dc2 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -10,9 +10,9 @@ - [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-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 -- [ ] **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-04**: User can skip any onboarding step without blocking subsequent steps +- [x] **ONBD-05**: User sees summary screen showing configured providers and agent-model pairings +- [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") ### Cloud Providers @@ -78,9 +78,9 @@ | CLOUD-03 | Phase 31 | Complete | | CLOUD-04 | Phase 31 | Complete | | CLOUD-05 | Phase 31 | Complete | -| ONBD-04 | Phase 32 | Pending | -| ONBD-05 | Phase 32 | Pending | -| ONBD-06 | Phase 32 | Pending | +| ONBD-04 | Phase 32 | Complete | +| ONBD-05 | Phase 32 | Complete | +| ONBD-06 | Phase 32 | Complete | | ASST-01 | Phase 33 | Pending | | ASST-02 | Phase 33 | Pending | | ASST-03 | Phase 33 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index a3f9075c..7ee576da 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -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 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 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 @@ -144,7 +144,7 @@ Plans: **Plans**: 1 plan 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 ### 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 | | 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 | -| 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 | - | | 34. Voice | v1.5 | 0/TBD | Not started | - | | 35. npx buildthis CLI | v1.5 | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 1daaeac3..03308427 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,15 +2,15 @@ gsd_state_version: 1.0 milestone: v1.5 milestone_name: Smart Onboarding + Personal AI Assistant -status: executing -stopped_at: Completed 31-puter.js-zero-config-cloud/31-04 (verification plan, auto-approved) -last_updated: "2026-04-03T21:23:02.558Z" +status: verifying +stopped_at: Completed 32-multi-step-onboarding-wizard/32-01 +last_updated: "2026-04-03T21:37:28.251Z" last_activity: 2026-04-03 progress: total_phases: 6 - completed_phases: 2 - total_plans: 6 - completed_plans: 6 + completed_phases: 3 + total_plans: 7 + completed_plans: 7 percent: 0 --- @@ -21,13 +21,13 @@ progress: 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. -**Current focus:** Phase 31 — puter.js-zero-config-cloud +**Current focus:** Phase 32 — multi-step-onboarding-wizard ## Current Position -Phase: 32 -Plan: Not started -Status: Ready to execute +Phase: 32 (multi-step-onboarding-wizard) — EXECUTING +Plan: 1 of 1 +Status: Phase complete — ready for verification Last activity: 2026-04-03 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 P03 | 5 | 2 tasks | 6 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 @@ -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]: 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 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 @@ -96,6 +99,6 @@ None yet. ## Session Continuity -Last session: 2026-04-03T21:22:33.808Z -Stopped at: Completed 31-puter.js-zero-config-cloud/31-04 (verification plan, auto-approved) +Last session: 2026-04-03T21:37:28.248Z +Stopped at: Completed 32-multi-step-onboarding-wizard/32-01 Resume file: None diff --git a/.planning/phases/32-multi-step-onboarding-wizard/32-01-SUMMARY.md b/.planning/phases/32-multi-step-onboarding-wizard/32-01-SUMMARY.md new file mode 100644 index 00000000..273c9afb --- /dev/null +++ b/.planning/phases/32-multi-step-onboarding-wizard/32-01-SUMMARY.md @@ -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