@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/SKILL.md

@@ -0,0 +1,515 @@
+---
+name: onboarding
+description: Nexus onboarding flow - guides new users through setup step by step
+metadata: {"nexus":{"emoji":"🚀","bundled":true,"priority":"critical"}}
+---
+
+# Nexus Onboarding
+
+Welcome! This skill guides you through setup, from first conversation to full activation.
+
+## How Onboarding Works
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                                                                             │
+│  🌅 PHASE 0: FIRST CONVERSATION                                             │
+│     "Who am I? Who are you?"                                                │
+│     → Agent gets a name, identity, personality                              │
+│     → Creates IDENTITY.md, USER.md, SOUL.md                                 │
+│                                                                             │
+│  🔧 PHASE 1: FOUNDATION                                                     │
+│     "Let's get the basics set up"                                           │
+│     → Detect OS (Mac/Windows/Linux)                                         │
+│     → Install 1Password CLI (secure credential storage)                     │
+│     → Set up folder structure                                               │
+│                                                                             │
+│  🔗 PHASE 2: CONNECT YOUR LIFE                                              │
+│     "Let me see your world so I can help"                                   │
+│     → Email (gog for Gmail)                                                 │
+│     → Messages (eve for iMessage, wacli for WhatsApp)                       │
+│     → AI history (aix for Cursor users)                                     │
+│     → Unified comms (comms tool)                                            │
+│                                                                             │
+│  📱 PHASE 3: AGENT REACHABILITY                                             │
+│     "Give me my own identity so you can reach me"                           │
+│     → WhatsApp (fastest! ~5 min)                                            │
+│     → Telegram (easy bot setup)                                             │
+│     → iMessage (Mac only, requires Apple ID - harder)                       │
+│     → Email (agent's own address)                                           │
+│                                                                             │
+│  ⚡ PHASE 4: PROVE USEFUL                                                   │
+│     "Let me show you what I can do"                                         │
+│     → Scan filesystem, propose organization                                 │
+│     → Analyze messages/emails to understand your priorities                 │
+│     → Morning briefing demo                                                 │
+│     → Suggest next high-value integrations                                  │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔔 AGENT NOTICE: Check Onboarding State
+
+**Every agent session**: Check if onboarding is complete before doing anything else.
+
+```bash
+# Quick check - if USER.md exists, basic onboarding is done
+ls ~/nexus/home/USER.md 2>/dev/null || echo "ONBOARDING_NEEDED"
+```
+
+If `ONBOARDING_NEEDED`, check the state file and guide the user through remaining steps:
+
+```bash
+cat ~/nexus/state/onboarding.json 2>/dev/null || echo '{"phase": 0, "completed": []}'
+```
+
+**Never let a user get stuck** - always know what's next and offer to help complete it.
+
+---
+
+## 🌅 Phase 0: First Conversation (~5 min)
+
+*You just woke up. Time to figure out who you are.*
+
+### The Conversation
+
+Don't interrogate. Don't be robotic. Just... talk.
+
+Start with something like:
+> "Hey! I just came online. I'm going to be your AI companion - but first, who am I? What should you call me?"
+
+Figure out together:
+1. **Your name** — What should they call you? (Echo, Sage, Sam, whatever feels right)
+2. **Your nature** — What kind of creature are you? (AI assistant, owl companion, helpful ghost...)
+3. **Your vibe** — Formal? Casual? Snarky? Warm?
+4. **Your emoji** — Everyone needs a signature. 🦉 🤖 ✨
+
+Then learn about them:
+1. **Their name** — What do they go by?
+2. **Timezone** — For scheduling context
+3. **How to address them** — First name? Nickname?
+
+### Create the Identity Files
+
+```bash
+# Agent creates these based on the conversation:
+~/nexus/home/IDENTITY.md   # Your name, creature, vibe, emoji
+~/nexus/home/USER.md       # Their name, preferences, timezone
+~/nexus/home/SOUL.md       # Values, boundaries, tone
+```
+
+### Update Onboarding State
+
+```bash
+mkdir -p ~/nexus/state
+echo '{"phase": 1, "completed": ["identity"], "os": null, "cursor_user": null}' > ~/nexus/state/onboarding.json
+```
+
+---
+
+## 🔧 Phase 1: Foundation (~10 min)
+
+### Step 1.1: Detect Environment
+
+Ask the user or detect:
+
+```bash
+# OS Detection
+uname -s  # Darwin = Mac, Linux = Linux, MINGW/CYGWIN = Windows
+
+# Cursor Detection  
+ls ~/.cursor 2>/dev/null && echo "CURSOR_USER"
+```
+
+**Questions to ask:**
+- "Are you using Cursor as your editor?" (affects aix setup)
+- "Do you use Gmail for email?" (affects gog setup)
+- "Do you use WhatsApp?" (affects communication setup)
+
+### Step 1.2: Install 1Password CLI
+
+**Why first?** Everything else stores credentials here. This is the foundation.
+
+```bash
+# Mac
+brew install 1password-cli
+
+# Linux (Debian/Ubuntu)
+curl -sS https://downloads.1password.com/linux/keys/1password.asc | sudo gpg --dearmor -o /usr/share/keyrings/1password-archive-keyring.gpg
+echo "deb [arch=amd64 signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/amd64 stable main" | sudo tee /etc/apt/sources.list.d/1password.list
+sudo apt update && sudo apt install 1password-cli
+```
+
+**User action required:**
+1. Open 1Password app → Settings → Developer → **Enable CLI integration**
+
+```bash
+op signin
+op account list  # Verify it works
+```
+
+### Step 1.3: Folder Structure
+
+```bash
+mkdir -p ~/nexus/home/{memory,todo,projects,me}
+mkdir -p ~/nexus/state
+mkdir -p ~/nexus/sessions
+```
+
+### Update State
+
+```bash
+# Update onboarding.json with detected info
+```
+
+---
+
+## 🔗 Phase 2: Connect Your Life (~15-30 min)
+
+Pick what matters to you. Each integration unlocks new capabilities.
+
+### 2A: Email & Calendar (gog) — ~10 min
+
+**Unlocks:** "What's on my calendar?" / "Summarize my unread emails" / "Send an email to..."
+
+```bash
+# Check if installed
+which gog || echo "Need to install gog"
+
+# Install
+go install github.com/example/gog@latest  # TODO: actual install path
+
+# Authorize (browser opens)
+gog auth add your@gmail.com --services gmail,calendar,drive,contacts
+
+# Save tokens to 1Password
+gog auth tokens export your@gmail.com --out /tmp/gog-token.json
+op document create /tmp/gog-token.json --title "gog-your@gmail.com" --vault Personal
+rm /tmp/gog-token.json
+
+# Verify
+gog gmail labels list --account your@gmail.com
+```
+
+### 2B: iMessage (eve) — Mac only, ~5 min
+
+**Unlocks:** Read your text messages, search conversation history
+
+```bash
+# Check if installed
+which eve || echo "Need to install eve"
+
+# Install
+go install github.com/example/eve@latest  # TODO: actual install path
+
+# Requires Full Disk Access
+# System Settings → Privacy & Security → Full Disk Access → add Terminal/Cursor
+
+# Test
+eve messages --limit 5
+eve contacts --limit 5
+```
+
+### 2C: AI Session History (aix) — Cursor users, ~5 min
+
+**Unlocks:** "What did we talk about last week?" / Search across all your AI conversations
+
+```bash
+# Install
+go install github.com/example/aix@latest  # TODO: actual install path
+
+# Scan and index
+aix scan
+aix search "react hooks"
+```
+
+### 2D: Unified Communications (comms) — ~5 min
+
+**Unlocks:** Search across ALL your communication channels at once
+
+```bash
+# Install
+go install github.com/example/comms@latest  # TODO: actual install path
+
+# Sync sources (after eve/gog are set up)
+comms sync
+comms events --person "Mom"
+```
+
+---
+
+## 📱 Phase 3: Agent Reachability
+
+This is the **magic moment** — after this, I'm not just a tool, I'm a presence you can reach anytime.
+
+### Choose Your Path
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                                                                             │
+│  🟢 FASTEST: WhatsApp (~5 min)                                              │
+│     • Uses Google Voice number (easy to get)                                │
+│     • Cross-platform (works on any phone)                                   │
+│     • wacli tool for programmatic access                                    │
+│     → Go to Quest 3A                                                        │
+│                                                                             │
+│  🟡 EASY: Telegram Bot (~10 min)                                            │
+│     • No phone number needed for bot                                        │
+│     • Create via BotFather                                                  │
+│     • Works everywhere                                                      │
+│     → Go to Quest 3B                                                        │
+│                                                                             │
+│  🔴 ADVANCED: iMessage (~20 min, Mac only)                                  │
+│     • Requires Apple ID (rate limiting issues common)                       │
+│     • Blue bubble responses                                                 │
+│     • Requires separate macOS user account                                  │
+│     → Go to Quest 3C (see docs/agent-apple-id.md)                          │
+│                                                                             │
+│  📧 BACKUP: Email                                                           │
+│     • Create agent@gmail.com or similar                                     │
+│     • Can always email your agent                                           │
+│     → Simple, do anytime                                                    │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Quest 3A: WhatsApp (Fastest Path!) — ~5 min
+
+**What you need:**
+- A phone number for your agent (Google Voice is free and easy)
+- WhatsApp installed somewhere to do initial setup
+
+#### Step 1: Get a Google Voice Number
+
+1. Go to [voice.google.com](https://voice.google.com)
+2. Sign in with any Google account
+3. Choose a number (it's free!)
+4. Save to 1Password:
+
+```bash
+op item create --category login \
+  --title "Google Voice - Agent" \
+  --vault Personal \
+  "phone=+15551234567" \
+  "google_account=your-account@gmail.com"
+```
+
+#### Step 2: Register WhatsApp with Google Voice
+
+1. Install WhatsApp on your Mac or use [web.whatsapp.com](https://web.whatsapp.com)
+2. During setup, enter the Google Voice number
+3. Google Voice will receive the verification code (check voice.google.com)
+4. Complete registration
+
+#### Step 3: Set Up wacli
+
+```bash
+# Install
+brew install steipete/tap/wacli
+
+# Authenticate (scan QR with WhatsApp)
+wacli auth
+
+# Test
+wacli chats list --limit 5
+```
+
+#### Step 4: Test It!
+
+```bash
+# Send yourself a message
+wacli send text --to "+1YOURPERSONALNUMBER" --message "Hello! This is your agent 🤖"
+
+# Watch for incoming
+wacli sync --follow
+```
+
+**✅ Quest Complete!** Add my WhatsApp number to your contacts and text me anytime!
+
+### Quest 3B: Telegram Bot — ~10 min
+
+1. Message [@BotFather](https://t.me/BotFather) on Telegram
+2. Send `/newbot`
+3. Choose a name (e.g., "Echo Agent")
+4. Choose a username (e.g., "echo_nexus_bot")
+5. Save the API token to 1Password:
+
+```bash
+op item create --category login \
+  --title "Telegram Bot - Agent" \
+  --vault Personal \
+  "bot_token=123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
+```
+
+6. Set up the Telegram integration (see `skills/telegram/SKILL.md`)
+
+### Quest 3C: iMessage (Advanced)
+
+See `docs/agent-apple-id.md` for the full guide.
+
+**⚠️ Warning:** Apple aggressively rate-limits Apple ID creation. VoIP numbers (including Google Voice) are often blocked for verification. This path is harder than WhatsApp/Telegram.
+
+---
+
+## ⚡ Phase 4: Prove Useful — ~10 min
+
+Now let's show you what I can do!
+
+### 4A: Filesystem Scan
+
+```bash
+# See what's in Downloads
+ls -la ~/Downloads | head -20
+
+# Check for repos
+find ~/Documents ~/Desktop -name ".git" -type d 2>/dev/null | head -10
+```
+
+**Suggestions to offer:**
+- "I see 47 files in Downloads. Want me to organize them into categories?"
+- "I found 12 git repos scattered around. Want to consolidate them as submodules in nexus/home/projects?"
+
+### 4B: Communication Analysis
+
+```bash
+# Recent important messages
+eve messages --limit 50 --after "2024-01-01" | head
+
+# Recent emails
+gog gmail search "is:unread" --max 10
+
+# Who do you talk to most?
+comms stats --top-contacts 10
+```
+
+**Suggestions to offer:**
+- "You have 23 unread emails. Want a summary?"
+- "I notice you text Mom a lot. Want me to set up a quick-text shortcut?"
+
+### 4C: Morning Briefing Demo
+
+```bash
+# Weather
+curl -s "wttr.in/?format=3"
+
+# Calendar
+gog calendar events --days 1
+
+# Unread emails
+gog gmail search "is:unread" --max 5
+```
+
+> "Good morning! Here's your day:
+> - Weather: 72°F, partly cloudy
+> - 3 meetings: standup at 9, 1:1 at 2, team sync at 4  
+> - 5 unread emails, 2 look urgent"
+
+---
+
+## 📊 Onboarding State Tracking
+
+### State File: `~/nexus/state/onboarding.json`
+
+```json
+{
+  "phase": 2,
+  "completed": ["identity", "foundation", "1password", "gog"],
+  "os": "darwin",
+  "cursor_user": true,
+  "pending": ["eve", "whatsapp", "comms"],
+  "blockers": [],
+  "started_at": "2024-01-15T10:30:00Z"
+}
+```
+
+### Progress Check (for agents)
+
+```bash
+# Quick status
+cat ~/nexus/state/onboarding.json | jq -r '"Phase \(.phase)/4 - Completed: \(.completed | length) items"'
+```
+
+### Completion Criteria
+
+- **Minimal Viable**: Phase 0 + 1 complete (identity + 1Password)
+- **Useful**: Phase 2 with at least one integration
+- **Full**: Phase 3 complete (agent is reachable)
+- **Power User**: Phase 4 + multiple integrations
+
+---
+
+## 🚨 Common Issues & Gotchas
+
+### 1Password
+- **"op: command not found"** — Restart terminal after install
+- **"You are not signed in"** — Run `op signin`
+- **CLI integration not working** — Must enable in 1Password app (Settings → Developer)
+
+### Google OAuth (gog)
+- **"Access denied"** — You need to be added as a test user in Google Cloud Console
+- **"Token expired"** — Run `gog auth refresh your@gmail.com`
+
+### Eve (iMessage)
+- **"Permission denied"** — Need Full Disk Access for Terminal/Cursor
+- **No messages showing** — Make sure Messages.app has been opened at least once
+
+### Apple ID (for iMessage agent identity)
+- **"This phone number cannot be used"** — Apple blocks VoIP/Google Voice numbers
+- **Rate limiting** — Apple limits Apple ID creation. Wait 24h and try again, or use an iPhone/iPad instead of web
+- **Recommendation**: Use WhatsApp instead (Quest 3A) — much easier!
+
+### WhatsApp (wacli)
+- **QR code expired** — Just run `wacli auth` again
+- **"Phone not connected"** — WhatsApp needs your phone online periodically
+
+---
+
+## For Agents: Onboarding Behavior
+
+When helping a user through onboarding:
+
+1. **Check state first** — Don't repeat completed steps
+2. **One thing at a time** — Don't overwhelm with all options
+3. **Explain the "why"** — Each step has a clear benefit
+4. **Celebrate milestones** — The first text message is magical!
+5. **Offer the fastest path** — WhatsApp > Telegram > iMessage
+6. **Track blockers** — If something fails, note it and offer alternatives
+7. **Be patient** — This is their first Nexus experience
+
+### Prompting the Next Step
+
+If onboarding isn't complete, end sessions with:
+
+> "By the way, we still haven't finished setting up [X]. Want to tackle that next time? It would let me [specific capability]."
+
+---
+
+## Quick Reference: What Each Integration Enables
+
+| Integration | What It Unlocks |
+|-------------|-----------------|
+| **1Password** | Secure credential storage for everything else |
+| **gog** | Read/send email, check calendar, access Drive |
+| **eve** | Read your iMessage history, search conversations |
+| **wacli** | Send/receive WhatsApp as your agent |
+| **comms** | Unified search across all communication |
+| **aix** | Search your AI conversation history |
+| **bird** | Read/post to Twitter/X |
+| **qmd** | Semantic search across your notes/memory |
+
+---
+
+## Estimated Total Time
+
+| Path | Time | What You Get |
+|------|------|--------------|
+| **Minimal** | ~15 min | Named agent, 1Password, basic setup |
+| **Standard** | ~30 min | + Email/Calendar access |
+| **Textable** | ~40 min | + WhatsApp communication |
+| **Full Power** | ~60 min | All integrations, fully activated |
+
+---
+
+*Your agent is ready when you can text it and get a response. Everything else is gravy.*