# Requirements: Nexus v1.5 — Smart Onboarding + Personal AI Assistant

**Defined:** 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.

## v1.5 Requirements

### 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-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-07**: Local AI framed as privacy premium ("runs entirely on your machine, no accounts, works offline")

### Cloud Providers

- [x] **CLOUD-01**: User gets working AI via Puter.js with zero API keys and no sign-up required
- [x] **CLOUD-02**: Puter.js integrated as server-proxied adapter (not browser-direct) with full cost tracking
- [x] **CLOUD-03**: User can sign in via Google OAuth to access Gemini free tier
- [x] **CLOUD-04**: System auto-detects installed tools (Hermes, Claude Code, OpenClaw) and pre-fills configuration
- [x] **CLOUD-05**: User can enter API keys for subscription providers during onboarding

### Voice

- [ ] **VOICE-01**: User gets Piper TTS speech output that works on CPU-only hardware
- [ ] **VOICE-02**: Piper TTS pre-warms on first use with visible download progress (no silent 15-30s hang)
- [ ] **VOICE-03**: Voice features (Whisper STT + Piper TTS) offered during onboarding based on hardware capability

### Personal AI Assistant

- [ ] **ASST-01**: User has persistent memory across chat sessions (summary-based, injected into system prompts)
- [ ] **ASST-02**: Memory content sanitized at write time to prevent prompt injection
- [ ] **ASST-03**: User can hand off an assistant conversation to a PM agent with one click, transferring context
- [ ] **ASST-04**: Assistant and Project Builder modes work standalone or together

### CLI

- [ ] **CLI-01**: User can run `npx buildthis` to bootstrap Nexus from scratch
- [ ] **CLI-02**: CLI bootstrapper detects hardware and walks through the same provider tiering as web onboarding

## Future Requirements

### Cloud

- **CLOUD-F01**: OpenAI OAuth free tier (unstable API, defer to v2+)

### Assistant

- **ASST-F01**: MCP connections for assistant mode

### Voice

- **VOICE-F01**: Server-side TTS fallback for headless mode

## Out of Scope

| Feature | Reason |
|---------|--------|
| OpenAI OAuth | Endpoint specifics unstable, low confidence on free tier details |
| MCP tool connections | Complexity too high for v1.5; assistant works without it |
| Server-side Piper TTS | Browser WASM sufficient; headless is edge case |
| DB schema changes | Upstream sync constraint — all state in existing JSONB/files |
| Vector database for memory | Summary-based approach sufficient; no infra overhead |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| ONBD-01 | Phase 30 | Complete |
| ONBD-02 | Phase 30 | Complete |
| ONBD-03 | Phase 30 | Complete |
| ONBD-07 | Phase 30 | Complete |
| CLOUD-01 | Phase 31 | Complete |
| CLOUD-02 | Phase 31 | Complete |
| 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 |
| ASST-01 | Phase 33 | Pending |
| ASST-02 | Phase 33 | Pending |
| ASST-03 | Phase 33 | Pending |
| ASST-04 | Phase 33 | Pending |
| VOICE-01 | Phase 34 | Pending |
| VOICE-02 | Phase 34 | Pending |
| VOICE-03 | Phase 34 | Pending |
| CLI-01 | Phase 35 | Pending |
| CLI-02 | Phase 35 | Pending |

**Coverage:**
- v1.5 requirements: 21 total
- Mapped to phases: 21
- Unmapped: 0 ✓

---
*Requirements defined: 2026-04-02*
*Last updated: 2026-04-02 after roadmap created (phases 30-35)*