@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/scripts/ralph/prd.json

@@ -0,0 +1,215 @@
+{
+  "project": "Onboarding Skill Deep-Dives",
+  "description": "Create comprehensive documentation for each skill to enable world-class onboarding",
+  "branchName": "feature/onboarding-skill-docs",
+  "skills": [
+    {
+      "id": "SKILL-001",
+      "name": "1password",
+      "priority": 1,
+      "category": "Foundation",
+      "status": "complete",
+      "notes": "Foundation skill - all others depend on this for credential storage",
+      "acceptanceCriteria": [
+        "Installation steps documented",
+        "CLI integration enable steps",
+        "Common failures (not signed in, integration not enabled)",
+        "Verification commands"
+      ]
+    },
+    {
+      "id": "SKILL-002",
+      "name": "gog",
+      "priority": 2,
+      "category": "Communication Data",
+      "status": "complete",
+      "notes": "MOST COMPLEX - Full Google OAuth flow, credentials.json setup, test users",
+      "acceptanceCriteria": [
+        "Full credentials.json creation process",
+        "OAuth consent screen setup",
+        "Test user addition process",
+        "Multi-account support documented",
+        "Token backup to 1Password",
+        "All failure points documented"
+      ]
+    },
+    {
+      "id": "SKILL-003",
+      "name": "eve",
+      "priority": 3,
+      "category": "Communication Data",
+      "status": "complete",
+      "notes": "Multiple capability tiers: read-only, send, analyze",
+      "acceptanceCriteria": [
+        "Tier 1: Read-only (Full Disk Access)",
+        "Tier 2: Send (Automation permissions)",
+        "Tier 3: Analyze (Gemini API)",
+        "Dual-account setup for agent identity",
+        "All permission steps documented"
+      ]
+    },
+    {
+      "id": "SKILL-004",
+      "name": "aix",
+      "priority": 4,
+      "category": "Code/Productivity",
+      "status": "complete",
+      "notes": "Auto-detects Cursor sessions, useful for ALL Cursor users not just coders",
+      "acceptanceCriteria": [
+        "Auto-detection logic documented",
+        "Supported editors (Cursor, Claude Code, etc.)",
+        "Indexing process",
+        "Search capabilities"
+      ]
+    },
+    {
+      "id": "SKILL-005",
+      "name": "comms",
+      "priority": 5,
+      "category": "Communication Data",
+      "status": "complete",
+      "notes": "Unified communication layer - aggregates eve, gog, wacli",
+      "acceptanceCriteria": [
+        "What sources it aggregates",
+        "Dependencies on other skills",
+        "Sync process",
+        "Cross-channel search capabilities"
+      ]
+    },
+    {
+      "id": "SKILL-006",
+      "name": "wacli",
+      "priority": 6,
+      "category": "Communication Data + Agent Reachability",
+      "status": "complete",
+      "notes": "Dual-purpose: read user WhatsApp AND agent identity. Requires REAL SIM.",
+      "acceptanceCriteria": [
+        "QR auth process",
+        "Real SIM requirement documented",
+        "Google Voice NOT working documented",
+        "User data access vs agent setup"
+      ]
+    },
+    {
+      "id": "SKILL-007",
+      "name": "github",
+      "priority": 7,
+      "category": "Code/Productivity",
+      "status": "complete",
+      "notes": "Simple gh auth login flow",
+      "acceptanceCriteria": [
+        "Installation",
+        "Auth flow",
+        "Key capabilities"
+      ]
+    },
+    {
+      "id": "SKILL-008",
+      "name": "bird",
+      "priority": 8,
+      "category": "Free Skill",
+      "status": "complete",
+      "notes": "Cookie-based auth - almost FREE, just needs Chrome login",
+      "acceptanceCriteria": [
+        "Cookie extraction process",
+        "No API key needed",
+        "Sweetistics alternative",
+        "Wow moment: reading feed"
+      ]
+    },
+    {
+      "id": "SKILL-009",
+      "name": "computer-use",
+      "priority": 9,
+      "category": "Advanced Automation",
+      "status": "complete",
+      "notes": "Key for automating onboarding itself! Test OAuth automation potential.",
+      "acceptanceCriteria": [
+        "Open Interpreter setup",
+        "Peekaboo setup",
+        "What can be automated (OAuth, form filling)",
+        "Limitations (CAPTCHAs, 2FA)"
+      ]
+    },
+    {
+      "id": "SKILL-010",
+      "name": "nexus-cloud",
+      "priority": 10,
+      "category": "Foundation",
+      "status": "complete",
+      "notes": "Workspace backup and sync - not blocking but important for durability",
+      "acceptanceCriteria": [
+        "Account creation",
+        "CLI auth",
+        "Sync capabilities",
+        "Shared workspaces"
+      ]
+    },
+    {
+      "id": "SKILL-011",
+      "name": "cron-and-heartbeat",
+      "priority": 11,
+      "category": "Automation",
+      "status": "complete",
+      "notes": "Built into gateway, not a standalone skill. Create concept doc.",
+      "acceptanceCriteria": [
+        "Cron job creation (nexus cron add)",
+        "Heartbeat configuration",
+        "Scheduling options (one-shot, recurring)",
+        "Wow moment: reminder delivered to phone"
+      ]
+    },
+    {
+      "id": "SKILL-012",
+      "name": "weather",
+      "priority": 12,
+      "category": "Free Skill",
+      "status": "complete",
+      "notes": "No setup required - uses wttr.in",
+      "acceptanceCriteria": [
+        "No setup needed",
+        "Best combined with morning briefing"
+      ]
+    },
+    {
+      "id": "SKILL-013",
+      "name": "qmd",
+      "priority": 13,
+      "category": "Productivity",
+      "status": "complete",
+      "notes": "Semantic search over notes/memory",
+      "acceptanceCriteria": [
+        "Indexing process",
+        "Search capabilities",
+        "Integration with memory folder"
+      ]
+    },
+    {
+      "id": "SKILL-014",
+      "name": "brave-search",
+      "priority": 14,
+      "category": "Productivity",
+      "status": "complete",
+      "notes": "Requires BRAVE_API_KEY - not free",
+      "acceptanceCriteria": [
+        "API key signup process",
+        "Cost considerations",
+        "Capabilities"
+      ]
+    },
+    {
+      "id": "SKILL-015",
+      "name": "homebrew-prereqs",
+      "priority": 15,
+      "category": "Foundation",
+      "status": "complete",
+      "notes": "Not a skill but critical - many users won't have brew/node/go installed",
+      "acceptanceCriteria": [
+        "Homebrew installation for new users",
+        "Node.js installation",
+        "Go installation",
+        "Detection of missing prereqs"
+      ]
+    }
+  ]
+}

