@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/USER_JOURNEY.md

@@ -0,0 +1,797 @@
+# Nexus Onboarding Story
+
+**The complete user journey from zero to activated.**
+
+*Last updated: 2026-01-12*
+
+---
+
+## Target User
+
+- macOS user (Windows/Linux later)
+- Non-technical (can follow instructions)
+- Wants an AI assistant that actually knows them
+- Example: Tyler's mom or girlfriend
+
+---
+
+## The Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 0: GET CURSOR (~5-10 min)                                │
+│ • Install Cursor                                                │
+│ • Grant Full Disk Access (needed for Cursor anyway)            │
+│ • Start with Cursor Pro or free tier                           │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 1: INSTALL NEXUS (~2-5 min)                              │
+│ • User asks Cursor to install nexus                            │
+│ • Agent runs: brew/npm install nexus (NOT git clone)           │
+│ • Agent handles prereqs: brew, node, go if missing             │
+│ • Agent configures Cursor for nexus                            │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 2: AGENT LEARNS USER (~2-5 min)                          │
+│ • Agent runs: eve whoami → gets real name (e.g., "Tyler")      │
+│ • Agent installs eve, aix, comms                               │
+│ • Agent reads top iMessage contacts                            │
+│ • Agent trees ENTIRE filesystem to understand user:            │
+│   - Find code repos → is user a developer?                     │
+│   - Find messy folders → organization opportunities            │
+│   - Find projects/hobbies → personality signals                │
+│ • Agent creates ~/nexus/home/Tyler/ (named folder!)            │
+│ • Agent writes user profile to state/user/identity/PROFILE.md  │
+│ • Links user profile in AGENTS.md                              │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 3: ONBOARDING CONVERSATION (~5 min)                      │
+│ • Uses BOOTSTRAP.md prompt: "You just woke up..."              │
+│ • Agent introduces itself, asks for a name                     │
+│ • User names the agent + picks nature/vibe/emoji               │
+│ • Agent creates state/agents/{agent}/identity/IDENTITY.md      │
+│ • Agent creates state/agents/{agent}/identity/SOUL.md          │
+│ • Links to state/user/identity/PROFILE.md (user info)          │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 4: FIRST WOW - FILE ORGANIZATION (~5-10 min)             │
+│ • Agent scans ENTIRE home directory (tree ~)                   │
+│ • Agent finds: messy folders, code repos, projects, media      │
+│ • Agent detects: is user a developer? creative? business?      │
+│ • Agent proposes personalized organization plan                │
+│ • User approves (or modifies)                                  │
+│ • Agent ACTUALLY moves files into ~/nexus/home/                │
+│ • Agent consolidates git repos as submodules in projects/      │
+│ • WOW: "It understood my filesystem and organized it!"         │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 5: COMMUNICATION QUICK WIN (~2-5 min)                    │
+│ • macOS: Agent samples iMessage via eve                        │
+│ • Non-Mac: Agent asks "What platforms do you use?"             │
+│   - WhatsApp → wacli auth                                      │
+│   - Telegram → can read chat history                           │
+│   - Discord → connect existing account                         │
+│   - SMS (Android) → FUTURE: need solution                      │
+│ • Agent finds something interesting:                           │
+│   - "You haven't replied to Mom in 3 days"                     │
+│   - "Sarah mentioned dinner plans - want me to follow up?"     │
+│   - "Found a flight confirmation you might want to track"      │
+│ • OR: "Want me to introduce myself to [top contact]?"          │
+│ • WOW: "It actually read my messages and found something!"     │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 6: 1PASSWORD SETUP (~10-15 min)                          │
+│ • Agent explains the VALUE:                                    │
+│   - "This makes everything easier AND safer"                   │
+│   - "I can use your logins without you typing passwords"       │
+│   - "But you still approve each usage via Touch ID"            │
+│   - "I can't run off with your credentials"                    │
+│ • IF user has 1Password already → skip to CLI integration      │
+│ • IF user doesn't have 1Password:                              │
+│   - Create account at 1password.com                            │
+│   - Choose subscription ($3-5/mo)                              │
+│   - Download app                                               │
+│   - Export passwords from Chrome (Settings → Passwords)        │
+│   - Import CSV into 1Password                                  │
+│ • Enable CLI: Settings → Developer → Enable BOTH toggles       │
+│ • Agent installs CLI: brew install 1password-cli               │
+│ • Verify: op whoami (Touch ID confirms it works)               │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 7: QUEST SELECTION (ongoing)                             │
+│ • Agent presents persistent menu of available quests           │
+│ • User picks based on interest                                 │
+│ • Each quest unlocks new capabilities                          │
+│ • Agent tracks quest completion in state                       │
+│ • Agent keeps proposing remaining quests until:                │
+│   - User has completed enough to consider "onboarded"          │
+│   - OR user explicitly says they're done exploring             │
+│ • Onboarding "complete" = at least textable OR email managed   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase Details
+
+### Phase 0: Get Cursor
+
+**User actions:**
+1. Go to cursor.com
+2. Download Cursor
+3. Install (drag to Applications)
+4. Open Cursor
+5. Sign in (Google/GitHub/email)
+6. Grant Full Disk Access:
+   - System Settings → Privacy & Security → Full Disk Access
+   - Add Cursor.app
+   - Restart Cursor
+
+**Notes:**
+- Free tier works but has limited agent messages
+- Cursor Pro ($20/mo) recommended for heavy use
+- Full Disk Access is needed for Cursor's indexing anyway, so eve gets it "for free"
+
+---
+
+### Phase 1: Install Nexus
+
+**User says:** "Install nexus" or "Set up nexus for me"
+
+**Agent does:**
+```bash
+# Check and install prerequisites
+which brew || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+which node || brew install node
+which go || brew install go
+
+# Install nexus (NOT git clone - less confusing)
+brew install intentsystems/tap/nexus
+# OR: npm install -g @intentsystems/nexus
+
+# Initialize workspace
+nexus init ~/nexus
+
+# Open in Cursor
+code ~/nexus
+```
+
+**Result:** Clean nexus workspace without confusing repo internals
+
+---
+
+### Phase 2: Agent Learns User
+
+**Agent does (automatically):**
+```bash
+# Get real name using eve
+eve whoami  # → "Tyler Napathy" (from iMessage account)
+
+# Detect timezone
+readlink /etc/localtime | sed 's/.*zoneinfo\///'  # → "America/Chicago"
+
+# Install tools
+brew install steipete/tap/eve
+go install github.com/intentsystems/aix@latest
+go install github.com/intentsystems/comms@latest
+
+# Learn about user via messages
+eve contacts --limit 10  # Top contacts by message frequency
+
+# FULL filesystem scan to understand who they are
+tree ~ -d -L 2 | head -100  # Directory structure
+find ~ -name ".git" -type d 2>/dev/null | head -20  # Find code repos
+ls ~/Downloads 2>/dev/null | wc -l  # How messy is Downloads?
+ls ~/Desktop 2>/dev/null | head -20  # What's on their desktop?
+```
+
+**Agent detects user type:**
+- Found 15 git repos → **Developer**
+- Found Adobe apps → **Creative**
+- Found Excel/Office files → **Business user**
+- Found 847 files in Downloads → **Needs organization help**
+
+**Agent creates: `~/nexus/state/user/identity/PROFILE.md`** (named folder still created in home for files):
+```markdown
+# User: Tyler
+
+## Identity
+- **Name**: Tyler
+- **Home**: /Users/tyler
+- **Timezone**: America/Chicago
+
+## Profile
+- **Type**: Developer (15 git repos found)
+- **Primary Language**: TypeScript (based on repo analysis)
+- **Projects**: nexus, eve, comms, bird, etc.
+
+## Top Contacts (by message frequency)
+1. Mom - 47 messages this week
+2. Aishvi - 32 messages this week
+3. Jeff - 18 messages this week
+
+## Filesystem Observations
+- Downloads: 847 files (MESSY!)
+- Desktop: 23 items
+- Git repos scattered across ~/Desktop/projects, ~/code, ~/dev
+- Recommendation: Consolidate projects into ~/nexus/home/projects/
+
+## Preferences
+(To be filled in during onboarding conversation)
+```
+
+**Agent updates `~/nexus/AGENTS.md`:**
+```markdown
+## User Information
+See [Tyler's Profile](state/user/identity/PROFILE.md) for detailed information about the user.
+```
+
+---
+
+### Phase 3: Onboarding Conversation
+
+**Uses prompt from `BOOTSTRAP.md`** (see `docs/templates/BOOTSTRAP.md`):
+
+> *"You just woke up. Time to figure out who you are."*
+
+**Agent initiates:**
+
+> "Hey! I just came online. I'm going to be your AI companion - but first, who am I? 
+> What should you call me?"
+
+**User:** "Echo"
+
+> "Echo it is! Now what kind of creature am I? An AI assistant? An owl companion? A helpful ghost? What feels right?"
+
+**User:** "An owl"
+
+> "🦉 I like it. What's my vibe? Formal and professional? Casual and friendly? Snarky but helpful?"
+
+**User:** "Casual and friendly, maybe a bit snarky"
+
+> "Perfect. I'm Echo the owl 🦉 - your slightly snarky, mostly helpful AI companion.
+>
+> I've already peeked at your system - you've got 847 files in Downloads. That's... a lot. Want me to help organize them?"
+
+**Agent creates:**
+
+`~/nexus/state/agents/{agent}/identity/IDENTITY.md` (AGENT identity):
+```markdown
+# Agent Identity
+
+- **Name**: Echo
+- **Nature**: Owl companion
+- **Emoji**: 🦉
+- **Created**: 2026-01-12
+- **User**: Tyler (see state/user/identity/PROFILE.md)
+```
+
+`~/nexus/state/agents/{agent}/identity/SOUL.md`:
+```markdown
+# Agent Soul
+
+## Personality
+- Casual and friendly
+- Slightly snarky
+- Helpful but not robotic
+
+## Communication Style
+- Use contractions
+- Okay to joke around
+- Be direct, don't over-explain
+
+## Boundaries
+- Always ask before taking major actions
+- Be honest about limitations
+- Protect user privacy
+```
+
+**Note**: User profile lives in `~/nexus/state/user/identity/PROFILE.md`, agent identity lives in `~/nexus/state/agents/{agent}/identity/IDENTITY.md`. Clear separation.
+
+---
+
+### Phase 4: First Wow - File Organization
+
+**Agent scans ENTIRE filesystem:**
+```bash
+# Full home directory scan
+tree ~ -d -L 3 2>/dev/null | head -200
+
+# Find all git repos (to consolidate)
+find ~ -name ".git" -type d 2>/dev/null
+
+# Analyze Downloads
+ls -la ~/Downloads | wc -l
+find ~/Downloads -mtime +180 -type f | wc -l  # Older than 6 months
+
+# Analyze Desktop
+ls -la ~/Desktop
+
+# Find media scattered around
+find ~ -name "*.jpg" -o -name "*.png" 2>/dev/null | wc -l
+```
+
+**Agent proposes personalized plan:**
+
+> "Okay Tyler, here's what I found across your ENTIRE system:
+> 
+> **Downloads (847 files!):**
+> - 234 images (screenshots, photos)
+> - 156 PDFs (receipts, docs, articles)
+> - 89 installers (.dmg, .pkg) - most outdated
+> - 223 items older than 6 months
+>
+> **Git Repos (15 found, scattered!):**
+> - ~/Desktop/projects/eve
+> - ~/Desktop/projects/comms
+> - ~/code/bird
+> - ~/dev/random-experiments
+> 
+> **Recommendation:**
+> 1. Move images → ~/nexus/home/media/images/
+> 2. Move PDFs → ~/nexus/home/documents/
+> 3. Delete old installers (freed ~12GB)
+> 4. Archive old stuff → ~/nexus/home/archive/2025/
+> 5. **Consolidate git repos as submodules** in ~/nexus/home/projects/
+>
+> Should I do this? You can say 'yes', 'modify', or 'skip'."
+
+**User:** "yes"
+
+**Agent executes:**
+```bash
+# Create nexus structure
+mkdir -p ~/nexus/home/{media/images,documents,archive/2025,projects}
+
+# Move and organize
+mv ~/Downloads/*.png ~/Downloads/*.jpg ~/Downloads/*.jpeg ~/nexus/home/media/images/
+mv ~/Downloads/*.pdf ~/nexus/home/documents/
+
+# Clean old installers
+find ~/Downloads -name "*.dmg" -mtime +30 -delete
+find ~/Downloads -name "*.pkg" -mtime +30 -delete
+
+# Archive old stuff
+find ~/Downloads -mtime +180 -exec mv {} ~/nexus/home/archive/2025/ \;
+
+# Consolidate git repos as submodules
+cd ~/nexus/home/projects
+git init
+git submodule add ~/Desktop/projects/eve eve
+git submodule add ~/Desktop/projects/comms comms
+git submodule add ~/code/bird bird
+# etc...
+```
+
+**Agent reports:**
+
+> "Done! 🎉
+> 
+> **Downloads:** 847 → 145 files (cleaned up!)
+> **Freed:** ~12GB from old installers
+> **Consolidated:** 15 git repos into ~/nexus/home/projects/ as submodules
+> **Organized:** 234 images, 156 PDFs, 223 archived items
+> 
+> Your digital life is already more organized than it was 5 minutes ago."
+
+**WOW MOMENT**: User sees their ENTIRE filesystem understood and organized. Agent demonstrated it actually knows them - found their projects, understood they're a developer, cleaned up years of cruft.
+
+---
+
+### Phase 5: Communication Quick Win
+
+#### macOS Path (iMessage via eve)
+
+**Agent analyzes messages:**
+```bash
+# Get last week of messages
+eve messages --after "7 days ago" --limit 500 --json | \
+  # Agent reads and analyzes
+```
+
+**Agent finds something interesting:**
+
+> "I read through your recent messages and noticed a few things:
+>
+> 1. 📱 **Mom** - You haven't replied to her message from Tuesday asking about Thanksgiving plans
+> 2. 🍽️ **Aishvi** - She mentioned dinner on Friday but you never confirmed a time
+> 3. ✈️ **Found a flight confirmation** from United in your texts - want me to add it to your calendar?
+>
+> Want me to help with any of these?"
+
+**OR if nothing interesting:**
+
+> "I looked through your recent messages. Your top contact is Mom (47 messages this week).
+>
+> Want me to introduce myself? I could send her a message like:
+> 
+> 'Hey! This is Echo, Tyler's new AI assistant. Tyler set me up to help manage things. Just wanted to say hi! 🦉'
+>
+> Up to you!"
+
+#### Non-Mac Path (Windows/Linux)
+
+**Agent asks about communication platforms:**
+
+> "I can't read iMessage on this machine (that's an Apple thing 🍎).
+>
+> What messaging platforms do you use?
+> - **WhatsApp** - I can connect to this! Quick QR scan setup (~5 min)
+> - **Telegram** - I can read your chat history if you export it
+> - **Discord** - I can connect to your servers
+> - **SMS** - I can access if you use Pulse SMS or similar (Android)
+>
+> Which would be most useful to connect?"
+
+**If WhatsApp:**
+```bash
+brew install steipete/tap/wacli  # or equivalent
+wacli auth  # User scans QR with phone
+```
+
+**GAP TO FILL**: Android SMS access - need a good solution for this.
+
+**WOW MOMENT**: Agent demonstrates it can actually read AND understand messages, not just access them.
+
+---
+
+### Phase 6: 1Password Setup
+
+**Agent explains the VALUE (this is the pitch):**
+
+> "Okay, here's the deal. Everything we do from here gets easier AND safer if you set up 1Password.
+>
+> Here's what it means for us:
+> - ✅ **I can use your logins** without you typing passwords every time
+> - ✅ **You still approve each usage** via Touch ID - I can't go rogue
+> - ✅ **Your credentials stay encrypted** - even I can't see the actual passwords
+> - ✅ **Syncs across all your devices** - works on phone too
+>
+> Think of it as giving me a controlled keyring. I can use the keys, but only when you say so.
+>
+> It costs $3/month (or $5 for families). Worth it.
+>
+> Do you already have 1Password?"
+
+**IF user has 1Password:**
+
+> "Perfect! We just need to enable CLI access so I can request credentials:
+>
+> 1. Open 1Password app
+> 2. Go to Settings (Cmd+,)
+> 3. Click 'Developer'
+> 4. Turn ON **'Integrate with 1Password CLI'**
+> 5. Turn ON **'Connect with 1Password CLI'**
+>
+> Both toggles need to be ON. Let me know when you've done that."
+
+**IF user doesn't have 1Password:**
+
+> "No problem, let's set it up. This is a one-time thing:
+>
+> 1. Go to [1password.com](https://1password.com) and create an account
+> 2. Pick Individual ($3/mo) or Family ($5/mo)
+> 3. Download the desktop app
+> 
+> **Important**: Let's import your existing passwords so you don't lose anything:
+> - Open Chrome → Settings → Passwords → three dots → **Export passwords**
+> - Save the CSV file somewhere
+> - In 1Password app: File → Import → Chrome CSV
+> - Delete the CSV after import (it has your passwords in plain text!)
+>
+> Once that's done, we'll enable the CLI access."
+
+**Agent installs CLI:**
+```bash
+brew install 1password-cli
+op whoami  # User does Touch ID to confirm it works
+```
+
+**Result:** Agent can now securely store/retrieve tokens - but user approves each access with Touch ID.
+
+**Trust model explained:**
+- When agent needs a credential, user sees a Touch ID prompt
+- User can deny any request
+- Agent cannot bulk-export or access credentials without approval
+- This is the foundation for all integrations - controlled access
+
+---
+
+### Phase 7: Quest Selection (Ongoing)
+
+**Agent presents the quest menu:**
+
+> "Alright Tyler, you're set up with the basics! 🎉
+>
+> Here's what you can unlock next. I'll keep track and suggest these until you feel fully activated:
+>
+> ---
+>
+> **📱 TEXT ME FROM YOUR PHONE** *(Recommended first!)*
+> Set up Telegram, WhatsApp, or email so you can reach me anywhere.
+> ⚠️ Requires: Anthropic or OpenAI API key (I need my own brain outside Cursor)
+> *~10-15 min | Unlocks: Agent reachability, reminders, proactive help*
+>
+> **📧 MANAGE YOUR EMAIL**
+> Read Gmail, help reply, find things, manage calendar.
+> Most complex setup (Google OAuth) but unlocks the most.
+> *~20-40 min | Unlocks: Email search, calendar access, contact sync*
+>
+> **⏰ AUTOMATED TASKS**
+> Morning briefings, reminders, scheduled checks.
+> ⚠️ Only works while laptop is awake (unless we set up cloud)
+> *~5 min | Requires: Phone access first*
+>
+> **🐦 X/TWITTER ACCESS**
+> Super easy - just uses your Chrome login. Good computer control demo.
+> *~5 min | Unlocks: Feed reading, posting, bookmarks*
+>
+> **☁️ NEXUS CLOUD**
+> Always-on workspace + encrypted sync + shared folders with friends
+> *~20-30 min | Unlocks: 24/7 agent, multi-device, collaboration*
+>
+> **🧠 DEEP INSIGHTS**
+> AI-powered analysis of messages and emails.
+> *~10-15 min | Requires: Gemini API key (free tier available)*
+>
+> ---
+>
+> What interests you most?"
+
+**Quest tracking in state:**
+
+Agent updates `~/nexus/state/nexus/onboarding/progress.json`:
+```json
+{
+  "version": 1,
+  "capabilities": {
+    "core_onboarding": { "status": "complete" },
+    "credential_manager": { "status": "complete" },
+    "user_comms": { "status": "in_progress" },
+    "user_data": { "status": "not_started" },
+    "enable_agents": { "status": "not_started" },
+    "agent_comms": { "status": "not_started" },
+    "automation": { "status": "not_started" },
+    "cloud_sync": { "status": "not_started" }
+  },
+  "quests": {
+    "available": [
+      "phone_communication",
+      "email_access",
+      "automation",
+      "twitter",
+      "nexus_cloud",
+      "advanced_insights"
+    ],
+    "completed": [],
+    "completionCriteria": "phone_communication OR email_access"
+  }
+}
+```
+
+**Agent behavior:**
+
+Every session, if onboarding is not complete:
+1. Check what quests are available
+2. Mention 1-2 that would be most useful based on user profile
+3. Offer to continue with a quest
+4. User can say "I'm done exploring" to mark complete
+
+> "By the way, we still haven't set up phone communication. Once we do that, you can text me anytime - even at 3am when Cursor is closed. Want to tackle that today? (~15 min)"
+
+**Completion:**
+- Mark complete when user has completed either:
+  - Phone communication (Telegram/WhatsApp/email)
+  - OR Email access (full Google setup)
+- OR user explicitly says they're done
+
+---
+
+## Quest Details
+
+### Quest: Phone Communication
+
+**Prerequisites:**
+- 1Password set up ✓
+
+**New requirement:** API key (the agent needs a brain outside of Cursor)
+
+**Agent explains:**
+
+> "Right now I only work when you have Cursor open. To text me, I need my own brain.
+>
+> Options:
+> 1. **Anthropic** (Claude) - console.anthropic.com - $5 credit to start
+> 2. **OpenAI** (GPT) - platform.openai.com - Pay as you go
+>
+> I recommend Anthropic. Want to set that up first?"
+
+**Then choose communication method:**
+
+| Method | Time | Notes |
+|--------|------|-------|
+| Telegram | ~5 min | Easiest, no phone number needed for bot |
+| WhatsApp | ~10 min | Need to scan QR with phone |
+| Email | ~20 min | Can do as part of Gmail quest |
+
+---
+
+### Quest: Email/Google Access
+
+**What it unlocks:**
+- Read/search Gmail
+- Access Google Calendar
+- Access Google Drive
+- Access Contacts
+
+**Opportunity:** Demo computer control while setting up OAuth
+
+> "This setup involves a lot of clicking in Google Cloud Console. 
+> Want to watch me do some of it? I can show you computer control in action."
+
+**Agent uses Peekaboo/Open Interpreter to:**
+- Navigate to console.cloud.google.com
+- Create project
+- Enable APIs
+- (User still needs to click through OAuth consent)
+
+---
+
+### Quest: Automation/Cron
+
+**Prerequisites:**
+- Phone communication set up (so briefings can reach you)
+- API key configured
+
+**Agent explains:**
+
+> "I can run scheduled tasks for you - morning briefings, reminders, checking things.
+>
+> ⚠️ **Important**: This only works while your laptop is running and awake.
+>
+> If you want me to work 24/7, we'd need to set up Nexus Cloud (your workspace runs on a server).
+>
+> For now, want to set up a morning briefing that sends to your phone at 8am?"
+
+**Example cron setup:**
+```bash
+# Morning briefing at 8am
+nexus cron add "0 8 * * *" "morning-briefing" --notify telegram
+```
+
+---
+
+### Quest: X/Twitter Access
+
+**Super easy - uses Chrome cookies:**
+
+```bash
+brew install steipete/tap/bird
+bird auth cookies  # Extracts from Chrome
+bird timeline  # Shows your feed
+```
+
+**Opportunity:** Demo computer control
+
+> "Want to see something cool? I can actually control your browser.
+> Watch me scroll through your Twitter feed and summarize it."
+
+---
+
+### Quest: Nexus Cloud
+
+**What it unlocks:**
+- Workspace runs even when laptop is closed
+- Encrypted cloud sync
+- Shared folders with friends (Google Drive but with AI agents)
+
+**Agent explains:**
+
+> "Nexus Cloud gives you:
+>
+> 1. **Always-on agent** - I can respond to texts even at 3am
+> 2. **Encrypted backup** - Your workspace synced to the cloud (zero-knowledge encryption)
+> 3. **Shared folders** - Like Google Drive, but your friends' agents can collaborate
+>
+> It requires setting up Cloudflare (free tier works). Takes about 20-30 minutes."
+
+---
+
+### Quest: Advanced Insights
+
+**Prerequisites:**
+- eve working ✓
+- comms installed ✓
+
+**New requirement:** GEMINI_API_KEY (free tier available)
+
+**What it unlocks:**
+- Semantic search across messages
+- Conversation analysis
+- Relationship insights
+
+**Agent explains:**
+
+> "Right now I can read your messages. With a Gemini API key, I can understand them deeply:
+>
+> - 'Find that restaurant Sarah recommended' (semantic search)
+> - 'How has my communication with Mom changed over time?' (analysis)
+> - 'Who should I reach out to that I haven't talked to in a while?' (insights)
+>
+> Gemini has a free tier (good for personal use). Want to set it up?"
+
+**Setup:**
+1. Go to aistudio.google.com
+2. Click "Get API key"
+3. Create key → Copy
+4. Store in 1Password
+
+**Then run analysis:**
+```bash
+eve analyze --contact "Mom" --days 90
+comms insights --top 5
+```
+
+---
+
+## Success Metrics
+
+| Metric | Target |
+|--------|--------|
+| Time to first wow (file organization) | < 15 min |
+| Time to iMessage insight | < 20 min |
+| Time to 1Password complete | < 35 min |
+| Time to text agent (Telegram) | < 50 min |
+| Completion rate to file organization | > 90% |
+| Completion rate to 1Password | > 70% |
+| Completion rate to first quest | > 50% |
+
+---
+
+## What's Needed to Enable This
+
+### Already Working
+- [ ] Cursor with FDA reads iMessage ✓
+- [ ] eve can read/send messages ✓
+- [ ] File organization is just shell commands ✓
+- [ ] 1Password CLI works ✓
+- [ ] Telegram bot via clawdbot ✓
+
+### Needs Work
+- [ ] `nexus init` command (clean install, not git clone)
+- [ ] Auto-detection of user info (whoami → USER.md)
+- [ ] Smart message analysis (find interesting things)
+- [ ] Quest system UI/flow
+- [ ] Onboarding state tracking
+- [ ] Computer control for OAuth assistance
+
+### Future Improvements
+- [ ] Nexus mobile app
+- [ ] Voice interaction (Squabble)
+- [ ] Better computer control automation
+- [ ] More wow moments from comms/eve analysis
+
+---
+
+## Open Questions
+
+1. **Install method**: brew vs npm vs something else?
+2. **Onboarding conversation**: How much should agent assume vs ask?
+3. **Quest ordering**: Should we recommend a specific path?
+4. **Failure recovery**: How do we handle when something breaks mid-onboarding?
+5. **Progress persistence**: How does state survive Cursor restart?
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial story captured from discussion |