@intent-systems/nexus 2026.1.5-3

package/skills/comms/docs/troubleshooting.md

@@ -0,0 +1,44 @@
+# Comms Troubleshooting
+
+## No adapters found
+
+**Symptom:** `comms sync` reports no adapters configured.
+
+**Fix:**
+
+```bash
+comms adapters
+comms connect imessage   # or gmail/whatsapp/cursor/x
+```
+
+## Adapter auth failures
+
+**Symptom:** sync fails for a specific adapter.
+
+**Fix:** verify the underlying tool works, then retry.
+
+```bash
+eve whoami
+gog gmail labels list --account you@gmail.com
+wacli doctor
+aix stats
+bird whoami
+```
+
+## Identity resolution not working
+
+**Symptom:** same person appears multiple times.
+
+**Fix:**
+
+```bash
+comms identify
+comms identify --merge "Person A" "Person B"
+comms identify --add "Dad" --email "dad@example.com"
+```
+
+## Slow initial sync
+
+**Cause:** large history across sources.
+
+**Fix:** let it finish; future syncs are incremental.

package/skills/comms/references/schema.md

@@ -0,0 +1,49 @@
+# Comms Schema Reference
+
+## Core tables
+
+- `events` - all communication events
+- `persons` - identity-resolved people
+- `identities` - channel-specific identifiers (phone, email, handle)
+- `event_participants` - many-to-many events to persons
+- `tags` - event tags
+
+## SQL 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 a 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 a specific tag
+SELECT e.*
+FROM events e
+JOIN tags t ON e.id = t.event_id
+WHERE t.tag = 'project:htaa';
+```

package/skills/computer-use/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: computer-use
+description: Browser and desktop automation via AI agents (Open Interpreter, Peekaboo, or browser-use)
+homepage: https://github.com/OpenInterpreter/open-interpreter
+metadata: {"nexus":{"emoji":"🖥️","os":["darwin","linux"],"requires":{"anyBins":["interpreter","peekaboo"]},"install":[{"id":"interpreter","kind":"shell","script":"uv pip install open-interpreter --system","bins":["interpreter"],"label":"Install Open Interpreter"},{"id":"peekaboo","kind":"brew","formula":"steipete/tap/peekaboo","bins":["peekaboo"],"label":"Install Peekaboo (macOS native)"}]}}
+---
+
+# Computer Use
+
+Autonomous browser and desktop control for AI agents. Use this skill to:
+- Navigate websites and fill forms
+- Complete OAuth flows
+- Extract information from web pages
+- Automate repetitive UI tasks
+
+## Docs
+
+- `docs/setup.md`
+- `docs/peekaboo.md`
+- `docs/open-interpreter.md`
+- `docs/troubleshooting.md`
+
+## Tools Comparison
+
+| Tool | Best For | LLM | Complexity |
+|------|----------|-----|------------|
+| **Peekaboo** | Scripted macOS UI automation | None (you drive) | Low |
+| **Open Interpreter** | Full computer control | OpenAI/Anthropic/etc | Medium |
+| **browser-use** | Browser-only automation | Requires their API key | Medium |
+| **Claude Computer Use** | Anthropic's official solution | Claude | High (beta) |
+
+## Peekaboo (Scripted - Best for Simple Flows)
+
+Native macOS automation. **No LLM needed** - you write the script.
+
+```bash
+# Install
+brew install steipete/tap/peekaboo
+
+# OAuth flow example (scripted)
+peekaboo app switch --to "Google Chrome"
+peekaboo hotkey --keys "cmd,l"
+peekaboo paste --text "https://console.cloud.google.com/apis/credentials"
+peekaboo press return
+sleep 3
+peekaboo see --annotate --path /tmp/gcloud.png  # See what's there
+peekaboo click --coords 300,93  # Click "Create credentials"
+```
+
+**Pros:** Fast, no API costs, works with any app  
+**Cons:** Requires knowing exact coordinates/elements, no AI reasoning
+
+## Open Interpreter (LLM-Driven - Best for Complex Flows)
+
+Full computer control with AI reasoning.
+
+```bash
+# Install
+uv pip install open-interpreter --system
+
+# Run interactively
+interpreter
+
+# Or with a specific task
+interpreter --model gpt-4o -y "Navigate to Google Cloud Console and create OAuth credentials for a desktop app called 'gog-cli'"
+```
+
+**Pros:** AI can reason about UI, handle unexpected states  
+**Cons:** Slower, costs API tokens, may need guidance
+
+### peekaboo (macOS native UI)
+
+Native macOS automation. Best for:
+- Controlling any app (not just browsers)
+- Screenshot + OCR
+- Mouse/keyboard input
+- Window management
+
+```bash
+# Install
+brew install steipete/tap/peekaboo
+
+# Take annotated screenshot
+peekaboo see --app "Google Chrome" --annotate --path /tmp/screenshot.png
+
+# Click element
+peekaboo click --coords 100,200 --app "Google Chrome"
+
+# Type text
+peekaboo paste --text "hello world"
+peekaboo press return
+```
+
+## Dispatching Computer-Use Tasks (Subagent Pattern)
+
+For autonomous tasks, dispatch as a background agent:
+
+```bash
+# Create a task file
+cat > /tmp/browser-task.py << 'EOF'
+from browser_use import Browser
+browser = Browser()
+browser.run("""
+Go to console.cloud.google.com/apis/credentials
+Click "+ Create credentials" > "OAuth client ID"  
+Select "Desktop app"
+Name it "gog-cli"
+Click "Create"
+Download the JSON file
+Save to ~/.config/gog/credentials.json
+""")
+EOF
+
+# Run in background
+bash workdir:/tmp background:true command:"python browser-task.py"
+
+# Monitor
+process action:log sessionId:XXX
+```
+
+## Common Tasks
+
+### OAuth Setup
+
+```python
+# oauth_setup.py
+from browser_use import Browser
+
+def setup_oauth(service_name: str, scopes: list[str]):
+    browser = Browser()
+    browser.run(f"""
+    1. Go to console.cloud.google.com/apis/credentials
+    2. Click "+ Create credentials" > "OAuth client ID"
+    3. If prompted, configure consent screen first:
+       - User type: External
+       - App name: {service_name}
+       - Scopes: {', '.join(scopes)}
+    4. Application type: Desktop app
+    5. Name: {service_name}-cli
+    6. Click Create
+    7. Download JSON
+    8. Save to ~/.config/{service_name.lower()}/credentials.json
+    """)
+```
+
+### Form Filling
+
+```bash
+# Using peekaboo
+peekaboo app switch --to "Google Chrome"
+peekaboo hotkey --keys "cmd,l"
+peekaboo paste --text "https://example.com/signup"
+peekaboo press return
+sleep 2
+peekaboo see --annotate --path /tmp/form.png
+peekaboo click --on "email_field"
+peekaboo paste --text "user@example.com"
+peekaboo press tab
+peekaboo paste --text "password123"
+peekaboo click --on "submit_button"
+```
+
+### Screenshot Analysis
+
+```bash
+# Capture and analyze
+peekaboo see --mode frontmost --analyze "What buttons are visible?" --path /tmp/analysis.png
+```
+
+## Integration with Nexus Onboarding
+
+This skill enables autonomous onboarding setup:
+
+```bash
+# Nexus can dispatch computer-use to set up other skills
+bash workdir:/tmp background:true command:"python -c \"
+from browser_use import Browser
+Browser().run('Set up Gmail OAuth for gog-cli...')
+\""
+
+# Or use peekaboo for simpler tasks
+peekaboo app switch --to 'Google Chrome'
+peekaboo paste --text 'console.cloud.google.com' && peekaboo press return
+```
+
+## Limitations
+
+1. **Interactive sessions**: OAuth may require 2FA - agent will wait/prompt
+2. **CAPTCHAs**: May require human intervention
+3. **Rate limits**: Some sites detect automation
+4. **Credentials**: Never let agents see/store passwords directly
+
+## Best Practices
+
+1. **Sandbox first**: Test in incognito/isolated browser
+2. **Watch the first run**: Monitor agent's browser actions
+3. **Checkpoint often**: Save state after each major step
+4. **Fallback to manual**: Some flows are faster to do by hand
+
+## Related Skills
+
+- `peekaboo` - macOS UI automation (see/click/type)
+- `coding-agent` - Background agent dispatch pattern
+- `tmux` - Interactive terminal sessions

package/skills/computer-use/docs/open-interpreter.md

@@ -0,0 +1,26 @@
+# Open Interpreter (LLM-driven)
+
+Open Interpreter can reason through complex UI flows.
+
+## Run interactively
+
+```bash
+interpreter
+```
+
+## Run a task
+
+```bash
+interpreter --model gpt-4o -y "Navigate to Google Cloud Console and create OAuth credentials for a desktop app called 'gog-cli'"
+```
+
+## Model configuration
+
+```bash
+interpreter --model claude-3-5-sonnet-20241022
+```
+
+## Notes
+
+- Costs tokens; confirm before running long tasks.
+- Prefer Peekaboo for short, repeatable workflows.

package/skills/computer-use/docs/peekaboo.md

@@ -0,0 +1,26 @@
+# Peekaboo (macOS scripted UI)
+
+Peekaboo is fast and deterministic. Use it for known flows.
+
+## Common commands
+
+```bash
+peekaboo app switch --to "Google Chrome"
+peekaboo hotkey --keys "cmd,l"
+peekaboo paste --text "https://console.cloud.google.com/apis/credentials"
+peekaboo press return
+sleep 2
+peekaboo see --annotate --path /tmp/gcloud.png
+```
+
+Click by coordinates:
+
+```bash
+peekaboo click --coords 300,93
+```
+
+Screenshot analysis:
+
+```bash
+peekaboo see --analyze "What buttons are visible?" --path /tmp/analysis.png
+```

package/skills/computer-use/docs/setup.md

@@ -0,0 +1,47 @@
+# Computer Use Setup
+
+This guide covers the two primary tools used by this skill:
+- Peekaboo (macOS scripted UI automation)
+- Open Interpreter (LLM-driven automation)
+
+## Install Peekaboo (macOS)
+
+```bash
+brew install steipete/tap/peekaboo
+peekaboo --version
+```
+
+## Install Open Interpreter
+
+```bash
+uv pip install open-interpreter --system
+interpreter --version
+```
+
+## Permissions (macOS)
+
+Peekaboo requires:
+- Accessibility permission
+- Screen Recording permission
+
+Grant both in:
+System Settings -> Privacy & Security -> Accessibility / Screen Recording.
+
+Restart your terminal after granting permissions.
+
+## API keys (Open Interpreter)
+
+Set either OpenAI or Anthropic:
+
+```bash
+export OPENAI_API_KEY="your-key-here"
+# or
+export ANTHROPIC_API_KEY="your-key-here"
+```
+
+1Password examples:
+
+```bash
+export OPENAI_API_KEY=$(op read "op://Personal/OpenAI API Key/credential")
+export ANTHROPIC_API_KEY=$(op read "op://Personal/Anthropic API Key/credential")
+```

package/skills/computer-use/docs/troubleshooting.md

@@ -0,0 +1,33 @@
+# Computer Use Troubleshooting
+
+## Accessibility permission denied (Peekaboo)
+
+Grant Accessibility access:
+System Settings -> Privacy & Security -> Accessibility -> add Terminal.
+Restart Terminal and retry.
+
+## Screen Recording permission denied (Peekaboo)
+
+Grant Screen Recording access:
+System Settings -> Privacy & Security -> Screen Recording -> add Terminal.
+Restart Terminal and retry.
+
+## API key not found (Open Interpreter)
+
+```bash
+export OPENAI_API_KEY=$(op read "op://Personal/OpenAI API Key/credential")
+```
+
+or
+
+```bash
+export ANTHROPIC_API_KEY=$(op read "op://Personal/Anthropic API Key/credential")
+```
+
+## UI changes break Peekaboo scripts
+
+Use annotated screenshots to re-capture coordinates:
+
+```bash
+peekaboo see --annotate --path /tmp/debug.png
+```