@intent-systems/nexus 2026.1.5-3

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

@@ -0,0 +1,607 @@
+# Skill Deep-Dive: comms
+
+**Skill**: `comms`
+**Category**: Communication Data (Aggregator)
+**Setup Difficulty**: 🟡 Medium
+**Time Estimate**: ~10 minutes (after prerequisites)
+**Platform**: macOS, Linux
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| Unified communication view | See all communications across channels in one place | `comms events --person "Dad"` |
+| Cross-channel search | Find conversations regardless of medium | Search Dad's messages in iMessage + Gmail |
+| Identity resolution | Merge identities across channels (phone + email = same person) | Auto-links "+1..." and "dad@gmail.com" |
+| Communication analytics | See who you talk to most, when, and where | `comms people --top 20` |
+| Timeline view | See all activity for a time period across channels | `comms timeline --today` |
+| Tagging & organization | Tag events by project, context, etc. | `comms tag add --event <id> --tag "project:htaa"` |
+| Programmable access | Query via SQL for custom insights | `comms db query <sql>` |
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] At least one communication source — eve OR gog (minimum)
+- [ ] `brew` or `go` — For installing comms
+
+### Soft Dependencies (Recommended)
+- [ ] `eve` skill — For iMessage data
+- [ ] `gog` skill — For Gmail data
+- [ ] `wacli` skill — For WhatsApp data
+- [ ] `aix` skill — For AI session data
+- [ ] `bird` skill — For X/Twitter data
+
+### This Skill Enables
+- [ ] Unified communication intelligence — Single query across all channels
+- [ ] Relationship insights — Understand communication patterns holistically
+- [ ] Agent context — Give agents full communication history
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check if communication sources are available
+which eve && echo "✅ eve (iMessage) available"
+which gog && echo "✅ gog (Gmail) available"
+which wacli && echo "✅ wacli (WhatsApp) available"
+which aix && echo "✅ aix (AI sessions) available"
+which bird && echo "✅ bird (Twitter) available"
+
+# At minimum, need one source
+# Recommended: Setup eve OR gog first
+
+# Check for brew or go
+which brew && echo "✅ Homebrew available"
+which go && echo "✅ Go available"
+```
+
+### Installation Steps
+
+```bash
+# Option 1: Install via Homebrew (recommended)
+brew install Napageneral/tap/comms
+
+# Option 2: Install via Go
+go install github.com/Napageneral/comms/cmd/comms@latest
+
+# Verify installation
+comms version
+```
+
+### Verification
+
+```bash
+# Check comms is accessible
+comms version
+```
+
+---
+
+## Configuration
+
+### Step 1: Initialize comms
+
+```bash
+# Create config and database
+comms init
+
+# This creates:
+# - ~/.config/comms/config.yaml (configuration)
+# - ~/Library/Application Support/Comms/comms.db (event store)
+```
+
+### Step 2: Configure Your Identity
+
+```bash
+# Set your canonical identity
+comms me set \
+  --name "Your Full Name" \
+  --phone "+1YOURNUMBER" \
+  --email "you@example.com"
+
+# Verify
+comms me
+```
+
+### Step 3: Connect Adapters
+
+Connect each communication source you have:
+
+#### iMessage (via eve)
+```bash
+# Prerequisites: eve installed and synced
+eve whoami  # Verify eve is working
+
+# Connect
+comms connect imessage
+
+# Verify
+comms adapters
+```
+
+#### Gmail (via gogcli)
+```bash
+# Prerequisites: gog installed and authenticated
+gog gmail labels list --account you@gmail.com  # Verify gog works
+
+# Connect
+comms connect gmail --account you@gmail.com
+
+# For multiple accounts
+comms connect gmail --account work@company.com
+
+# Verify
+comms adapters
+```
+
+#### WhatsApp (via wacli)
+```bash
+# Prerequisites: wacli authenticated
+wacli doctor  # Verify wacli works
+
+# Connect
+comms connect whatsapp
+
+# Verify
+comms adapters
+```
+
+#### AI Sessions (via aix)
+```bash
+# Prerequisites: aix installed and synced
+aix stats  # Verify aix works
+
+# Connect
+comms connect cursor
+
+# Verify
+comms adapters
+```
+
+#### X/Twitter (via bird)
+```bash
+# Prerequisites: bird authenticated
+bird whoami  # Verify bird works
+
+# Connect
+comms connect x
+
+# Verify
+comms adapters
+```
+
+### Step 4: Initial Sync
+
+```bash
+# Sync all connected adapters
+comms sync
+
+# This may take a few minutes depending on history size
+# Watch progress with:
+comms db query "SELECT COUNT(*) as event_count FROM events"
+```
+
+### Step 5: Verify Data
+
+```bash
+# Check event count
+comms db query "SELECT COUNT(*) as events FROM events"
+
+# See your top contacts
+comms people --top 10
+
+# View recent events
+comms events --limit 20
+
+# Check channel breakdown
+comms db query "SELECT channel, COUNT(*) as count FROM events GROUP BY channel"
+```
+
+---
+
+## User Actions Required
+
+No manual system permissions required! All automation happens through the underlying skills (eve, gog, etc.).
+
+---
+
+## Common Failure Points
+
+### Failure: "No adapters found"
+
+**Symptom**: `comms sync` returns "No adapters configured"
+
+**Cause**: Haven't connected any communication sources
+
+**Recovery**:
+```bash
+# Check which sources are available
+which eve gog wacli aix bird
+
+# Connect at least one
+comms connect imessage  # If eve is installed
+# OR
+comms connect gmail --account you@gmail.com  # If gog is installed
+
+# Verify
+comms adapters
+```
+
+**Prevention**: Setup eve or gog before comms
+
+---
+
+### Failure: Sync fails for specific adapter
+
+**Symptom**: `comms sync` errors on specific channel (e.g., "gmail: authentication failed")
+
+**Cause**: Underlying tool not working (gog not authenticated, eve not synced, etc.)
+
+**Recovery**:
+```bash
+# Test the underlying tool directly
+# For Gmail:
+gog gmail labels list --account you@gmail.com
+
+# For iMessage:
+eve whoami
+
+# For WhatsApp:
+wacli doctor
+
+# Fix the underlying tool first, then retry
+comms sync --adapter <adapter-name>
+```
+
+**Prevention**: Verify each skill works independently before connecting to comms
+
+---
+
+### Failure: Identity resolution not working
+
+**Symptom**: Same person appears as multiple entries in `comms people`
+
+**Cause**: Identities not linked (e.g., phone number and email treated as separate people)
+
+**Recovery**:
+```bash
+# List all people
+comms people
+
+# Merge two entries
+comms identify --merge "Dad (phone)" "Dad (email)"
+
+# Or add identity to existing person
+comms identify --add "Dad" --email "dad@example.com"
+```
+
+**Prevention**: Configure identity resolution rules in config.yaml
+
+---
+
+### Failure: Slow sync
+
+**Symptom**: Initial sync takes 10+ minutes
+
+**Cause**: Large communication history (normal for first sync)
+
+**Recovery**:
+```bash
+# Check progress
+comms db query "SELECT channel, COUNT(*) FROM events GROUP BY channel"
+
+# Let it finish - subsequent syncs are incremental (fast)
+```
+
+**Prevention**: Warn users with large histories to expect 5-15 minutes for first sync
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Install comms | ✅ Yes | bash | `brew install Napageneral/tap/comms` |
+| Initialize | ✅ Yes | bash | `comms init` |
+| Configure identity | ✅ Yes | bash | `comms me set ...` |
+| Connect adapters | ✅ Yes | bash | `comms connect ...` |
+| Sync | ✅ Yes | bash | `comms sync` |
+| Schedule periodic sync | ✅ Yes | cron | `comms sync` hourly |
+| Query events | ✅ Yes | bash | `comms events` or `comms db query` |
+
+### Full Automation Script
+
+```bash
+#!/bin/bash
+# Complete comms setup automation
+
+set -e
+
+echo "Installing comms..."
+brew install Napageneral/tap/comms
+
+echo "Initializing comms..."
+comms init
+
+echo "Configuring identity..."
+# Get from user or environment
+NAME="${USER_FULL_NAME:-$(whoami)}"
+PHONE="${USER_PHONE:-}"
+EMAIL="${USER_EMAIL:-}"
+
+comms me set --name "$NAME" --phone "$PHONE" --email "$EMAIL"
+
+echo "Connecting adapters..."
+# Connect available sources
+if which eve >/dev/null; then
+    comms connect imessage
+    echo "✅ Connected iMessage"
+fi
+
+if which gog >/dev/null; then
+    # Detect gog accounts
+    for account in $(gog auth list --plain | cut -f1); do
+        comms connect gmail --account "$account"
+        echo "✅ Connected Gmail: $account"
+    done
+fi
+
+if which wacli >/dev/null; then
+    comms connect whatsapp
+    echo "✅ Connected WhatsApp"
+fi
+
+if which aix >/dev/null; then
+    comms connect cursor
+    echo "✅ Connected AI sessions"
+fi
+
+if which bird >/dev/null; then
+    comms connect x
+    echo "✅ Connected X/Twitter"
+fi
+
+echo "Syncing all adapters..."
+comms sync
+
+echo "✅ comms setup complete!"
+echo ""
+echo "Statistics:"
+comms db query "SELECT channel, COUNT(*) as events FROM events GROUP BY channel"
+echo ""
+echo "Top contacts:"
+comms people --top 5
+```
+
+### Scheduled Sync (Hourly)
+
+```bash
+# Add to cron or use nexus cron skill
+# Sync communications every hour
+0 * * * * /opt/homebrew/bin/comms sync
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| Cross-channel view | Show all communications with Dad (iMessage + Gmail + WhatsApp) | Right after first sync |
+| Top contacts across channels | Show who user talks to most, regardless of medium | When user asks about relationships |
+| Timeline view | Show all activity for today across all channels | Morning briefing use case |
+| Project tagging | Tag events by project, then query all project comms | When user mentions project management |
+| Identity resolution | Show same person across phone, email, WhatsApp | When demonstrating intelligence |
+
+### Demo Script
+
+```
+Agent: "Let me show you what comms enables. I've unified your communications across all channels."
+
+comms db query "SELECT channel, COUNT(*) as events FROM events GROUP BY channel"
+
+Agent: "Here are the people you communicate with most, regardless of channel:"
+
+comms people --top 5
+
+Agent: "Now watch this - I can show you ALL communications with [Person], across iMessage, Gmail, and WhatsApp:"
+
+comms events --person "Dad" --limit 10
+
+Agent: "And I can see your activity timeline for today across all channels:"
+
+comms timeline --today
+
+Agent: "This means when you ask me about a conversation, I can find it no matter where it happened."
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **eve** | Provides iMessage data | Primary data source |
+| **gog** | Provides Gmail data | Primary data source |
+| **wacli** | Provides WhatsApp data | Primary data source |
+| **aix** | Provides AI session data | Secondary data source |
+| **bird** | Provides X/Twitter data | Secondary data source |
+| **qmd** | Comms events can be indexed | Semantic search across all comms |
+| **cron** | Schedule periodic syncs | Keep event store fresh |
+
+---
+
+## Testing Checklist
+
+- [ ] Fresh install: `brew install Napageneral/tap/comms`
+- [ ] Version check: `comms version`
+- [ ] Init works: `comms init`
+- [ ] Identity set: `comms me set ...`
+- [ ] Adapter connected: `comms connect imessage` (or other)
+- [ ] Adapters list works: `comms adapters`
+- [ ] Sync works: `comms sync`
+- [ ] Events show data: `comms events --limit 10`
+- [ ] People list works: `comms people --top 5`
+- [ ] Timeline works: `comms timeline --today`
+- [ ] SQL queries work: `comms db query "SELECT COUNT(*) FROM events"`
+- [ ] Cross-channel query: `comms events --person "Name"` shows multiple channels
+- [ ] Identity merge works: `comms identify --merge "A" "B"`
+
+---
+
+## Notes for Onboarding Agent
+
+- **Setup order matters**: Always setup eve and/or gog BEFORE comms
+- **At least one source required**: Comms needs eve OR gog (minimum)
+- **Recommend multiple sources**: More channels = better insights
+- **Identity configuration is critical**: Help user set canonical name/phone/email
+- **When NOT to recommend**:
+  - User has no communication skills setup (eve, gog, wacli)
+  - User only uses one communication channel (comms adds less value)
+- **Value proposition**: "Understand your communications holistically, regardless of channel"
+- **Time estimate**: 10 minutes (assumes prerequisites already setup)
+- **Sync frequency**: Recommend hourly sync via cron for near-real-time data
+
+---
+
+## Database Schema (comms.db)
+
+```sql
+-- Core tables
+events              -- All communication events
+  id                -- Unique event ID
+  timestamp         -- When it happened
+  channel           -- imessage, gmail, whatsapp, cursor, x
+  content_types     -- ["text"], ["text", "image"], etc.
+  direction         -- sent, received, observed
+  content_preview   -- First 200 chars
+
+persons             -- Identity-resolved people
+  id                -- Person ID
+  display_name      -- Canonical name
+
+identities          -- Channel-specific identities
+  person_id         -- Links to persons.id
+  channel           -- imessage, email, whatsapp, etc.
+  identifier        -- +1..., email address, @handle
+
+event_participants  -- Many-to-many: events ↔ persons
+  event_id
+  person_id
+
+tags                -- Event tags
+  event_id
+  tag               -- "project:htaa", "context:work"
+```
+
+---
+
+## SQL Query Examples
+
+```sql
+-- Total events per channel
+SELECT channel, COUNT(*) as events
+FROM events
+GROUP BY channel;
+
+-- Top contacts across all channels
+SELECT p.display_name, COUNT(*) as events
+FROM persons p
+JOIN event_participants ep ON p.id = ep.person_id
+GROUP BY p.id
+ORDER BY events DESC
+LIMIT 10;
+
+-- Communication with specific person across channels
+SELECT e.channel, COUNT(*) as events
+FROM events e
+JOIN event_participants ep ON e.id = ep.event_id
+JOIN persons p ON ep.person_id = p.id
+WHERE p.display_name = 'Dad'
+GROUP BY e.channel;
+
+-- Activity by date (last 30 days)
+SELECT date(timestamp/1000, 'unixepoch') as day,
+       channel,
+       COUNT(*) as events
+FROM events
+WHERE timestamp > (strftime('%s', 'now') - 2592000) * 1000
+GROUP BY day, channel
+ORDER BY day DESC;
+
+-- Find all events with specific tag
+SELECT e.*
+FROM events e
+JOIN tags t ON e.id = t.event_id
+WHERE t.tag = 'project:htaa';
+```
+
+---
+
+## Configuration File Structure
+
+`~/.config/comms/config.yaml`:
+
+```yaml
+me:
+  canonical_name: "Tyler Brandt"
+  identities:
+    - channel: imessage
+      identifier: "+17072876731"
+    - channel: email
+      identifier: "tnapathy@gmail.com"
+    - channel: whatsapp
+      identifier: "+17072876731"
+
+adapters:
+  imessage:
+    type: eve
+    enabled: true
+
+  gmail:
+    type: gogcli
+    enabled: true
+    account: tnapathy@gmail.com
+
+  gmail_work:
+    type: gogcli
+    enabled: true
+    account: tyler@company.com
+
+  whatsapp:
+    type: wacli
+    enabled: true
+
+  cursor:
+    type: aix
+    enabled: true
+
+  x:
+    type: bird
+    enabled: true
+
+identity_resolution:
+  # Auto-link phone and email if name matches
+  auto_merge: true
+  # Fuzzy match threshold (0.0-1.0)
+  match_threshold: 0.85
+```
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*