package/skills/onboarding/scripts/ralph/progress.txt

@@ -0,0 +1,99 @@
+# Ralph Progress Log - Onboarding Skill Deep-Dives
+
+Started: 2025-01-08
+
+## Codebase Patterns
+
+- Skill docs are at `~/nexus/skills/<name>/SKILL.md`
+- Some skills have additional docs in `~/nexus/skills/<name>/docs/`
+- Deep-dive output goes to `~/nexus/skills/onboarding/docs/skill-deep-dives/<name>.md`
+- Use TEMPLATE.md as the format guide
+- Gateway docs (cron, heartbeat) are at `~/nexus/home/projects/nexus/docs/`
+
+## Key Files
+
+- Template: `docs/skill-deep-dives/TEMPLATE.md`
+- Planning: `docs/onboarding-wizard-planning.md`
+- Work plan: `docs/onboarding-work-plan.md`
+- Wow moments: `docs/wow-moments-and-activation.md`
+- Failure points: `docs/common-failure-points.md`
+
+## Cross-Skill Dependencies (Discovered)
+
+- comms depends on: eve OR gog (at least one)
+- eve Tier 3 depends on: Gemini API key
+- gog depends on: Google Cloud account with OAuth consent screen
+- All credential storage depends on: 1password
+- Agent reachability depends on: Anthropic API key (for agent to respond)
+
+## Important Notes
+
+- Many skills are Mac-only (eve, apple-notes, peekaboo, etc.)
+- Google Voice does NOT work for WhatsApp or Apple ID verification
+- gog has the most complex setup - document EVERY step
+- homebrew is a hidden dependency for most installs
+
+---
+
+## Progress Log
+
+(Append entries here after each skill)
+
+### 2026-01-12 - ALL SKILLS COMPLETE
+
+Successfully created comprehensive deep-dive documentation for all 15 skills:
+
+**Foundation Skills:**
+1. ✅ 1password - Credential storage foundation, manual permission steps documented
+2. ✅ homebrew-prereqs - Prerequisite doc for brew/node/go installation
+
+**Communication Data:**
+3. ✅ gog - MOST COMPLEX: OAuth flow, credentials.json, test users, CDP automation
+4. ✅ eve - Tier-based setup (read/send/intelligence/dual-account), macOS-only
+5. ✅ comms - Aggregator skill, depends on eve OR gog minimum
+6. ✅ wacli - REAL SIM requirement (Google Voice does NOT work), QR auth
+7. ✅ bird - Cookie-based (FREE), easiest setup, works immediately
+
+**Code/Productivity:**
+8. ✅ aix - AI session history, auto-detects Cursor/Claude Code/etc.
+9. ✅ github - Simple gh auth flow, 2-minute setup
+10. ✅ qmd - Local search with Ollama, BM25+vector+rerank
+11. ✅ brave-search - Web search API, requires API key
+
+**Automation:**
+12. ✅ computer-use - Peekaboo + Open Interpreter, OAuth automation potential
+13. ✅ cron-and-heartbeat - Gateway feature doc (not standalone skill)
+
+**Utilities:**
+14. ✅ nexus-cloud - Encrypted workspace sync via Cloudflare, zero-knowledge
+15. ✅ weather - wttr.in + Open-Meteo, no setup required
+
+## Key Learnings
+
+### Complexity Tiers
+- **Very Hard**: gog (OAuth), eve (Tier 4), nexus-cloud (Cloudflare setup)
+- **Medium**: comms, wacli, computer-use, qmd, eve (Tier 1-3)
+- **Easy**: 1password, aix, github, bird, weather, brave-search
+
+### Critical Warnings
+1. **Google Voice does NOT work**: wacli (WhatsApp), eve (Apple ID for dual-account)
+2. **Manual permission steps**: 1password (app integration), eve (Full Disk Access, Automation)
+3. **Test users critical**: gog OAuth consent - "access_denied" if missing
+4. **Browser automation limitations**: CAPTCHAs, 2FA require human intervention
+
+### Setup Order Recommendations
+1. Start with: 1password (foundation for all credentials)
+2. Then pick communication path:
+   - Path A: eve → comms (if macOS user)
+   - Path B: gog → comms (if non-macOS or prefer Gmail)
+3. Add-ons: aix (universal), github (developers), bird (X users)
+4. Advanced: wacli (agent reachability), computer-use (automation), nexus-cloud (sync)
+
+### Time Estimates
+- Quick wins (2-5 min): bird, github, weather, aix
+- Standard (5-10 min): 1password, wacli (after auth), brave-search
+- Complex (10-20 min): eve (Tier 1-2), comms (after deps)
+- Very complex (20-40 min): gog (manual), eve (Tier 4), nexus-cloud
+
+### Files Created (15 total)
+All files in: `~/nexus/skills/onboarding/docs/skill-deep-dives/`

