@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/skill-deep-dives/nexus-cloud.md

@@ -0,0 +1,689 @@
+# Skill Deep-Dive: nexus-cloud
+
+**Skill**: `nexus-cloud`
+**Category**: Automation (Backup & Sync)
+**Setup Difficulty**: 🔴 Very Hard
+**Time Estimate**: ~30-45 minutes
+**Platform**: Cross-platform (macOS, Windows, Linux)
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| Encrypted workspace backup | Zero-knowledge backup of entire Nexus workspace | `nexus-cloud push -m "Daily backup"` |
+| Cross-device sync | Sync workspace between multiple devices | `nexus-cloud pull` on new device |
+| Version history | Git-like commit history for workspace | `nexus-cloud log` |
+| Rollback capability | Restore workspace to any previous state | `nexus-cloud checkout <commit>` |
+| Selective sync | Exclude sensitive files from backup | `.nexusignore` configuration |
+| E2E encryption | All data encrypted client-side before upload | Server cannot read your data |
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] Cloudflare account (free tier works)
+- [ ] `wrangler` CLI — For deploying Cloudflare Workers
+- [ ] `node` + `npm` — For installing wrangler
+- [ ] R2 storage bucket — Cloudflare's S3-compatible storage
+- [ ] Durable Objects — For storing metadata
+
+### Soft Dependencies (Recommended)
+- [ ] `1password` skill — For storing API keys and master password
+- [ ] `git` — Familiar mental model (nexus-cloud is Git-like)
+
+### This Skill Enables
+- [ ] Multi-device workflow — Work from laptop, desktop, remote server
+- [ ] Disaster recovery — Lose device? Pull workspace on new machine
+- [ ] Version control — Track changes to workspace over time
+- [ ] Secure backup — Never lose Nexus configuration
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check for Node.js
+which node && node --version || echo "❌ Need Node.js"
+
+# Check for npm
+which npm && npm --version || echo "❌ Need npm"
+
+# Check for wrangler
+which wrangler && echo "✅ wrangler installed" || echo "⚠️  Need to install wrangler"
+
+# Check for Cloudflare account
+echo "❓ Do you have a Cloudflare account? (free tier works)"
+```
+
+### Installation Steps
+
+#### Step 1: Install Wrangler
+
+```bash
+# Install wrangler globally
+npm install -g wrangler
+
+# Or via brew (macOS)
+brew install wrangler
+
+# Verify installation
+wrangler --version
+```
+
+#### Step 2: Authenticate with Cloudflare
+
+```bash
+# Login to Cloudflare
+wrangler login
+
+# This opens browser for OAuth authentication
+# Click "Allow" to grant wrangler access
+
+# Verify authentication
+wrangler whoami
+```
+
+#### Step 3: Clone/Obtain nexus-cloud Project
+
+```bash
+# Navigate to projects directory
+cd ~/nexus/home/projects
+
+# Clone or verify nexus-cloud exists
+ls nexus-cloud || echo "❌ nexus-cloud project not found"
+
+cd nexus-cloud
+```
+
+#### Step 4: Create R2 Bucket
+
+```bash
+# Create R2 bucket for encrypted blobs
+wrangler r2 bucket create nexus-blobs
+
+# Verify bucket created
+wrangler r2 bucket list | grep nexus-blobs
+```
+
+#### Step 5: Deploy Cloudflare Worker
+
+```bash
+# Deploy the worker and Durable Object
+cd ~/nexus/home/projects/nexus-cloud
+wrangler deploy
+
+# Note the deployed URL (e.g., nexus-cloud.your-account.workers.dev)
+```
+
+### Verification
+
+```bash
+# Check wrangler
+wrangler whoami
+
+# Check R2 bucket
+wrangler r2 bucket list | grep nexus-blobs
+
+# Check worker deployment
+wrangler deployments list
+```
+
+---
+
+## Configuration
+
+### Step 1: Initialize nexus-cloud Locally
+
+```bash
+# Initialize nexus-cloud (creates encryption keys)
+nexus-cloud init
+
+# You'll be prompted for:
+# 1. Worker URL: https://nexus-cloud.your-account.workers.dev
+# 2. Master password: Create a STRONG password (you'll need this for recovery)
+
+# CRITICAL: Store master password in 1Password
+op item create \
+  --category "Password" \
+  --title "Nexus Cloud Master Password" \
+  --vault Personal \
+  "password=$(echo 'your-master-password-here')"
+```
+
+### Step 2: Configure .nexusignore
+
+```bash
+# Create .nexusignore to exclude sensitive files
+cat > ~/nexus/home/.nexusignore << 'EOF'
+# Never sync these sensitive directories
+sessions/
+.env
+*credentials*
+*secret*
+*.key
+*.pem
+
+# Node modules and build artifacts
+node_modules/
+.next/
+dist/
+build/
+
+# Logs
+*.log
+logs/
+
+# Temporary files
+.DS_Store
+*.tmp
+*.swp
+EOF
+```
+
+### Step 3: First Push
+
+```bash
+# Push your workspace to cloud
+nexus-cloud push -m "Initial sync"
+
+# This will:
+# 1. Encrypt all files locally
+# 2. Upload encrypted blobs to R2
+# 3. Create initial commit in Durable Object
+
+# Check status
+nexus-cloud status
+```
+
+### Verification
+
+```bash
+# Verify initialization
+ls ~/.nexus-cloud/ && echo "✅ Config exists"
+
+# Verify connection
+nexus-cloud status
+
+# Verify commit history
+nexus-cloud log
+```
+
+---
+
+## User Actions Required
+
+1. **Create Cloudflare account**: Sign up at cloudflare.com (free tier)
+2. **Authorize wrangler**: Click "Allow" in browser during `wrangler login`
+3. **Create master password**: Choose a STRONG password for encryption
+4. **Store master password**: Save in 1Password (CRITICAL for recovery)
+5. **Configure .nexusignore**: Review and customize excluded files
+
+---
+
+## Common Failure Points
+
+### Failure: "Not authenticated with Cloudflare"
+
+**Symptom**: `wrangler deploy` fails with authentication error
+
+**Cause**: Not logged in to Cloudflare
+
+**Recovery**:
+```bash
+# Login to Cloudflare
+wrangler login
+
+# Or use API token
+wrangler config set api_token YOUR_TOKEN
+
+# Verify
+wrangler whoami
+```
+
+**Prevention**: Complete authentication before deploying
+
+---
+
+### Failure: "R2 bucket not found"
+
+**Symptom**: Worker deploy fails, R2 bucket doesn't exist
+
+**Cause**: Forgot to create R2 bucket
+
+**Recovery**:
+```bash
+# Create bucket
+wrangler r2 bucket create nexus-blobs
+
+# Update wrangler.toml if using different bucket name
+# [[r2_buckets]]
+# binding = "BUCKET"
+# bucket_name = "nexus-blobs"
+
+# Re-deploy
+wrangler deploy
+```
+
+**Prevention**: Create R2 bucket before deploying worker
+
+---
+
+### Failure: "Master password lost"
+
+**Symptom**: Cannot decrypt workspace after reinstalling
+
+**Cause**: Master password not backed up
+
+**Recovery**:
+```bash
+# Unfortunately, if master password is lost, data is UNRECOVERABLE
+# This is by design - zero-knowledge encryption
+
+# Check 1Password for backup
+op item get "Nexus Cloud Master Password"
+
+# If truly lost, start fresh
+rm -rf ~/.nexus-cloud
+nexus-cloud init
+# Create NEW master password and back it up this time
+```
+
+**Prevention**: ALWAYS store master password in 1Password immediately after creating
+
+---
+
+### Failure: "Encryption key mismatch"
+
+**Symptom**: `nexus-cloud pull` fails with decryption error on new device
+
+**Cause**: Used different master password or wrong worker URL
+
+**Recovery**:
+```bash
+# Verify worker URL is correct
+cat ~/.nexus-cloud/config.json | grep worker_url
+
+# Try pull with correct master password
+nexus-cloud pull
+# Enter the EXACT master password used during init
+
+# If still fails, check worker URL matches deployed worker
+wrangler deployments list
+```
+
+**Prevention**: Store worker URL and master password together in 1Password
+
+---
+
+### Failure: "Quota exceeded" on R2
+
+**Symptom**: Push fails with storage quota error
+
+**Cause**: Free tier R2 limit reached (10GB)
+
+**Recovery**:
+```bash
+# Check storage usage
+wrangler r2 bucket list
+
+# Clean old commits (not yet implemented - manual cleanup needed)
+# For now: upgrade to paid plan or create new bucket
+
+# Or selectively push
+# Add more exclusions to .nexusignore
+echo "large-dir/" >> ~/nexus/home/.nexusignore
+```
+
+**Prevention**: Monitor R2 storage usage, exclude large files
+
+---
+
+### Failure: "Worker timeout"
+
+**Symptom**: Large workspace push/pull times out
+
+**Cause**: Cloudflare Worker has 30-second CPU time limit
+
+**Recovery**:
+```bash
+# Break up sync into smaller chunks
+# Push specific directories
+nexus-cloud push --path skills/ -m "Sync skills"
+nexus-cloud push --path projects/ -m "Sync projects"
+
+# Or increase worker timeout (requires paid plan)
+# Edit wrangler.toml:
+# [build]
+# timeout = 60
+```
+
+**Prevention**: Keep workspace size reasonable, use .nexusignore
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Install wrangler | ✅ Yes | bash | `npm install -g wrangler` |
+| Cloudflare login | 🟡 Partial | - | Requires browser OAuth |
+| Create R2 bucket | ✅ Yes | bash | `wrangler r2 bucket create` |
+| Deploy worker | ✅ Yes | bash | `wrangler deploy` |
+| Initialize locally | 🟡 Partial | - | Requires master password input |
+| Push workspace | ✅ Yes | bash | `nexus-cloud push` |
+| Pull workspace | ✅ Yes | bash | `nexus-cloud pull` |
+| Schedule backups | ✅ Yes | cron | Periodic `nexus-cloud push` |
+
+### Automation Script: Initial Setup
+
+```bash
+#!/bin/bash
+# Automate nexus-cloud setup (requires Cloudflare account)
+
+set -e
+
+echo "Installing wrangler..."
+npm install -g wrangler
+
+echo "⚠️  MANUAL STEP: Authenticate with Cloudflare"
+wrangler login
+# Wait for browser authentication
+
+echo "Verifying authentication..."
+wrangler whoami || { echo "❌ Authentication failed"; exit 1; }
+
+echo "Creating R2 bucket..."
+wrangler r2 bucket create nexus-blobs
+
+echo "Deploying worker..."
+cd ~/nexus/home/projects/nexus-cloud
+wrangler deploy
+
+echo "✅ Cloudflare setup complete!"
+echo ""
+echo "Next steps:"
+echo "1. Run: nexus-cloud init"
+echo "2. Enter worker URL: $(wrangler deployments list | head -1)"
+echo "3. Create and store master password in 1Password"
+echo "4. Run: nexus-cloud push -m 'Initial sync'"
+```
+
+### Scheduled Backup (Daily)
+
+```bash
+# Add to cron or use nexus cron skill
+# Push workspace backup daily at 2 AM
+0 2 * * * cd ~/nexus/home && nexus-cloud push -m "Daily backup $(date +%Y-%m-%d)"
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| First encrypted push | Entire workspace backed up, encrypted, can't be read by server | After initial setup |
+| Pull on new device | Full workspace restored with single command | Multi-device use case |
+| Version history | See commit log of workspace changes | After a few syncs |
+| Rollback workspace | Restore to previous state | When demonstrating safety |
+| Zero-knowledge proof | Show encrypted blob - complete gibberish | When discussing security |
+
+### Demo Script
+
+```
+Agent: "Let me show you how nexus-cloud provides secure workspace backup. First, I'll push your current workspace:"
+
+nexus-cloud push -m "Demo backup"
+
+Agent: "Your workspace is now backed up to Cloudflare R2. Here's what's important: all encryption happens on YOUR device. The server only sees encrypted blobs."
+
+# Show commit history
+nexus-cloud log
+
+Agent: "You can see the version history. Now let me show you the most powerful feature - pulling on a new device:"
+
+# Simulate new device
+Agent: "On a new machine, you'd just run:"
+# nexus-cloud init
+# nexus-cloud pull
+
+Agent: "Your entire workspace would be restored, decrypted locally using your master password. The server never had access to your plaintext data."
+
+# Show encrypted blob (if possible)
+Agent: "And here's what the server actually stores - complete gibberish without your password."
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **1password** | Store master password and worker URL | CRITICAL for recovery |
+| **cron** | Schedule automatic backups | Daily/hourly workspace sync |
+| **git** | Similar mental model | Both are version control systems |
+| **All skills** | Backs up entire workspace | Skills, configs, data all synced |
+
+---
+
+## Testing Checklist
+
+- [ ] wrangler installed: `wrangler --version`
+- [ ] Authenticated: `wrangler whoami`
+- [ ] R2 bucket created: `wrangler r2 bucket list | grep nexus-blobs`
+- [ ] Worker deployed: `wrangler deployments list`
+- [ ] Local init: `nexus-cloud init`
+- [ ] Master password stored in 1Password
+- [ ] .nexusignore configured
+- [ ] First push succeeds: `nexus-cloud push -m "Test"`
+- [ ] Status shows sync: `nexus-cloud status`
+- [ ] Log shows commits: `nexus-cloud log`
+- [ ] Pull works: `nexus-cloud pull` (test on different directory)
+- [ ] Encrypted blob verification (server stores gibberish)
+
+---
+
+## Notes for Onboarding Agent
+
+- **Complexity warning**: This is the hardest skill to set up (30-45 minutes)
+- **Prerequisites**: Requires Cloudflare account, wrangler, R2, Durable Objects
+- **Master password is CRITICAL**: Emphasize backing up to 1Password
+- **When to recommend**:
+  - User has multiple devices
+  - User wants secure backup
+  - User comfortable with command-line tools
+  - User has Cloudflare account or willing to create one
+- **When NOT to recommend**:
+  - User is uncomfortable with encryption concepts
+  - User doesn't need multi-device sync
+  - User prefers Git for version control
+  - Single-device user with local backups
+- **Cost considerations**: Cloudflare free tier includes:
+  - R2: 10GB storage free
+  - Workers: 100k requests/day free
+  - Durable Objects: 1M reads + 1M writes free
+  - Should be sufficient for most users
+- **Security selling point**: Zero-knowledge encryption - even Cloudflare can't read your data
+- **Alternative**: For simpler backup, suggest Git + private GitHub repo (less secure but easier)
+- **Time estimate breakdown**:
+  - Install wrangler: 2 minutes
+  - Cloudflare auth: 3 minutes
+  - R2 bucket: 2 minutes
+  - Deploy worker: 5 minutes
+  - Local init: 5 minutes
+  - First push: 10-15 minutes (depends on workspace size)
+  - Configuration: 5 minutes
+
+---
+
+## Architecture: How It Works
+
+### Data Flow
+
+```
+~/nexus/home (plaintext workspace)
+  ↓
+nexus-cloud push
+  ↓
+1. Read files (excluding .nexusignore)
+2. Encrypt each file with AES-256
+   - Content key: encrypts file contents
+   - Metadata key: encrypts filenames
+   - Version key: encrypts commit messages
+  ↓
+Encrypted blobs
+  ↓
+Upload to Cloudflare R2
+  ↓
+Commit metadata stored in Durable Object
+```
+
+### Pull Process
+
+```
+nexus-cloud pull
+  ↓
+Query Durable Object for latest commit
+  ↓
+Download encrypted blobs from R2
+  ↓
+Decrypt locally using master password
+  ↓
+Restore files to ~/nexus/home
+```
+
+### Zero-Knowledge Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│  Your Device                                    │
+│  ┌───────────────────────────────────────────┐ │
+│  │  Master Password (never leaves device)    │ │
+│  │    ↓                                      │ │
+│  │  Derive encryption keys (local only)     │ │
+│  │    ↓                                      │ │
+│  │  Encrypt workspace (local only)          │ │
+│  └───────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────┘
+         │
+         ↓ Upload encrypted blobs
+┌─────────────────────────────────────────────────┐
+│  Cloudflare (Server)                            │
+│  ┌───────────────────────────────────────────┐ │
+│  │  R2: Encrypted blobs (gibberish)         │ │
+│  │  Durable Object: Encrypted metadata      │ │
+│  │                                           │ │
+│  │  Server CANNOT decrypt without password  │ │
+│  └───────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## Security & Privacy
+
+### What's Encrypted
+
+| Data | Encrypted? | Key Used |
+|------|------------|----------|
+| File contents | ✅ Yes | Content key |
+| Filenames | ✅ Yes | Metadata key |
+| Directory structure | ✅ Yes | Metadata key |
+| Commit messages | ✅ Yes | Version key |
+| File sizes | ❌ No | - |
+| Storage totals | ❌ No | - |
+
+### Encryption Details
+
+- **Algorithm**: AES-256-GCM (Galois/Counter Mode)
+- **Key derivation**: PBKDF2 with 100,000 iterations
+- **Master password**: Never transmitted or stored on server
+- **Keys derived locally**: Content, metadata, version keys all derived from master password
+- **Zero-knowledge**: Server cannot decrypt without master password
+
+### Threat Model
+
+**Protected Against:**
+- Server compromise (Cloudflare breach)
+- Network eavesdropping (MITM attacks)
+- Unauthorized access to R2 bucket
+- Insider threats (Cloudflare employees)
+
+**NOT Protected Against:**
+- Master password compromise (user's responsibility)
+- Malware on local device
+- Physical device theft (if not encrypted at rest)
+- Keyloggers capturing master password
+
+### Best Practices
+
+1. **Strong master password**: Use 20+ character passphrase
+2. **Store in 1Password**: Back up master password securely
+3. **Device encryption**: Enable FileVault (macOS) or BitLocker (Windows)
+4. **Regular rotation**: Consider rotating master password periodically
+5. **Access control**: Limit who knows master password
+6. **Monitor access**: Review Cloudflare audit logs
+
+---
+
+## Recovery Scenarios
+
+### Scenario 1: Lost Device
+
+```bash
+# On new device:
+# 1. Install nexus and nexus-cloud
+# 2. Initialize with same worker URL and master password
+nexus-cloud init
+# Enter worker URL: https://nexus-cloud.your-account.workers.dev
+# Enter master password: [from 1Password]
+
+# 3. Pull workspace
+nexus-cloud pull
+
+# ✅ Workspace fully restored
+```
+
+### Scenario 2: Corrupted Local Workspace
+
+```bash
+# Rollback to previous commit
+nexus-cloud log
+# Find commit hash of good state
+
+nexus-cloud checkout <commit-hash>
+
+# Workspace restored to that point in time
+```
+
+### Scenario 3: Forgot Master Password
+
+```bash
+# Unfortunately, data is UNRECOVERABLE
+# This is by design - zero-knowledge encryption
+
+# Only option: Start fresh
+rm -rf ~/.nexus-cloud
+nexus-cloud init
+# Create NEW master password
+# Store in 1Password IMMEDIATELY
+
+# Previous backups are permanently inaccessible
+```
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*