@intent-systems/nexus 2026.1.5-3

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

@@ -0,0 +1,399 @@
+# Skill Deep-Dive: wacli
+
+**Skill**: `wacli`
+**Category**: Communication Data + Agent Reachability
+**Setup Difficulty**: 🟡 Medium
+**Time Estimate**: ~5 minutes
+**Platform**: Cross-platform (macOS, Windows, Linux)
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| WhatsApp messaging | Send messages to contacts or groups | `wacli send text --to "+1..." --message "Hi!"` |
+| WhatsApp history sync | Sync WhatsApp messages to local database | `wacli sync --follow` |
+| Chat search | Find chats by name or number | `wacli chats list --query "Mom"` |
+| Message search | Search message content | `wacli messages search "invoice" --after 2025-01-01` |
+| History backfill | Request older messages from phone | `wacli history backfill --chat <jid> --requests 2` |
+| File sending | Send images, PDFs, etc. | `wacli send file --to "+1..." --file photo.jpg` |
+| Agent WhatsApp identity | Agent can send/receive WhatsApp messages | Requires REAL SIM card |
+
+---
+
+## Dual-Purpose Usage
+
+### For User Data Access
+- Read user's WhatsApp history
+- Power unified comms layer (aggregates with eve, gog)
+- Enable agent to understand user's WhatsApp conversations
+
+### For Agent Identity
+- Give agent its own WhatsApp number for reachability
+- Agent can send/receive WhatsApp messages
+- **CRITICAL**: Requires REAL SIM card (Google Voice does NOT work)
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] `brew` or `go` — For installing wacli
+- [ ] WhatsApp account — With phone number
+- [ ] **REAL SIM card** — Google Voice/VoIP numbers do NOT work
+
+### Soft Dependencies (Recommended)
+- [ ] `1password` skill — For backing up session data
+
+### This Skill Enables
+- [ ] `comms` — Provides WhatsApp data to unified communication layer
+- [ ] Agent reachability via WhatsApp — Users can message agent on WhatsApp
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check for brew or go
+which brew && echo "✅ Homebrew available"
+which go && echo "✅ Go available"
+
+# CRITICAL: Verify you have a REAL phone number (not Google Voice)
+echo "⚠️  WhatsApp requires a REAL SIM card"
+echo "Google Voice, Skype numbers, and other VoIP numbers will NOT work"
+```
+
+### Installation Steps
+
+```bash
+# Option 1: Install via Homebrew (recommended)
+brew install steipete/tap/wacli
+
+# Option 2: Install via Go
+go install github.com/steipete/wacli/cmd/wacli@latest
+
+# Verify installation
+wacli version
+```
+
+### Verification
+
+```bash
+# Check wacli is accessible
+wacli version
+```
+
+---
+
+## Configuration
+
+### Step 1: Authenticate with WhatsApp
+
+```bash
+# Start authentication (opens QR code in browser)
+wacli auth
+
+# This will:
+# 1. Generate a QR code in your browser
+# 2. Open WhatsApp on your phone
+# 3. Go to Settings > Linked Devices > Link a Device
+# 4. Scan the QR code
+# 5. Wait for initial sync (may take a few minutes)
+
+# Verify authentication
+wacli doctor
+# Should show: "✅ Connected to WhatsApp"
+```
+
+### Step 2: Initial Sync
+
+```bash
+# Sync WhatsApp history
+# This runs in foreground and syncs messages
+wacli sync
+
+# For continuous syncing (background mode)
+wacli sync --follow &
+
+# Check sync status
+wacli doctor
+```
+
+### Step 3: Verify Data
+
+```bash
+# List recent chats
+wacli chats list --limit 10
+
+# Search for a specific chat
+wacli chats list --query "Mom"
+
+# View messages from a chat
+wacli messages search "hello" --limit 5
+```
+
+### Step 4: Optional - Backup Session to 1Password
+
+```bash
+# Export session data
+tar -czf /tmp/wacli-session.tar.gz ~/.wacli/
+
+# Store in 1Password
+op document create /tmp/wacli-session.tar.gz \
+  --title "wacli-session" \
+  --vault Personal
+
+# Clean up
+rm /tmp/wacli-session.tar.gz
+```
+
+---
+
+## User Actions Required
+
+1. **Scan QR code**: Open WhatsApp on phone, go to Settings > Linked Devices > Scan QR code (displayed by `wacli auth`)
+2. **Keep phone online during backfill**: History backfill requires phone to be online and connected
+
+---
+
+## Common Failure Points
+
+### Failure: "Google Voice number not supported"
+
+**Symptom**: QR code scans successfully but WhatsApp rejects with "This number is not supported"
+
+**Cause**: WhatsApp does not allow VoIP numbers (Google Voice, Skype, etc.)
+
+**Recovery**:
+```bash
+# You MUST use a real SIM card
+# Options:
+# 1. Use your personal phone number
+# 2. Get a prepaid SIM card
+# 3. Use a different phone number service (real carrier)
+
+# No workaround exists - this is a WhatsApp limitation
+```
+
+**Prevention**: Verify phone number is from a real mobile carrier before starting
+
+---
+
+### Failure: QR code expired
+
+**Symptom**: "QR code expired" error when trying to scan
+
+**Cause**: Took too long to scan (QR codes expire after ~20 seconds)
+
+**Recovery**:
+```bash
+# Re-run auth to generate new QR code
+wacli auth
+
+# Scan quickly this time (within 20 seconds)
+```
+
+**Prevention**: Have phone ready with WhatsApp open before running `wacli auth`
+
+---
+
+### Failure: Connection lost
+
+**Symptom**: `wacli doctor` shows "Not connected" after previously working
+
+**Cause**: WhatsApp session expired or was logged out
+
+**Recovery**:
+```bash
+# Re-authenticate
+wacli auth
+
+# If that fails, remove old session and re-auth
+rm -rf ~/.wacli/
+wacli auth
+```
+
+**Prevention**: Don't log out of WhatsApp web sessions, keep wacli session active
+
+---
+
+### Failure: History backfill not working
+
+**Symptom**: `wacli history backfill` returns no results or times out
+
+**Cause**: Phone not online, or WhatsApp app not running on phone
+
+**Recovery**:
+```bash
+# Ensure phone is:
+# 1. Online (connected to WiFi/cellular)
+# 2. WhatsApp app is open (or background app refresh enabled)
+# 3. Not in low power mode
+
+# Try backfill again with smaller request
+wacli history backfill --chat <jid> --requests 1 --count 20
+```
+
+**Prevention**: Keep phone online and WhatsApp running during backfill
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Install wacli | ✅ Yes | bash | `brew install steipete/tap/wacli` |
+| Authenticate | ❌ No | - | Requires scanning QR code with phone |
+| Sync messages | ✅ Yes | bash | `wacli sync` |
+| Send messages | ✅ Yes | bash | `wacli send text ...` |
+| Search history | ✅ Yes | bash | `wacli messages search ...` |
+| Schedule periodic sync | ✅ Yes | cron | `wacli sync` hourly |
+| Backup session | ✅ Yes | bash | tar + 1Password |
+
+### Automation Script (Post-Auth)
+
+```bash
+#!/bin/bash
+# Automate wacli operations (after initial auth)
+
+set -e
+
+# Verify authenticated
+wacli doctor || { echo "❌ Not authenticated. Run: wacli auth"; exit 1; }
+
+# Sync messages
+echo "Syncing WhatsApp messages..."
+wacli sync
+
+# List recent chats
+echo "Recent chats:"
+wacli chats list --limit 10
+
+# Backup session to 1Password
+echo "Backing up session..."
+tar -czf /tmp/wacli-session.tar.gz ~/.wacli/
+op document create /tmp/wacli-session.tar.gz --title "wacli-session-$(date +%Y%m%d)" --vault Personal
+rm /tmp/wacli-session.tar.gz
+
+echo "✅ wacli automation complete!"
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| Send WhatsApp message | Agent sends WhatsApp message on user's behalf | When user asks to message someone |
+| Search WhatsApp history | Find old messages by content | When user asks "what did X say about Y" |
+| Agent receives WhatsApp | User texts agent's WhatsApp number, agent responds | Agent reachability demo |
+| Cross-platform WhatsApp | Use WhatsApp on desktop via CLI | Show CLI power |
+
+### Demo Script
+
+```
+Agent: "Let me show you what wacli enables. First, I can search your WhatsApp history:"
+
+wacli messages search "dinner plans" --limit 5
+
+Agent: "I can also send WhatsApp messages. Who would you like me to message?"
+
+[User: "Message Mom"]
+
+Agent: "What should I say to Mom?"
+
+[User: "Tell her I'll be home at 7"]
+
+wacli send text --to "+1MOMSNUM" --message "I'll be home at 7"
+
+Agent: "✅ Sent! And with the agent WhatsApp identity setup, people can text me directly on WhatsApp."
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **1password** | Backup WhatsApp session | Prevents losing connection |
+| **comms** | Provides WhatsApp data | One of three primary sources |
+| **cron** | Schedule periodic sync | Keep message database fresh |
+| **qmd** | Messages can be indexed | Semantic search across WhatsApp |
+
+---
+
+## Testing Checklist
+
+- [ ] Fresh install: `brew install steipete/tap/wacli`
+- [ ] Version check: `wacli version`
+- [ ] Auth works: `wacli auth` + QR scan
+- [ ] Doctor shows connected: `wacli doctor`
+- [ ] Sync works: `wacli sync`
+- [ ] Chats list works: `wacli chats list --limit 10`
+- [ ] Search works: `wacli messages search "test"`
+- [ ] Send text works: `wacli send text --to "+1..." --message "Test"`
+- [ ] Send file works: `wacli send file --to "+1..." --file test.jpg`
+- [ ] History backfill works: `wacli history backfill --chat <jid> --requests 1`
+- [ ] Session backup works: tar + 1Password upload
+
+---
+
+## Notes for Onboarding Agent
+
+- **CRITICAL: Real SIM requirement**: ALWAYS warn users that Google Voice does NOT work
+- **QR code scanning**: Guide users through the scan process step-by-step
+- **Session persistence**: Emphasize backing up session to 1Password
+- **When NOT to recommend**:
+  - User doesn't use WhatsApp
+  - User only has Google Voice or VoIP number (won't work)
+  - User uncomfortable with WhatsApp Web security model
+- **Value proposition**: "Access WhatsApp from desktop/CLI + agent reachability"
+- **Time estimate**: 5 minutes (plus initial sync time)
+- **Agent identity use case**: Requires separate phone number with real SIM
+
+---
+
+## WhatsApp JID Format
+
+WhatsApp uses JIDs (Jabber IDs) to identify chats:
+
+- **Direct chats**: `<phonenumber>@s.whatsapp.net` (e.g., `14155551212@s.whatsapp.net`)
+- **Group chats**: `<groupid>@g.us` (e.g., `1234567890-123456789@g.us`)
+
+Find JIDs using:
+```bash
+wacli chats list --query "Name"
+# Look for the "jid" field in output
+```
+
+---
+
+## Storage Location
+
+- **Session data**: `~/.wacli/` (override with `--store` flag)
+- **Database**: `~/.wacli/wacli.db` (SQLite)
+- **Credentials**: `~/.wacli/session.json` (encrypted)
+
+---
+
+## Security Considerations
+
+- **Session file contains auth**: Treat `~/.wacli/` as sensitive (back up to 1Password)
+- **WhatsApp Web model**: wacli uses same security model as WhatsApp Web
+- **Multi-device**: Each wacli session counts as a linked device (WhatsApp allows 4)
+- **Logout remotely**: Can disconnect from WhatsApp app → Settings → Linked Devices
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*