@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/skill-deep-dives/1password.md

@@ -0,0 +1,367 @@
+# Skill Deep-Dive: 1password
+
+**Skill**: `1password`
+**Category**: Local Foundation
+**Setup Difficulty**: 🟡 Medium
+**Time Estimate**: ~5-10 minutes
+**Platform**: Cross-platform (macOS, Windows, Linux)
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| Secure secret storage | Store and retrieve credentials without writing them to disk | `op read op://vault/item/password` |
+| Secret injection | Inject secrets into config files or env vars | `op inject -i config.tpl -o config.yml` |
+| Secure command execution | Run commands with secrets in environment | `op run -- ./script.sh` |
+| Multi-account management | Switch between personal and work accounts | `op signin --account work` |
+| Cross-skill credential provider | All other skills depend on this for storing API keys, tokens, etc. | Used by gog, eve, wacli, etc. |
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] `1Password account` — Requires active subscription
+- [ ] `1Password desktop app` — Required for app integration (recommended auth method)
+- [ ] `brew` (macOS) or equivalent package manager — For installing `op` CLI
+
+### Soft Dependencies (Recommended)
+- [ ] `tmux` skill — For avoiding repeated auth prompts in automation contexts
+
+### This Skill Enables
+- [ ] `gog` — Stores Google OAuth tokens
+- [ ] `eve` — Stores email credentials
+- [ ] `wacli` — Stores WhatsApp session tokens
+- [ ] `nexus-cloud` — Stores cloud API keys
+- [ ] `brave-search` — Stores Brave API key
+- [ ] **ALL skills that require credentials** — Foundation for secure credential management
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check if 1Password desktop app is installed
+# macOS:
+ls -la /Applications/1Password.app && echo "✅ 1Password app found" || echo "❌ Need to install 1Password app"
+
+# Check if brew is installed (macOS)
+which brew || echo "❌ Need to install Homebrew first"
+```
+
+### Installation Steps
+
+```bash
+# Step 1: Install 1Password CLI
+brew install 1password-cli
+
+# Step 2: Verify installation
+op --version
+# Expected output: e.g., "2.25.0"
+```
+
+### Verification
+
+```bash
+# Verify CLI is accessible
+op --version
+
+# Check for desktop app integration capability
+op whoami
+# If not configured, will prompt to enable integration
+```
+
+---
+
+## Configuration
+
+### Required Configuration
+
+**Enable Desktop App Integration** (CANNOT be automated - requires manual steps):
+
+1. **Open 1Password desktop app** and unlock it
+2. **Select your account/collection** (if you have multiple)
+3. **Navigate to settings**:
+   - **macOS**: 1Password → Settings → Developer → Enable "Integrate with 1Password CLI"
+     - Optional: Enable "Use Touch ID to authenticate" for biometric auth
+   - **Windows**: Turn on Windows Hello first, then Settings → Developer → Enable "Integrate with 1Password CLI"
+   - **Linux**: Settings → Security → Enable "Unlock using system authentication", then Settings → Developer → Enable "Integrate with 1Password CLI"
+     - Requires PolKit + an auth agent
+
+### First Sign-In
+
+```bash
+# Step 1: Sign in (will open 1Password app for authorization)
+op signin
+
+# Step 2: Verify authentication
+op whoami
+# Expected output: Shows your account details
+
+# Step 3: List vaults to confirm access
+op vault list
+```
+
+### Optional Configuration
+
+```bash
+# For multiple accounts: Set default account
+export OP_ACCOUNT="my.1password.com"
+
+# Or specify account per command
+op whoami --account work.1password.com
+```
+
+---
+
+## User Actions Required
+
+List any manual steps the user MUST perform (can't be automated):
+
+1. **Install 1Password desktop app**: Download from 1Password website, install, and create/sign in to account
+2. **Enable CLI integration**: Open 1Password app → Settings → Developer → Toggle "Integrate with 1Password CLI"
+3. **Authorize terminal on first use**: When running first `op` command, click "Authorize" in the desktop app prompt
+4. **Keep app unlocked**: Desktop app must be unlocked for CLI to work with app integration
+
+---
+
+## Common Failure Points
+
+### Failure: "1Password CLI is not signed in"
+
+**Symptom**: Running `op` commands returns error: `[ERROR] 1Password CLI is not signed in. Run 'op signin' to sign in.`
+
+**Cause**: Either app integration not enabled, desktop app is locked, or terminal not authorized
+
+**Recovery**:
+```bash
+# Step 1: Verify desktop app is running and unlocked
+# (Open 1Password app manually)
+
+# Step 2: Re-run sign in
+op signin
+
+# Step 3: Authorize in the desktop app when prompted
+
+# Step 4: Verify
+op whoami
+```
+
+**Prevention**: Keep 1Password desktop app running and unlocked during automation tasks
+
+---
+
+### Failure: "Desktop app integration not enabled"
+
+**Symptom**: CLI doesn't connect to app, or prompts for manual credentials
+
+**Cause**: Integration toggle not enabled in 1Password settings
+
+**Recovery**:
+1. Open 1Password desktop app
+2. Go to Settings → Developer
+3. Enable "Integrate with 1Password CLI"
+4. Run `op signin` again
+
+**Prevention**: Follow installation configuration steps completely
+
+---
+
+### Failure: Repeated auth prompts in automation
+
+**Symptom**: Every `op` command triggers a new authorization prompt in the desktop app
+
+**Cause**: Each bash command runs in a fresh TTY, losing auth session context
+
+**Recovery**: Use tmux to maintain session across commands
+```bash
+# Create persistent tmux session for op commands
+SOCKET_DIR="${NEXUS_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nexus-tmux-sockets}"
+mkdir -p "$SOCKET_DIR"
+SOCKET="$SOCKET_DIR/nexus.sock"
+SESSION=op-auth
+
+# Start session
+tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
+
+# Run commands in the same session
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op signin" Enter
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op vault list" Enter
+
+# Capture output
+tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+**Prevention**: For automation scripts, consolidate multiple `op` commands into a single bash session or tmux window
+
+---
+
+### Failure: Multi-account confusion
+
+**Symptom**: Commands work but access wrong account's vaults
+
+**Cause**: Multiple 1Password accounts signed in, CLI using wrong account by default
+
+**Recovery**:
+```bash
+# List all accounts
+op account list
+
+# Sign in to specific account
+op signin --account work.1password.com
+
+# Or set environment variable
+export OP_ACCOUNT="work.1password.com"
+
+# Verify correct account
+op whoami
+```
+
+**Prevention**: Set `OP_ACCOUNT` environment variable for multi-account setups
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Install CLI | ✅ Yes | bash | `brew install 1password-cli` |
+| Check if app installed | ✅ Yes | bash | Check for app bundle path |
+| Enable app integration | ❌ No | - | Requires manual toggle in app settings |
+| First signin | ❌ No | - | Requires clicking "Authorize" in app |
+| Read secrets | ✅ Yes | bash | `op read op://vault/item/field` |
+| Inject into files | ✅ Yes | bash | `op inject -i template -o output` |
+| Run with secrets | ✅ Yes | bash | `op run -- command` |
+| Detect if signed in | ✅ Yes | bash | `op whoami` (check exit code) |
+
+### Automation Script
+
+```bash
+# Check if 1Password CLI is ready for use
+#!/bin/bash
+
+# Check if op CLI is installed
+if ! command -v op &> /dev/null; then
+    echo "❌ 1Password CLI not installed"
+    echo "Run: brew install 1password-cli"
+    exit 1
+fi
+
+# Check if signed in
+if ! op whoami &> /dev/null; then
+    echo "❌ Not signed in to 1Password"
+    echo "Run: op signin"
+    echo "Make sure 1Password desktop app is running and unlocked"
+    exit 1
+fi
+
+echo "✅ 1Password CLI ready"
+op whoami
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| Secret-free config files | Show a config template with `{{ op://... }}` placeholders, then inject actual secrets without exposing them | After first successful signin |
+| Zero secrets on disk | Run a script that uses API keys without ever writing them to `.env` files | When setting up first skill that needs credentials |
+| Cross-account switching | Seamlessly switch between personal and work accounts | When user mentions having multiple 1Password accounts |
+
+### Demo Script
+
+```
+Agent: "Let me show you how 1Password keeps your credentials secure. Instead of storing API keys in files, we'll reference them directly from your vault."
+
+# Create a demo template
+echo 'DATABASE_URL={{ op://dev/postgres/url }}' > config.template
+
+# Inject without exposing secret
+op inject -i config.template
+
+Agent: "Notice how the secret was retrieved but never written to disk? This is how all your Nexus skills will store credentials securely."
+
+# Alternative: Run command with secret in environment
+export API_KEY='op://dev/api-keys/openai'
+op run -- env | grep API_KEY
+
+Agent: "The secret is loaded into the environment only while the command runs, then disappears."
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **gog** | Stores `credentials.json` and OAuth tokens | Critical: gog token must be backed up to 1Password |
+| **eve** | Stores email account credentials | Uses op:// references for secure storage |
+| **wacli** | Stores WhatsApp session data | Prevents loss of WhatsApp connection |
+| **nexus-cloud** | Stores cloud API credentials | For workspace sync |
+| **brave-search** | Stores Brave API key | Alternative to environment variables |
+| **tmux** | Avoids repeated auth prompts | Use tmux sessions for automation |
+| **All credential-dependent skills** | Foundation for secure storage | Setup 1Password before any skill that needs secrets |
+
+---
+
+## Testing Checklist
+
+- [ ] Fresh install works: `brew install 1password-cli`
+- [ ] CLI version check: `op --version`
+- [ ] Desktop app integration enabled (manual step verified)
+- [ ] Sign in works: `op signin` + authorize in app
+- [ ] Whoami shows account: `op whoami`
+- [ ] Can list vaults: `op vault list`
+- [ ] Can read a secret: `op read op://vault/item/field`
+- [ ] Inject works: `op inject -i template`
+- [ ] Run works: `op run -- env`
+- [ ] Multi-account switching works (if applicable)
+- [ ] Failure recovery: Lock app, try command, see error, unlock, retry
+
+---
+
+## Notes for Onboarding Agent
+
+- **ALWAYS recommend this skill FIRST** - It's the foundation for all credential storage
+- **Check if user has 1Password account** - If not, they need to create one first (requires subscription)
+- **Emphasize manual steps** - Desktop app integration CANNOT be automated
+- **For new users**: Explain why this is better than `.env` files (no secrets on disk, no git accidents)
+- **For users coming from other systems**: Show how `op://` references replace environment variables
+- **When NOT to recommend**: If user doesn't have/want 1Password subscription (suggest alternative: environment variables with strong warnings)
+- **Security reminder**: Never ask user to paste secrets in chat - always use `op://` references
+- **Multi-account awareness**: Ask if they have work/personal accounts - setup is slightly different
+
+---
+
+## Platform-Specific Notes
+
+### macOS
+- Requires Big Sur 11.0.0 or later
+- Touch ID integration available (optional but recommended)
+- Most seamless experience
+
+### Windows
+- Requires Windows Hello to be enabled first
+- Then enable CLI integration in settings
+
+### Linux
+- Requires PolKit + an auth agent
+- Enable "Unlock using system authentication" first
+- Then enable CLI integration
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*

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

@@ -0,0 +1,197 @@
+# Skill Deep-Dive: [SKILL_NAME]
+
+**Skill**: `[skill_name]`  
+**Category**: [Local Foundation | Communication Data | Code/Productivity | Agent Reachability | Automation | Free]  
+**Setup Difficulty**: [🟢 Easy | 🟡 Medium | 🟠 Hard | 🔴 Very Hard]  
+**Time Estimate**: ~X minutes  
+**Platform**: [macOS | Cross-platform | macOS + Linux]
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| [Capability 1] | [What it does] | `command example` |
+| [Capability 2] | [What it does] | `command example` |
+
+---
+
+## Capability Tiers (if applicable)
+
+| Tier | What's Enabled | Additional Requirements |
+|------|----------------|------------------------|
+| Tier 1 | [Basic capability] | [What's needed] |
+| Tier 2 | [Enhanced capability] | [What's needed] |
+| Tier 3 | [Full capability] | [What's needed] |
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] `dependency_1` — Reason
+- [ ] `dependency_2` — Reason
+
+### Soft Dependencies (Recommended)
+- [ ] `dependency_1` — Reason
+- [ ] `dependency_2` — Reason
+
+### This Skill Enables
+- [ ] `other_skill` — How it enables it
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check if prerequisites are met
+which [binary] || echo "Need to install [thing]"
+```
+
+### Installation Steps
+
+```bash
+# Step 1: [Description]
+[command]
+
+# Step 2: [Description]
+[command]
+```
+
+### Verification
+
+```bash
+# Verify installation
+[verification_command]
+```
+
+---
+
+## Configuration
+
+### Required Configuration
+
+```bash
+# [Description of what this configures]
+[command]
+```
+
+### Optional Configuration
+
+```bash
+# [Description]
+[command]
+```
+
+---
+
+## User Actions Required
+
+List any manual steps the user MUST perform (can't be automated):
+
+1. **[Action]**: [Description of what to click/do]
+2. **[Action]**: [Description of what to click/do]
+
+---
+
+## Common Failure Points
+
+### Failure: [Failure name]
+
+**Symptom**: [What the user sees]
+
+**Cause**: [Why it happens]
+
+**Recovery**:
+```bash
+[recovery_commands]
+```
+
+**Prevention**: [How to avoid this]
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| [Step 1] | ✅ Yes | bash | [notes] |
+| [Step 2] | ❌ No | - | Requires manual click |
+| [Step 3] | 🟡 Partial | computer-use | [notes] |
+
+### Automation Script (if available)
+
+```bash
+# Path: skills/onboarding/scripts/automation/[skill]-setup.sh
+[script_content_or_link]
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| [Moment 1] | [Description] | After [step] |
+
+### Demo Script
+
+```
+Agent: "[What to say to user]"
+
+[commands to run]
+
+Agent: "[What to say after]"
+```
+
+---
+
+## Dual-Purpose Usage (if applicable)
+
+### For User Data Access
+- [How to use for reading user's data]
+
+### For Agent Identity
+- [How to use for agent's own account]
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| comms | [How they integrate] | [notes] |
+| [other] | [How they integrate] | [notes] |
+
+---
+
+## Testing Checklist
+
+- [ ] Fresh install works
+- [ ] Verification command passes
+- [ ] Each capability tier works
+- [ ] Failure recovery works
+- [ ] Integration with dependent skills works
+
+---
+
+## Notes for Onboarding Agent
+
+- [Special considerations for the onboarding agent]
+- [When to recommend this skill]
+- [When NOT to recommend this skill]
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| YYYY-MM-DD | Initial deep-dive |
+
+---
+
+*Template version: 1.0*