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	executing	Completed 31-puter.js-zero-config-cloud/31-03 (2 tasks, 6 files, provider selection UI complete)	2026-04-03T00:44:22.867Z	2026-04-03	total_phases completed_phases total_plans completed_plans percent 6 1 6 5 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 31 — puter.js-zero-config-cloud

Current Position

Phase: 31 (puter.js-zero-config-cloud) — EXECUTING Plan: 4 of 4 Status: Ready to execute 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 |

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

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-03T00:44:22.863Z Stopped at: Completed 31-puter.js-zero-config-cloud/31-03 (2 tasks, 6 files, provider selection UI complete) Resume file: None