package/skills/onboarding/scripts/ralph/prompt.md

@@ -0,0 +1,87 @@
+# Ralph Agent Instructions - Onboarding Skill Deep-Dives
+
+## Your Task
+
+You are researching and documenting Nexus skills for the onboarding system. Your goal is to create comprehensive deep-dive documentation for each skill.
+
+## Context
+
+1. Read `scripts/ralph/prd.json` for the task list
+2. Read `scripts/ralph/progress.txt` for learnings from previous iterations
+3. Read `docs/skill-deep-dives/TEMPLATE.md` for the documentation format
+
+## For Each Skill Deep-Dive
+
+1. **Read the skill's SKILL.md** - Located at `~/nexus/skills/<skill_name>/SKILL.md`
+2. **Check for additional docs** - Some skills have `docs/` folders
+3. **Test the installation** - Run the install commands, note any issues
+4. **Identify dependencies** - What other skills/tools are required?
+5. **Document failure points** - What can go wrong?
+6. **Find automation opportunities** - What can be scripted?
+7. **Identify wow moments** - What impresses users?
+
+## Output Format
+
+Create a deep-dive doc at: `docs/skill-deep-dives/<skill_name>.md`
+
+Follow the TEMPLATE.md structure exactly:
+- What It Enables (capabilities table)
+- Capability Tiers (if applicable)
+- Dependencies (hard and soft)
+- Installation steps
+- Configuration
+- User Actions Required (manual steps)
+- Common Failure Points
+- Automation Opportunities
+- Wow Moments
+- Integration with Other Skills
+- Testing Checklist
+
+## Special Considerations
+
+### For gog (Google APIs)
+- Document the FULL credentials.json setup process
+- Document test user addition
+- Note the OAuth consent screen requirements
+- This is the most complex skill - be thorough
+
+### For skills with capability tiers (eve, etc.)
+- Document each tier separately
+- What additional permissions/setup each tier requires
+
+### For dual-purpose skills (wacli, gog)
+- Document both user data access AND agent identity setup
+
+## Verification
+
+After creating each deep-dive:
+1. Verify all commands actually work
+2. Check that dependencies are correct
+3. Ensure failure points are accurate
+
+## Progress Tracking
+
+After completing a skill:
+1. Update prd.json: set `"status": "complete"`
+2. Append learnings to progress.txt
+3. Note any cross-skill dependencies discovered
+
+## Stop Condition
+
+If ALL skills in prd.json are complete, reply:
+<promise>COMPLETE</promise>
+
+Otherwise, pick the next highest priority skill and continue.
+
+---
+
+## Codebase Patterns
+
+Check progress.txt for patterns discovered in previous iterations.
+
+## Important Notes
+
+- Some skills are Mac-only - note this prominently
+- Some skills require external accounts (Google Cloud, etc.) - document the full account setup
+- If a skill has no SKILL.md or is deprecated, note it and skip
+- For skills that reference nexus gateway docs (cron, heartbeat), create a skill doc that explains the concept and points to the gateway docs

