nexus/.planning/STATE.md

gsd_state_version	milestone	milestone_name	status	stopped_at	last_updated	last_activity	progress
1.0	v1.5	Smart Onboarding + Personal AI Assistant	verifying	Completed 35-npx-buildthis-cli/35-01	2026-04-03T23:03:36.034Z	2026-04-03	total_phases completed_phases total_plans completed_plans percent 6 6 13 13 0

Project State

Project Reference

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 35 — npx-buildthis-cli

Current Position

Phase: 35 Plan: Not started Status: Phase complete — ready for verification Last activity: 2026-04-03

Progress: [__________] 0%

Performance Metrics

Velocity:

• Total plans completed: 0 (v1.5)
• Average duration: -
• Total execution time: 0 hours

By Phase:

Phase	Plans	Total	Avg/Plan
-	-	-	-

Recent Trend:

• Last 5 plans: none yet (v1.5)
• Trend: -

Updated after each plan completion | Phase 30-hardware-detection-mode-selection P01 | 15 | 2 tasks | 8 files | | Phase 30-hardware-detection-mode-selection P02 | 15 | 2 tasks | 6 files | | Phase 31-puter.js-zero-config-cloud P01 | 4 | 2 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 P04 | 1 | 1 tasks | 0 files | | Phase 32-multi-step-onboarding-wizard P01 | 4 | 2 tasks | 3 files | | Phase 33 P01 | 4 | 2 tasks | 6 files | | Phase 33 P02 | 12 | 2 tasks | 8 files | | Phase 33-persistent-memory P03 | 20 | 2 tasks | 6 files | | Phase 34-voice P01 | 3 | 2 tasks | 7 files | | Phase 34-voice P02 | 4 | 2 tasks | 3 files | | Phase 35-npx-buildthis-cli P01 | 263 | 2 tasks | 11 files |

Accumulated Context

Decisions

Decisions are logged in PROJECT.md Key Decisions table. Key constraints for v1.5 (established at roadmap):

• No DB schema changes — all state in existing JSONB fields (instance_settings.general) and file-backed JSON (data/memory/<companyId>.json)
• Puter.js is server-proxied adapter only — @heyputer/puter.js browser import is for auth popup only; all AI calls via POST /api/puter-proxy/chat
• OAuth tokens (Google, Puter) stored server-side via secretService — never in localStorage
• Memory sanitization blocklist applied at write time, not retrieval time
• Apple Silicon: use os.freemem() × 0.75 for VRAM estimate; label as "unified memory" not "VRAM"; use systeminformation v5 (not v6)
• Unauthenticated GET /system/providers endpoint required for pre-auth hardware probe
• Google OAuth cloud tier: include but flag policy risk (Gemini CLI abuse detection issue #21866)
• Skip-all minimum valid state: one working agent with a valid provider must be created when user skips all steps
• [Phase 30-hardware-detection-mode-selection]: Hardware routes mounted before api Router to bypass boardMutationGuard; Apple Silicon detection via process.platform + cpuModel.startsWith('Apple') without calling si.graphics(); Promise.race 3s timeout on GPU probe for cpu_only fallback
• [Phase 30-hardware-detection-mode-selection]: Hardware probe is non-blocking — wizard step 1 always has an enabled Continue button regardless of probe outcome
• [Phase 30-hardware-detection-mode-selection]: Mode save on wizard completion is non-blocking — wrapped in try/catch, defaults to 'both' on failure
• [Phase 31-puter.js-zero-config-cloud]: agentId is optional in puterProxyService.chatStream — cost recording skipped when null/undefined to avoid FK violation in cost_events
• [Phase 31-puter.js-zero-config-cloud]: pendingPkce stores only verifier (no companyId) — company does not exist at authorize time during onboarding
• [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
• [Phase 33]: Removed zod dependency from assistant-memory.ts — replaced with manual type guard due to worktree node_modules not having zod symlink
• [Phase 33]: GitHub PAT regex changed from {36} to {36,} to handle tokens longer than the minimum expected length
• [Phase 33]: PersonalAssistant uses chatApi directly for standalone full-page chat (no ChatPanel dependency) — maintains worktree isolation for parallel execution
• [Phase 33]: useNexusMode defaults to 'both' while loading — prevents flash-redirect to dashboard on initial mount before settings resolve
• [Phase 33-persistent-memory]: Pre-fetch conversation/settings/memory BEFORE flushHeaders to avoid SSE header race (Pitfall 3 from research)
• [Phase 33-persistent-memory]: puterProxyService.resolveToken wrapped in try/catch — graceful fallback to streamEcho when no puter token configured
• [Phase 33-persistent-memory]: buildHandoffSummary exported as named pure function for direct unit testing without route test harness
• [Phase 34-voice]: chatFileRoutes registered inside boardMutationGuard after assistantHandoffRoutes; nexusSettingsRoutes also added (was missing)
• [Phase 34-voice]: voiceEnabled as Zod boolean with default(false) in nexus-settings — file-backed JSON, no DB migration
• [Phase 34-voice]: VoiceStep inserted at step 4; rootDir shifts to step 5, summary to step 6 — clean sequential numbering
• [Phase 34-voice]: TtsButton rendered inline in messages.map rather than inside MessageBubble — avoids prop drilling usePiperTts
• [Phase 35-npx-buildthis-cli]: detectHardware() accepts optional platform param for testability; getProviderOptions() extracted as pure function; controller.vram uses nullish coalescing for TypeScript strict mode

Pending Todos

None yet.

Blockers/Concerns

• [Phase 31] Puter.js Node.js server-side streaming API surface unverified — confirm stream: true works server-side before designing puterProxyService; plan-phase should include a research spike
• [Phase 31] Puter.js ToS on server-side request relaying unverified — attribute costs to user's Puter account in all UI copy as mitigation
• [Phase 33] Chat route injection point needs codebase inspection — confirm correct hook location in server/src/services/chat.ts during plan-phase
• [Phase 34] smart-whisper Apple Silicon acceleration claim unverified on Mac Mini M4 — fall back to tiny.en if base.en acceleration not confirmed on device

Session Continuity

Last session: 2026-04-03T23:00:01.397Z Stopped at: Completed 35-npx-buildthis-cli/35-01 Resume file: None