@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/skill-deep-dives/eve.md

@@ -0,0 +1,711 @@
+# Skill Deep-Dive: eve
+
+**Skill**: `eve`
+**Category**: Communication Data + Agent Reachability
+**Setup Difficulty**: 🟡 Medium (Basic) → 🔴 Very Hard (Full Intelligence + Agent Identity)
+**Time Estimate**: ~5 minutes (basic) | ~15 minutes (intelligence) | ~30 minutes (dual-account)
+**Platform**: macOS only
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| iMessage reading | Read messages from your iMessage database | `eve messages --contact "Mom"` |
+| iMessage sending | Send messages via Messages.app automation | `eve send --to "+1..." --text "Hi!"` |
+| Contact management | List and search contacts by message frequency | `eve contacts --top 10` |
+| Chat searching | Find conversations by content or contact | `eve chats --search "Family"` |
+| Attachment access | View and export photos/videos from messages | `eve attachments --type image` |
+| Message streaming | Watch for new messages in real-time | `eve watch` |
+| Relationship analysis | Analyze conversation patterns, topics, emotions | `eve analyze --contact "Casey"` |
+| Semantic search | Search conversations by meaning, not keywords | `eve search "when did we talk about moving"` |
+| Intelligence insights | Extract topics, entities, emotions, humor | `eve insights topics --chat-id 2` |
+| Agent iMessage identity | Agent can send/receive iMessages via its own Apple ID | Dual-account setup |
+
+---
+
+## Capability Tiers
+
+| Tier | What's Enabled | Additional Requirements |
+|------|----------------|------------------------|
+| **Tier 1: Read-Only** | Read messages, contacts, chats | Full Disk Access for Terminal |
+| **Tier 2: Send** | Send messages, automation | Automation permission for Messages.app |
+| **Tier 3: Intelligence** | AI analysis, semantic search, insights | `GEMINI_API_KEY` environment variable |
+| **Tier 4: Agent Identity** | Agent's own iMessage account for reachability | Dual macOS user setup, separate Apple ID |
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] `macOS` — eve only works on macOS (accesses Messages.app database)
+- [ ] `Messages.app signed in` — Must be signed in with your Apple ID
+- [ ] `Full Disk Access` — Terminal must have Full Disk Access permission
+
+### Soft Dependencies (Recommended)
+- [ ] `GEMINI_API_KEY` — Required for Tier 3 (intelligence features)
+- [ ] `1password` skill — For storing Gemini API key securely
+- [ ] Separate Apple ID — Required for Tier 4 (agent identity)
+- [ ] macOS user account for agent — Required for Tier 4
+
+### This Skill Enables
+- [ ] `comms` — Provides iMessage data to unified communication layer
+- [ ] Agent reachability via iMessage — Users can text the agent's phone number
+- [ ] Morning briefings — Pull recent messages for daily summaries
+- [ ] Relationship insights — Understand communication patterns
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check if on macOS
+uname -s | grep -q Darwin && echo "✅ macOS" || echo "❌ Not macOS (eve requires macOS)"
+
+# Check if Messages.app is signed in
+ls ~/Library/Messages/chat.db && echo "✅ Messages.app database exists" || echo "❌ Messages.app not signed in"
+
+# Check if brew is installed
+which brew || echo "❌ Need to install Homebrew first"
+```
+
+### Installation Steps
+
+```bash
+# Option 1: Install via Homebrew (recommended)
+brew install Napageneral/tap/eve
+
+# Option 2: Install via Go
+go install github.com/Napageneral/eve/cmd/eve@latest
+
+# Verify installation
+eve version
+```
+
+### Verification
+
+```bash
+# Check eve is accessible
+eve version
+
+# Check if databases exist
+eve paths
+```
+
+---
+
+## Configuration
+
+### Tier 1: Read-Only Setup
+
+#### Step 1: Grant Full Disk Access (MANUAL - Cannot be automated)
+
+1. Open **System Settings** → **Privacy & Security** → **Full Disk Access**
+2. Click the lock icon to make changes (enter password)
+3. Click the **+** button
+4. Navigate to **Applications** → **Utilities** → **Terminal** (or iTerm, etc.)
+5. Select Terminal and click **Open**
+6. **Restart Terminal**
+
+#### Step 2: Initialize eve
+
+```bash
+# Create databases
+eve init
+
+# Sync messages from Messages.app
+eve sync
+# This may take a few minutes for large message histories (100k+ messages)
+
+# Verify sync
+eve whoami
+# Should show your name, phone, email
+
+# Test reading messages
+eve contacts --top 5
+eve chats --limit 10
+```
+
+#### Verification
+
+```bash
+# Test basic read operations
+eve contacts --top 5
+eve messages --limit 5
+eve chats --limit 5
+```
+
+---
+
+### Tier 2: Send Capability
+
+#### Grant Automation Permission (MANUAL - Cannot be automated)
+
+1. Open **System Settings** → **Privacy & Security** → **Automation**
+2. Find your terminal app (Terminal, iTerm, etc.)
+3. Enable **Messages** checkbox
+4. Test sending (will prompt first time)
+
+#### Test Sending
+
+```bash
+# ALWAYS confirm recipient before sending!
+eve send --contact "Your Name" --text "Test message from eve"
+
+# Or send to phone number
+eve send --to "+1YOURPHONENUMBER" --text "Test from eve"
+```
+
+**CRITICAL**: Always verify the recipient before sending messages!
+
+---
+
+### Tier 3: Intelligence Features
+
+#### Step 1: Get Gemini API Key
+
+```bash
+# Go to: https://ai.google.dev/gemini-api/docs/api-key
+# Create a free API key (generous free tier)
+
+# Store in 1Password
+op item create \
+  --category "API Credential" \
+  --title "Gemini API Key" \
+  --vault Personal \
+  "credential[password]=YOUR_API_KEY_HERE"
+
+# Or add to your shell profile
+echo 'export GEMINI_API_KEY="op://Personal/Gemini API Key/credential"' >> ~/.zshrc
+echo 'eval "$(op plugin run -- zsh)"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+#### Step 2: Analyze Conversations
+
+```bash
+# Analyze your top relationships
+eve analyze --contact "Mom"
+eve analyze --contact "Best Friend"
+eve analyze --contact "Significant Other"
+
+# Process the analysis queue
+eve compute run
+# This may take a while - it's analyzing your conversations with AI
+
+# Check progress
+eve compute status
+```
+
+#### Step 3: Explore Insights
+
+```bash
+# Get chat ID for a contact
+eve chats --search "Mom"
+# Note the chat_id
+
+# View insights
+eve insights --chat-id <ID>
+eve insights topics --chat-id <ID>
+eve insights entities --chat-id <ID>
+eve insights emotions --chat-id <ID>
+eve insights humor --chat-id <ID>
+```
+
+#### Step 4: Semantic Search
+
+```bash
+# Search by meaning, not keywords
+eve search "when did we talk about moving"
+eve search "restaurant recommendations"
+eve search "plans for next week" --chat-id <ID>
+```
+
+---
+
+### Tier 4: Agent Identity (Dual-Account Setup)
+
+This is the most complex setup - it gives your agent its own iMessage identity.
+
+#### Prerequisites
+
+- [ ] Separate Apple ID for agent (e.g., `echo.nexus@icloud.com`)
+- [ ] Fast User Switching enabled on macOS
+- [ ] SSH (Remote Login) enabled
+
+#### Step 1: Create Agent's Apple ID (MANUAL)
+
+1. Go to [appleid.apple.com/account](https://appleid.apple.com/account)
+2. Create new Apple ID:
+   - Email: `your-agent-name@icloud.com`
+   - Name: Agent's name (e.g., "Echo")
+   - Complete 2FA setup
+3. This becomes the agent's phone number/iMessage address
+
+#### Step 2: Create Agent macOS User (Automated)
+
+```bash
+# Run the setup script
+cd ~/nexus/skills/eve/scripts
+bash setup-dual-account.sh "Echo"
+
+# This creates:
+# - User: nexus-agent
+# - Home: /Users/nexus-agent
+# - Random password (shown once)
+```
+
+#### Step 3: Sign Agent into Messages (MANUAL)
+
+1. **Switch to agent account**:
+   - Menu bar → User icon → `nexus-agent`
+   - Enter the password shown in Step 2
+2. **Open Messages.app**:
+   - Sign in with agent's Apple ID
+   - Enable iMessage
+   - Send a test message to verify it works
+3. **Grant Full Disk Access**:
+   - System Settings → Privacy & Security → Full Disk Access
+   - Add Terminal
+4. **Switch back to your account**:
+   - Menu bar → User icon → Your name
+   - Agent session stays active in background
+
+#### Step 4: Configure Permissions
+
+```bash
+# Make chat databases readable
+sudo chmod 644 ~/Library/Messages/chat.db
+sudo chmod 644 /Users/nexus-agent/Library/Messages/chat.db
+
+# Set up SSH for sending as agent
+ssh-keygen -t ed25519 -f ~/.ssh/nexus-agent -N ""
+
+# Enable SSH (Remote Login)
+sudo systemsetup -setremotelogin on
+
+# Add key to agent's authorized_keys
+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
+ssh -i ~/.ssh/nexus-agent -o BatchMode=yes nexus-agent@localhost "echo 'SSH works!'"
+```
+
+#### Step 5: Using Dual Accounts
+
+```bash
+# Read YOUR messages (default)
+eve messages --contact "Mom"
+
+# Read AGENT's messages
+EVE_SOURCE_CHAT_DB=/Users/nexus-agent/Library/Messages/chat.db eve messages
+
+# Create aliases for convenience
+alias eve-agent='EVE_SOURCE_CHAT_DB=/Users/nexus-agent/Library/Messages/chat.db eve'
+
+# Send as YOU (default)
+eve send --to "+15551234567" --text "Hello from me"
+
+# Send as AGENT
+ssh -i ~/.ssh/nexus-agent nexus-agent@localhost "imsg send --to '+15551234567' --text 'Hello from agent!'"
+
+# Or create helper script
+cat > ~/bin/eve-send-as-agent <<'EOF'
+#!/bin/bash
+ssh -i ~/.ssh/nexus-agent nexus-agent@localhost "imsg send --to '$1' --text '$2'"
+EOF
+chmod +x ~/bin/eve-send-as-agent
+
+# Use it
+eve-send-as-agent "+15551234567" "Hi from agent!"
+```
+
+#### Verification
+
+```bash
+# 1. Verify agent session is active
+ps aux | grep -i Messages
+# Should show 2 Messages.app processes
+
+# 2. Read agent's messages
+eve-agent chats
+
+# 3. Text the agent from your phone
+# Text to: echo@icloud.com (or whatever the agent's Apple ID is)
+
+# 4. Verify it arrived
+eve-agent messages --limit 1
+
+# 5. Send reply as agent
+eve-send-as-agent "+1YOURPHONE" "Echo received your message!"
+
+# 6. Check your phone - should have blue bubble from agent!
+```
+
+---
+
+## User Actions Required
+
+List any manual steps the user MUST perform (can't be automated):
+
+1. **Grant Full Disk Access** (Tier 1): System Settings → Privacy & Security → Full Disk Access → Add Terminal
+2. **Grant Automation Permission** (Tier 2): System Settings → Privacy & Security → Automation → Enable Messages
+3. **Get Gemini API Key** (Tier 3): Visit ai.google.dev and create free API key
+4. **Create Agent Apple ID** (Tier 4): Create new iCloud account at appleid.apple.com
+5. **Sign Agent into Messages** (Tier 4): Switch to agent user, open Messages.app, sign in
+6. **Keep agent session active** (Tier 4): Don't log out of nexus-agent user (use Fast User Switching)
+
+---
+
+## Common Failure Points
+
+### Failure: "Permission denied" reading chat.db
+
+**Symptom**: Error reading `~/Library/Messages/chat.db`
+
+**Cause**: Terminal doesn't have Full Disk Access permission
+
+**Recovery**:
+1. Open System Settings → Privacy & Security → Full Disk Access
+2. Add Terminal to the list
+3. **Restart Terminal** (critical!)
+4. Try again: `eve sync`
+
+**Prevention**: Complete Full Disk Access setup before running eve commands
+
+---
+
+### Failure: "Messages.app automation not authorized"
+
+**Symptom**: `eve send` fails with permission error
+
+**Cause**: Terminal not authorized to control Messages.app
+
+**Recovery**:
+1. System Settings → Privacy & Security → Automation
+2. Find your terminal app
+3. Enable "Messages" checkbox
+4. Try again: `eve send --contact "Your Name" --text "Test"`
+
+**Prevention**: Complete Tier 2 setup before attempting to send
+
+---
+
+### Failure: "GEMINI_API_KEY not set"
+
+**Symptom**: `eve analyze` or `eve search` fails with API key error
+
+**Cause**: Environment variable not set
+
+**Recovery**:
+```bash
+# Check if key is set
+echo $GEMINI_API_KEY
+
+# If empty, set it
+export GEMINI_API_KEY="your-key-here"
+
+# Or load from 1Password
+export GEMINI_API_KEY=$(op read "op://Personal/Gemini API Key/credential")
+
+# Or add to shell profile for persistence
+echo 'export GEMINI_API_KEY="op://Personal/Gemini API Key/credential"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Prevention**: Setup Gemini API key before using Tier 3 features
+
+---
+
+### Failure: Agent's Messages.app not receiving
+
+**Symptom**: Messages sent to agent's Apple ID don't arrive
+
+**Cause**: Agent user session not active, or Messages.app not signed in
+
+**Recovery**:
+```bash
+# Check if agent session is active
+ps aux | grep -c Messages
+# Should show 2 (one for you, one for agent)
+
+# If only 1, switch to agent account:
+# Menu bar → User icon → nexus-agent
+# Open Messages.app, verify it's signed in
+# Switch back to your account
+
+# Verify agent's Messages.app is running
+ps aux | grep Messages
+```
+
+**Prevention**: Use Fast User Switching, never log out of agent account
+
+---
+
+### Failure: SSH connection to agent fails
+
+**Symptom**: `ssh nexus-agent@localhost` times out or refuses connection
+
+**Cause**: Remote Login not enabled
+
+**Recovery**:
+```bash
+# Enable Remote Login
+sudo systemsetup -setremotelogin on
+
+# Verify SSH is running
+sudo launchctl list | grep ssh
+
+# Test connection
+ssh -i ~/.ssh/nexus-agent nexus-agent@localhost "echo 'Works!'"
+```
+
+**Prevention**: Run permission setup script completely
+
+---
+
+### Failure: Sync takes forever
+
+**Symptom**: `eve sync` runs for 10+ minutes
+
+**Cause**: Large message history (100k+ messages), normal for first sync
+
+**Recovery**:
+```bash
+# Check progress
+eve compute status
+
+# Let it finish - it only needs to sync once
+# Subsequent syncs are incremental (fast)
+```
+
+**Prevention**: Warn users with large message histories to expect 5-10 minutes for first sync
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Install eve | ✅ Yes | bash | `brew install Napageneral/tap/eve` |
+| Grant Full Disk Access | ❌ No | - | Requires manual GUI interaction |
+| Grant Automation | ❌ No | - | Requires manual GUI interaction |
+| Initialize databases | ✅ Yes | bash | `eve init` |
+| Sync messages | ✅ Yes | bash | `eve sync` |
+| Get Gemini API key | ❌ No | - | User must create account |
+| Store API key in 1Password | ✅ Yes | bash | `op item create ...` |
+| Analyze conversations | ✅ Yes | bash | `eve analyze` + `eve compute run` |
+| Create agent Apple ID | ❌ No | - | Requires manual account creation |
+| Create agent macOS user | ✅ Yes | bash | `sudo dscl ...` |
+| Sign agent into Messages | ❌ No | - | Requires GUI interaction |
+| Setup SSH | ✅ Yes | bash | `ssh-keygen` + key copy |
+| Configure dual-account | ✅ Yes | bash | Setup script |
+
+### Tier 1+2 Automation Script
+
+```bash
+#!/bin/bash
+# Automates eve basic setup (excludes manual permission grants)
+
+set -e
+
+echo "Installing eve..."
+brew install Napageneral/tap/eve
+
+echo "Verifying Messages.app database..."
+if [ ! -f ~/Library/Messages/chat.db ]; then
+    echo "❌ Messages.app not signed in. Please sign in and try again."
+    exit 1
+fi
+
+echo "⚠️  MANUAL STEP REQUIRED:"
+echo "1. Open System Settings → Privacy & Security → Full Disk Access"
+echo "2. Add Terminal"
+echo "3. Restart Terminal"
+echo ""
+read -p "Press Enter after completing Full Disk Access setup..."
+
+echo "Initializing eve..."
+eve init
+
+echo "Syncing messages (may take a few minutes)..."
+eve sync
+
+echo "✅ Tier 1 (Read-Only) setup complete!"
+echo ""
+echo "Testing..."
+eve whoami
+eve contacts --top 5
+
+echo ""
+echo "⚠️  For Tier 2 (Send), grant Automation permission:"
+echo "System Settings → Privacy & Security → Automation → Enable Messages"
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| Your social graph | Show user's top 10 contacts by message frequency | Right after first sync |
+| Recent unread messages | Show who's messaged them recently | Morning briefing use case |
+| Relationship topics | Show what you talk about with your best friend | After first analysis completes |
+| Semantic search magic | Search "when did we talk about moving" - finds it even if you never said "moving" | After intelligence setup |
+| Agent receives text | User texts agent's phone number, agent responds via iMessage | Dual-account demo |
+| Agent helps you reply | "Tell Mom I'll be there at 7" → agent sends from YOUR phone | AI assistant use case |
+
+### Demo Script
+
+```
+Agent: "Let me show you what eve enables. First, your social graph based on message frequency:"
+
+eve contacts --top 5
+
+Agent: "Here are your most recent conversations:"
+
+eve chats --limit 5
+
+Agent: "And with intelligence features enabled, I can tell you what you and [Name] talk about:"
+
+eve insights topics --chat-id 2
+
+Agent: "Watch this - I can search by meaning, not just keywords. Let me find when you discussed vacation plans:"
+
+eve search "vacation plans"
+
+Agent: "And the really powerful part - I can now help you with your messages. Just tell me 'tell Mom I'll be late' and I'll send it from your account."
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **1password** | Stores Gemini API key | Required for Tier 3 |
+| **comms** | Provides iMessage data | One of three primary sources (eve, gog, wacli) |
+| **qmd** | Messages can be indexed | Semantic search across all messages |
+| **cron** | Schedule periodic sync | Keep message database fresh |
+| **nexus gateway** | Agent reachability | Gateway watches agent's chat.db for incoming messages |
+| **imsg** (replaced by eve) | eve supersedes imsg | Use eve instead of imsg |
+
+---
+
+## Testing Checklist
+
+- [ ] Fresh install: `brew install Napageneral/tap/eve`
+- [ ] Version check: `eve version`
+- [ ] Full Disk Access granted (manual verification)
+- [ ] Init works: `eve init`
+- [ ] Sync works: `eve sync`
+- [ ] Whoami shows user info: `eve whoami`
+- [ ] Can list contacts: `eve contacts --top 5`
+- [ ] Can read messages: `eve messages --limit 5`
+- [ ] Automation permission granted (manual verification)
+- [ ] Can send message: `eve send --to "+1..." --text "Test"`
+- [ ] Gemini API key set
+- [ ] Analysis works: `eve analyze --contact "Name"`
+- [ ] Compute runs: `eve compute run`
+- [ ] Insights show data: `eve insights --chat-id 2`
+- [ ] Semantic search works: `eve search "test query"`
+- [ ] Dual-account: agent user created
+- [ ] Dual-account: agent Messages signed in
+- [ ] Dual-account: SSH works
+- [ ] Dual-account: can read agent messages
+- [ ] Dual-account: can send as agent
+
+---
+
+## Notes for Onboarding Agent
+
+- **Platform-specific**: ALWAYS check user is on macOS first
+- **Tier-based approach**: Start with Tier 1, then offer Tier 2, then Tier 3 if user is interested
+- **Set expectations for Tier 3**: Analysis takes time, warn users it may take 10-30 minutes for first run
+- **Dual-account is advanced**: Only recommend Tier 4 if user explicitly wants agent reachability via iMessage
+- **Privacy concerns**: Some users may be uncomfortable with message analysis - respect that
+- **Gemini API is free**: Emphasize generous free tier for Tier 3
+- **When NOT to recommend**:
+  - User is not on macOS
+  - User doesn't use iMessage
+  - User is uncomfortable with local message database access
+- **Alternative for non-Mac users**: Suggest gog + wacli for communication data instead
+- **Fast User Switching tip**: Explain that agent user stays logged in background, doesn't kick them out
+- **Time estimates**:
+  - Tier 1: 5 minutes + restart Terminal
+  - Tier 2: 2 minutes
+  - Tier 3: 15 minutes (plus compute time)
+  - Tier 4: 30 minutes (includes Apple ID creation, user setup, SSH config)
+
+---
+
+## Architecture: How Eve Works
+
+### Data Flow
+
+```
+Messages.app
+  ↓ (writes to)
+~/Library/Messages/chat.db (Apple's SQLite database)
+  ↓ (read by)
+eve sync (imports into eve's database)
+  ↓ (stores in)
+~/.eve/eve.db (normalized schema + analysis results)
+  ↓ (read by)
+eve commands (chats, messages, insights, etc.)
+```
+
+### Dual-Account Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│  Your Mac                                       │
+├─────────────────────────────────────────────────┤
+│                                                 │
+│  User: tyler                  User: nexus-agent │
+│  ├─ Your Apple ID             ├─ Agent Apple ID │
+│  ├─ Messages.app              ├─ Messages.app   │
+│  └─ chat.db: Your msgs        └─ chat.db: Agent │
+│                                                 │
+│  ┌───────────────────────────────────────────┐ │
+│  │  Nexus Gateway (watches agent's chat.db) │ │
+│  │  └─ Responds to messages sent TO agent   │ │
+│  └───────────────────────────────────────────┘ │
+│                                                 │
+│  ┌───────────────────────────────────────────┐ │
+│  │  Eve (reads/writes BOTH accounts)        │ │
+│  │  └─ Help you: "What did Mom say?"        │ │
+│  │  └─ Help agent: Respond as agent         │ │
+│  └───────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## Security & Privacy
+
+- **Local-first**: All data stays on your Mac, never sent to cloud
+- **Gemini API**: Only used for analysis if you enable Tier 3
+- **What's sent to Gemini**: Conversation excerpts for analysis, embeddings
+- **What's NOT sent**: Your full message database never leaves your machine
+- **Secure storage**: Databases stored in `~/.eve/` with appropriate file permissions
+- **1Password integration**: API keys stored securely, not in plaintext files
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*