package/skills/onboarding/scripts/ralph/ralph.log

@@ -0,0 +1,84 @@
+🚀 Starting Ralph - Onboarding Skill Deep-Dives
+   Max iterations: 20
+   Working directory: /Users/tyler/nexus/skills/onboarding
+
+═══════════════════════════════════════════════════════════════
+═══ Iteration 1 of 20 ═══
+═══════════════════════════════════════════════════════════════
+
+Perfect! Let me provide the final completion summary.
+
+## COMPLETE ✅
+
+I have successfully created comprehensive deep-dive documentation for all 15 Nexus skills. Here's the summary:
+
+### Documentation Created
+
+**15 skill deep-dives** totaling **~220KB** and **8,614 lines** of comprehensive documentation:
+
+1. **1password** (11KB) - Credential storage foundation, manual permission steps
+2. **gog** (20KB) - Most complex: OAuth flow, credentials.json, test users, CDP automation
+3. **eve** (22KB) - Largest doc: 4 capability tiers, macOS-only, dual-account setup
+4. **aix** (13KB) - AI session history across Cursor/Claude Code/etc.
+5. **comms** (14KB) - Communication aggregator, unifies eve/gog/wacli
+6. **wacli** (10KB) - WhatsApp CLI, REAL SIM required (Google Voice won't work)
+7. **github** (7.5KB) - Simplest: gh CLI auth flow
+8. **bird** (9.1KB) - Cookie-based X/Twitter, free and instant
+9. **computer-use** (17KB) - Peekaboo + Open Interpreter for automation
+10. **nexus-cloud** (18KB) - Zero-knowledge encrypted workspace sync
+11. **cron-and-heartbeat** (14KB) - Gateway feature documentation
+12. **weather** (12KB) - wttr.in + Open-Meteo, no setup
+13. **qmd** (16KB) - Local search with BM25, vectors, Ollama
+14. **brave-search** (15KB) - Web search API
+15. **homebrew-prereqs** (18KB) - Foundation prerequisites doc
+
+### What Each Document Includes
+
+Every deep-dive follows the TEMPLATE.md structure with:
+- ✅ What It Enables (capability tables)
+- ✅ Capability Tiers (where applicable)
+- ✅ Dependencies (hard/soft/enables)
+- ✅ Installation & Configuration steps
+- ✅ User Actions Required (manual steps that can't be automated)
+- ✅ Common Failure Points with recovery procedures
+- ✅ Automation Opportunities with scripts
+- ✅ Wow Moments for demonstrations
+- ✅ Integration with Other Skills
+- ✅ Testing Checklists
+- ✅ Notes for Onboarding Agent
+
+### Key Learnings Documented
+
+**Complexity Tiers:**
+- Very Hard: gog, eve (Tier 4), nexus-cloud
+- Medium: comms, wacli, computer-use, qmd, eve (Tier 1-3)
+- Easy: 1password, aix, github, bird, weather, brave-search
+
+**Critical Warnings:**
+- Google Voice does NOT work for wacli or eve dual-account
+- Manual permissions required for 1password and eve
+- gog test users are CRITICAL to avoid "access_denied"
+
+**Setup Order Recommendations:**
+1. Start: 1password (credential foundation)
+2. Communication path: eve (macOS) OR gog (universal)
+3. Add-ons: aix, github, bird
+4. Advanced: wacli, computer-use, nexus-cloud
+
+### Status Updates
+
+- ✅ Updated prd.json: All 15 skills marked "complete"
+- ✅ Updated progress.txt: Comprehensive learnings appended
+- ✅ All files verified and present
+
+### Next Steps
+
+These deep-dives are now ready to:
+1. Power the onboarding wizard logic
+2. Guide users through skill setup
+3. Help agents understand failure recovery
+4. Enable automated setup where possible
+
+<promise>COMPLETE</promise>
+
+✅ All skills documented! Ralph is done.

package/skills/onboarding/scripts/ralph/ralph.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+set -e
+
+# Ralph Runner for Onboarding Skill Deep-Dives
+# Usage: ./ralph.sh [max_iterations]
+
+MAX_ITERATIONS=${1:-15}
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ONBOARDING_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+echo "🚀 Starting Ralph - Onboarding Skill Deep-Dives"
+echo "   Max iterations: $MAX_ITERATIONS"
+echo "   Working directory: $ONBOARDING_DIR"
+echo ""
+
+cd "$ONBOARDING_DIR"
+
+for i in $(seq 1 $MAX_ITERATIONS); do
+  echo "═══════════════════════════════════════════════════════════════"
+  echo "═══ Iteration $i of $MAX_ITERATIONS ═══"
+  echo "═══════════════════════════════════════════════════════════════"
+  echo ""
+  
+  # Run Claude Code with the prompt
+  # Using claude instead of amp since that's what Tyler has
+  OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" \
+    | claude --dangerously-skip-permissions 2>&1 \
+    | tee /dev/stderr) || true
+  
+  # Check for completion
+  if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
+    echo ""
+    echo "✅ All skills documented! Ralph is done."
+    exit 0
+  fi
+  
+  echo ""
+  echo "--- Iteration $i complete, sleeping 5s ---"
+  sleep 5
+done
+
+echo ""
+echo "⚠️ Max iterations ($MAX_ITERATIONS) reached"
+echo "   Run again to continue: ./ralph.sh"
+exit 1

package/skills/onboarding/scripts/setup-cursor-skills.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Setup Cursor Agent Skills by symlinking nexus skills to ~/.codex/skills/
+# This enables Cursor's dynamic skill discovery feature
+
+set -e
+
+NEXUS_SKILLS="${NEXUS_SKILLS:-$HOME/nexus/skills}"
+CODEX_SKILLS="$HOME/.codex/skills"
+
+echo "Setting up Cursor Agent Skills..."
+echo "  Source: $NEXUS_SKILLS"
+echo "  Target: $CODEX_SKILLS"
+
+# Create codex skills directory if needed
+mkdir -p "$CODEX_SKILLS"
+
+# Count for summary
+linked=0
+skipped=0
+
+# Symlink each skill
+for skill_dir in "$NEXUS_SKILLS"/*/; do
+    skill_name=$(basename "$skill_dir")
+    target="$CODEX_SKILLS/$skill_name"
+    
+    if [ -e "$target" ]; then
+        echo "  ⏭️  $skill_name (already exists)"
+        ((skipped++))
+    else
+        ln -s "$skill_dir" "$target"
+        echo "  ✅ $skill_name"
+        ((linked++))
+    fi
+done
+
+echo ""
+echo "Done! Linked $linked skills, skipped $skipped existing."
+echo ""
+echo "To verify, restart Cursor and ask an agent: 'What skills are available?'"
+echo "The agent should list all $(ls -d "$NEXUS_SKILLS"/*/ 2>/dev/null | wc -l | tr -d ' ') nexus skills."

package/skills/openai-image-gen/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: openai-image-gen
+description: Batch-generate images via OpenAI Images API. Random prompt sampler + `index.html` gallery.
+homepage: https://platform.openai.com/docs/api-reference/images
+metadata: {"nexus":{"emoji":"🖼️","requires":{"bins":["python3"],"env":["OPENAI_API_KEY"]},"primaryEnv":"OPENAI_API_KEY","install":[{"id":"python-brew","kind":"brew","formula":"python","bins":["python3"],"label":"Install Python (brew)"}]}}
+---
+
+# OpenAI Image Gen
+
+Generate a handful of “random but structured” prompts and render them via the OpenAI Images API.
+
+## Run
+
+```bash
+python3 {baseDir}/scripts/gen.py
+open ~/Projects/tmp/openai-image-gen-*/index.html  # if ~/Projects/tmp exists; else ./tmp/...
+```
+
+Useful flags:
+
+```bash
+python3 {baseDir}/scripts/gen.py --count 16 --model gpt-image-1.5
+python3 {baseDir}/scripts/gen.py --prompt "ultra-detailed studio photo of a lobster astronaut" --count 4
+python3 {baseDir}/scripts/gen.py --size 1536x1024 --quality high --out-dir ./out/images
+```
+
+## Output
+
+- `*.png` images
+- `prompts.json` (prompt → file mapping)
+- `index.html` (thumbnail gallery)