@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/WOW_MOMENTS.md

@@ -0,0 +1,232 @@
+# Wow Moments & Activation Thresholds
+
+**Goal**: Document all the "wow moments" that hook users and create activation thresholds to maximize onboarding completion.
+
+---
+
+## What is a Wow Moment?
+
+A wow moment is when the user realizes "holy shit, this actually works" — it breaks their mental model of what's possible and creates emotional investment.
+
+**Good wow moments are:**
+- Immediate (happens fast)
+- Tangible (they can see/feel the result)
+- Personal (uses their actual data)
+- Unexpected (exceeds their expectations)
+
+---
+
+## Wow Moments Catalog
+
+### 🟢 Tier 1: No Setup Required (Instant)
+
+| Moment | What Happens | User Reaction | Dependency |
+|--------|--------------|---------------|------------|
+| **Filesystem Organization** | Agent ACTUALLY organizes Downloads into nexus, files appear in their workspace | "Holy shit it's actually moving my files!" | None (just needs file access) |
+| **Voice Control (Squabble)** | User talks to agent out loud, agent responds | "I can just TALK to it?!" | Squabble/speech installed |
+| **Watch Browser Automation** | Agent uses computer-use to navigate a website while user watches | "It's controlling my browser!" | computer-use |
+
+**Note**: Weather and Cursor history alone are "meh" - only use as part of a larger demo (morning briefing).
+
+
+### 🟡 Tier 2: Minimal Setup (5-10 min)
+
+| Moment | What Happens | User Reaction | Dependency |
+|--------|--------------|---------------|------------|
+| **Read Your Texts + Suggest Reply** | Agent reads recent iMessages, notices you haven't replied to Mom, drafts response | "It knows I should text Mom!" | eve + Full Disk Access |
+| **Email Deep Insight** | Agent finds something INTERESTING - job offers, awards, big purchases, important receipts | "It found my job offer from last year!" | gog OAuth |
+| **Calendar Intelligence** | Agent identifies interesting upcoming events for next month, OR connects events: "I see you're meeting X for dinner tomorrow - want me to add this to your calendar?" | "It understood the context!" | gog OAuth + eve (cross-channel) |
+| **Tweet/X Feed Summary** | Agent summarizes what your feed is talking about, or analyzes your own tweets | "It reads my Twitter?!" | bird (Chrome cookies) |
+
+**Key insight**: The wow is not just READING data, it's finding something INTERESTING or ACTIONABLE about them personally.
+
+### 🟠 Tier 3: Moderate Setup (15-20 min)
+
+| Moment | What Happens | User Reaction | Dependency |
+|--------|--------------|---------------|------------|
+| **Agent Texts You** | User receives actual text message from their agent | "I CAN TEXT MY AI?!" | Telegram/WhatsApp/iMessage + Anthropic API |
+| **Morning Briefing** | Automated morning message: weather + calendar + email urgents | "It's like having an assistant!" | gog + cron + reachability |
+| **Cross-Channel Identity Link** | Agent finds same person across email AND texts by linking identities | "It knows Mom's email AND phone?!" | eve + gog + comms (identity linking) |
+| **Onboarding Reminder** | During onboarding, agent sets a reminder to continue tomorrow, user gets actual text | "Oh cool, it reminded me to finish setup!" | cron + reachability |
+
+**Key insight**: Agent texting you is THE moment. Everything before is building to this. Telegram is fastest path (no phone needed for bot).
+
+### 🔴 Tier 4: Advanced Setup (30+ min)
+
+| Moment | What Happens | User Reaction | Dependency |
+|--------|--------------|---------------|------------|
+| **Phone Call from Agent** | User gets actual phone call from their AI | "MY AI CALLED ME" | Voice setup (Twilio) |
+| **Smart Home Control** | "Turn off the lights" actually turns off lights | "It controls my house!" | openhue/sonos |
+| **Reactive Automation** | Agent detects airline checkin email, automatically checks them in using browser-use | "It checked me in without me asking?!" | gog + computer-use + cron (reactive trigger) |
+| **Multi-Agent Coordination** | Agent delegates task to specialized sub-agent, reports back | "It has minions?!" | coding-agent, subagent pattern |
+
+**Key insight**: These are "holy shit" moments but require significant setup. Save for power users or post-activation.
+
+---
+
+## Activation Thresholds
+
+Based on product activation research, users need to hit certain milestones to become "activated" (likely to continue using).
+
+### Threshold 1: "This is real" (5 min)
+- Agent has a name
+- Agent did ONE thing with their actual data
+- Recommended: Filesystem scan or weather
+
+### Threshold 2: "This is useful" (15 min)  
+- Agent accessed a communication channel (email OR messages)
+- Agent provided actionable insight ("you should reply to X")
+- Recommended: eve read-only OR gog email
+
+### Threshold 3: "This is a presence" (30 min)
+- User can REACH the agent outside of Cursor
+- Agent sent them a message they received on their phone
+- Recommended: Telegram bot (easiest)
+
+### Threshold 4: "This is my assistant" (60+ min)
+- Multiple data sources connected
+- Recurring automated value (morning briefings)
+- User has texted agent and received useful response
+
+---
+
+## Wow Moment Priority for Onboarding
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  RECOMMENDED WOW MOMENT SEQUENCE                                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  1️⃣  IMMEDIATE: Filesystem Scan (~0 min setup)                              │
+│      "I see 147 files in Downloads. Want me to organize them?"              │
+│      → Proves agent can see their system, requires NO setup                 │
+│                                                                             │
+│  2️⃣  QUICK WIN: Read Messages or Email (~5-10 min)                          │
+│      "You have 3 unread texts from Mom. The last one says..."               │
+│      "You have 12 unread emails. 2 look urgent: [subject lines]"            │
+│      → Proves agent can access personal data, requires one OAuth            │
+│                                                                             │
+│  3️⃣  MAGIC MOMENT: Agent Texts You (~15-20 min)                             │
+│      [User's phone buzzes with message from agent]                          │
+│      → This is THE moment. Agent becomes real. Telegram is fastest.         │
+│                                                                             │
+│  4️⃣  RECURRING VALUE: Morning Briefing (~5 min after #3)                    │
+│      Set up daily 7am briefing: weather + calendar + urgent emails          │
+│      → Proves ongoing value, creates habit                                  │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Measuring Activation
+
+### Key Questions
+- Did the user name their agent? (Identity)
+- Did the agent access any of their data? (Data access)
+- Did the user receive a message from the agent on their phone? (Reachability)
+- Did the user set up any recurring automation? (Stickiness)
+
+### Activation Score
+
+```
+Activation Score = sum of completed milestones
+
+0 points: Installed but not started
+1 point:  Named agent (identity)
+2 points: 1Password configured
+3 points: First data source connected (eve OR gog)
+4 points: Agent sent them a message they received
+5 points: Set up recurring automation (cron job)
+6 points: Second data source connected
+7 points: Multi-channel unified (comms working)
+
+Score 0-2: Not activated (will likely churn)
+Score 3-4: Partially activated (may continue)
+Score 5+:  Fully activated (likely to stick)
+```
+
+---
+
+## Anti-Patterns (What Kills Wow Moments)
+
+| Anti-Pattern | What Happens | How to Avoid |
+|--------------|--------------|--------------|
+| **Too much setup before value** | User gets bored before seeing anything useful | Filesystem scan FIRST (no setup) |
+| **OAuth flow fails** | User clicks wrong button, gets error | Provide screenshots, fallback instructions |
+| **Overwhelming options** | User doesn't know what to do next | Present ONE choice at a time |
+| **Technical language** | User doesn't understand "OAuth" or "Full Disk Access" | Use human language: "Let me see your emails" |
+| **Long waits** | User waits while something installs/indexes | Show progress, explain what's happening |
+| **Privacy concerns not addressed** | User worried about data leaving machine | Explain tiers: local-only vs cloud analysis |
+
+---
+
+## Wow Moment Scripts
+
+### Script: Filesystem Scan
+
+```
+Agent: "Hey! I just noticed I have access to your filesystem. Want me to take a 
+look around? I won't change anything, just observe."
+
+User: "Sure"
+
+Agent: "Okay, here's what I found:
+- Downloads: 147 files (42 MB) - last organized never 😅
+- Documents: 823 files across 12 folders
+- Desktop: 34 items (it's getting cluttered)
+
+I notice a lot of PDF receipts in Downloads that could be organized by date.
+Want me to propose an organization plan? I can move things into your nexus 
+where they'll be easier to find later."
+```
+
+### Script: First Text Received
+
+```
+[User's phone buzzes]
+
+From: Echo (Telegram)
+"Hey! 👋 This is Echo, your Nexus agent. I'm sending this from Telegram to 
+prove I can reach you here. Pretty cool, right?
+
+By the way, I noticed you have 3 unread emails from today. Want me to 
+summarize them?"
+```
+
+### Script: Morning Briefing
+
+```
+[7:00 AM - User's phone buzzes]
+
+From: Echo (Telegram)
+"Good morning! ☀️
+
+🌤️ Weather: 68°F, partly cloudy. Perfect for that outdoor meeting.
+
+📅 Today:
+- 9:00 AM: Standup (Zoom)
+- 2:00 PM: 1:1 with Sarah
+- 4:30 PM: Team sync
+
+📧 3 emails need attention:
+- ⚠️ AWS billing alert ($127 over budget)
+- Client replied to your proposal
+- Mom forwarded another recipe
+
+Have a great day! Text me if you need anything."
+```
+
+---
+
+## Research TODOs
+
+- [ ] Track which wow moments have highest conversion to activation
+- [ ] A/B test filesystem scan vs email summary as first wow
+- [ ] Measure time-to-activation across different paths
+- [ ] Identify wow moments for non-Mac users (limited options)
+- [ ] Document wow moments that work without internet (offline-first)
+
+---
+
+*Last updated: 2025-01-08*

package/skills/onboarding/docs/agent-apple-id.md

@@ -0,0 +1,289 @@
+# Agent Apple ID Setup
+
+Give your Nexus agent its own iMessage identity so you can text it directly.
+
+## Why Do This?
+
+Without a dedicated identity:
+- Agent sends messages "from you" (same iMessage account)
+- Messages to yourself look weird
+- No real back-and-forth conversation possible
+
+With a dedicated identity:
+- Agent has its own phone number / email
+- You text the agent like any other contact
+- True async communication
+- **Blue bubble responses from your AI** ✨
+
+This is what makes your agent feel *real*.
+
+---
+
+## Step 1: Get an Email for Your Agent
+
+Your agent needs an email to create an Apple ID. Choose one:
+
+### Option A: Custom Domain (Best)
+
+If you own a domain, create an email for your agent:
+- `echo@yourdomain.com`
+- `agent@yourdomain.com`
+- `nexus@yourdomain.com`
+
+**Why it's best:** You fully control it, it's professional, and you can create more agent emails later.
+
+### Option B: Gmail (Easiest)
+
+1. Go to **[accounts.google.com/signup](https://accounts.google.com/signup)**
+2. Create: `echo-nexus-agent@gmail.com` (or similar)
+3. Use your phone for verification
+4. Save to 1Password:
+
+```bash
+op item create --category login \
+  --title "Gmail - Echo (Agent Email)" \
+  --vault Personal \
+  "username=echo-nexus-agent@gmail.com" \
+  "password=YOUR_PASSWORD"
+```
+
+### Option C: Outlook (Alternative)
+
+1. Go to **[outlook.live.com](https://outlook.live.com/owa/?signup=1)**
+2. Create: `echo-nexus@outlook.com`
+3. Microsoft is less aggressive about bot detection than Google
+4. Save to 1Password
+
+---
+
+## Step 2: Create Apple ID
+
+1. Go to **[appleid.apple.com/account](https://appleid.apple.com/account)**
+
+2. Fill in:
+   | Field | Value |
+   |-------|-------|
+   | **Name** | Echo Nexus (your agent's name) |
+   | **Country** | United States |
+   | **Birthday** | Make it 18+ (e.g., May 15, 1995) |
+   | **Email** | The email from Step 1 |
+   | **Password** | Strong - save to 1Password NOW |
+   | **Phone** | Your phone (for 2FA during setup only) |
+
+3. Complete CAPTCHA, verify via SMS
+
+4. Save to 1Password:
+```bash
+op item create --category login \
+  --title "Apple ID - Echo (Nexus Agent)" \
+  --vault Personal \
+  "username=echo-nexus-agent@gmail.com" \
+  "password=YOUR_PASSWORD" \
+  "url=https://appleid.apple.com"
+```
+
+---
+
+## Step 3: Create iCloud Email
+
+This is the address people will text to reach your agent.
+
+1. Go to **[icloud.com](https://www.icloud.com)**
+2. Sign in with the Apple ID from Step 2
+3. Click **Mail**
+4. You'll be prompted to create an iCloud email
+5. Choose something like: `echo-nexus@icloud.com`
+
+**Save this address** - it's how you'll text your agent!
+
+---
+
+## Step 4: Create macOS User
+
+Your agent needs its own macOS account to have a separate Messages.app.
+
+### Via System Settings (easiest)
+
+1. System Settings → Users & Groups
+2. Click **Add Account...**
+3. Create Standard user:
+   - Name: `Echo` (or your agent's name)
+   - Account name: `nexus-agent`
+   - Password: Generate and save to 1Password
+
+### Via Terminal
+
+```bash
+sudo dscl . -create /Users/nexus-agent
+sudo dscl . -create /Users/nexus-agent UserShell /bin/zsh
+sudo dscl . -create /Users/nexus-agent RealName "Echo"
+sudo dscl . -create /Users/nexus-agent UniqueID 502
+sudo dscl . -create /Users/nexus-agent PrimaryGroupID 20
+sudo dscl . -create /Users/nexus-agent NFSHomeDirectory /Users/nexus-agent
+sudo dscl . -passwd /Users/nexus-agent "PASSWORD"
+sudo createhomedir -c -u nexus-agent
+```
+
+---
+
+## Step 5: Sign Agent into Messages
+
+1. **Switch to agent account:**
+   - Apple menu → Log Out (or use Fast User Switching)
+   - Log in as `nexus-agent`
+
+2. **Open Messages.app**
+
+3. **Sign in** with agent's Apple ID (from Step 2)
+
+4. **Enable iMessage** when prompted
+
+5. **Verify:** Send a test message to yourself
+
+6. **Keep Messages open** (minimize, don't quit)
+
+7. **Switch back** to your account (Apple menu → your name)
+
+---
+
+## Step 6: Enable Fast User Switching
+
+Keep the agent's session alive in the background:
+
+```bash
+sudo defaults write /Library/Preferences/.GlobalPreferences MultipleSessionEnabled -bool true
+defaults write com.apple.controlcenter "NSStatusItem Visible FastUserSwitching" -bool true
+```
+
+---
+
+## Step 7: Set Up SSH for Sending
+
+```bash
+# Enable SSH
+sudo systemsetup -setremotelogin on
+
+# Generate key
+ssh-keygen -t ed25519 -f ~/.ssh/nexus-agent -N ""
+
+# Deploy to agent
+sudo mkdir -p /Users/nexus-agent/.ssh
+sudo cp ~/.ssh/nexus-agent.pub /Users/nexus-agent/.ssh/authorized_keys
+sudo chown -R nexus-agent:staff /Users/nexus-agent/.ssh
+sudo chmod 700 /Users/nexus-agent/.ssh
+sudo chmod 600 /Users/nexus-agent/.ssh/authorized_keys
+
+# Test
+ssh -i ~/.ssh/nexus-agent nexus-agent@localhost "echo '✅ SSH works!'"
+```
+
+---
+
+## Step 8: Test Everything!
+
+```bash
+# Read messages sent to your agent
+EVE_SOURCE_CHAT_DB=/Users/nexus-agent/Library/Messages/chat.db eve messages --limit 3
+
+# Send as your agent (using eve's --as flag)
+eve send --as nexus-agent --to "+1YOURPHONE" --text "Hello! This is Echo 🤖"
+
+# Watch for incoming (text echo-nexus@icloud.com from your phone!)
+EVE_SOURCE_CHAT_DB=/Users/nexus-agent/Library/Messages/chat.db eve watch
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Your Mac                                                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  User: "tyler"                    User: "nexus-agent"      │
+│  ├─ Your Apple ID                 ├─ Agent's Apple ID      │
+│  ├─ Your iMessage                 ├─ Agent's iMessage      │
+│  └─ Cursor + Nexus                └─ Messages.app running  │
+│                                                             │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │  You text: echo-nexus@icloud.com                      │  │
+│  │  Agent receives in its Messages.app                   │  │
+│  │  Nexus detects via: eve watch                         │  │
+│  │  Agent responds via: eve send --as nexus-agent        │  │
+│  │  You receive blue bubble on your phone ✨             │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Usage
+
+```bash
+# Read agent's messages
+EVE_SOURCE_CHAT_DB=/Users/nexus-agent/Library/Messages/chat.db eve messages
+
+# Send as agent
+eve send --as nexus-agent --to "+15551234567" --text "Hello!"
+eve send --as nexus-agent --contact "Tyler" --text "Hey!"
+
+# Watch for incoming
+EVE_SOURCE_CHAT_DB=/Users/nexus-agent/Library/Messages/chat.db eve watch
+```
+
+### Helper Alias
+
+Add to `~/.zshrc`:
+```bash
+alias eve-agent='EVE_SOURCE_CHAT_DB=/Users/nexus-agent/Library/Messages/chat.db eve'
+```
+
+---
+
+## Keeping Mac Awake
+
+For always-on operation:
+
+```bash
+sudo pmset -a sleep 0
+sudo pmset -a disksleep 0
+sudo pmset -a womp 1
+```
+
+---
+
+## Troubleshooting
+
+### Messages not arriving
+- Verify agent's Messages.app is running
+- Check Fast User Switching is enabled
+- Switch to agent account, verify Messages is signed in
+
+### SSH send fails
+- Test: `ssh -i ~/.ssh/nexus-agent nexus-agent@localhost whoami`
+- Check authorized_keys permissions (600)
+- Check .ssh directory permissions (700)
+
+### Agent session logs out
+- Disable "Log out after X minutes" in System Settings
+- Enable "Prevent computer from sleeping"
+
+---
+
+## Summary
+
+| Step | What | Time |
+|------|------|------|
+| 1 | Get agent email (Gmail/Outlook/custom) | 3 min |
+| 2 | Create Apple ID | 5 min |
+| 3 | Create iCloud email | 2 min |
+| 4 | Create macOS user | 2 min |
+| 5 | Sign into Messages | 3 min |
+| 6 | Enable Fast User Switching | 1 min |
+| 7 | Set up SSH | 2 min |
+| 8 | Test | 2 min |
+| **Total** | | **~20 min** |
+
+After this, you can text your AI agent and get blue bubble responses! 📱✨