@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/TROUBLESHOOTING.md

@@ -0,0 +1,363 @@
+# Common Failure Points & Recovery
+
+**Goal**: Document all the places onboarding can fail and how to recover, so we can either automate around them or guide users through them.
+
+---
+
+## Failure Categories
+
+1. **Permission Failures** - OS won't grant access
+2. **OAuth Failures** - Browser flow goes wrong
+3. **Rate Limiting** - External service blocks us
+4. **Installation Failures** - Tool won't install
+5. **Configuration Failures** - Setup is wrong
+6. **User Confusion** - Don't know what to do
+
+---
+
+## Permission Failures (macOS)
+
+### Full Disk Access Denied
+
+**Symptom**: eve returns empty results or permission error
+
+**Cause**: Terminal/Cursor doesn't have Full Disk Access
+
+**Recovery**:
+```
+1. System Settings → Privacy & Security → Full Disk Access
+2. Click + button
+3. Navigate to /Applications/Cursor.app (or Terminal.app)
+4. Grant access
+5. RESTART Cursor/Terminal (required!)
+```
+
+**Automation potential**: Can detect with `ls ~/Library/Messages/chat.db` - if permission denied, prompt user.
+
+### Automation Permission Denied
+
+**Symptom**: eve send fails with "not allowed to send Apple events"
+
+**Cause**: Automation permission not granted to Terminal/Cursor
+
+**Recovery**:
+```
+1. System Settings → Privacy & Security → Automation
+2. Find Terminal/Cursor
+3. Enable "System Events" and "Messages"
+```
+
+**Automation potential**: Can detect by attempting send and catching error.
+
+### Accessibility Permission Denied
+
+**Symptom**: Peekaboo/computer-use can't click or type
+
+**Cause**: Accessibility not granted
+
+**Recovery**:
+```
+1. System Settings → Privacy & Security → Accessibility
+2. Add Terminal/Cursor
+```
+
+---
+
+## OAuth Failures
+
+### Google: "Access blocked: This app's request is invalid"
+
+**Symptom**: OAuth flow shows error page
+
+**Cause**: credentials.json not configured or expired
+
+**Recovery**:
+```
+1. Go to console.cloud.google.com
+2. Navigate to APIs & Services → Credentials
+3. Create new OAuth 2.0 Client ID (Desktop app)
+4. Download JSON
+5. Save to ~/.config/gog/credentials.json
+```
+
+**Automation potential**: HIGH - computer-use could automate this entire flow.
+
+### Google: "Access denied" (403)
+
+**Symptom**: OAuth completes but API calls fail
+
+**Cause**: User not added as test user (app in testing mode)
+
+**Recovery**:
+```
+1. console.cloud.google.com → OAuth consent screen → Test users
+2. Add the email address
+3. Re-run gog auth add
+```
+
+**Automation potential**: HIGH - computer-use could add test users.
+
+### Google: "Token has been expired or revoked"
+
+**Symptom**: Was working, now fails
+
+**Cause**: Refresh token expired (happens if unused for 7 days in testing mode)
+
+**Recovery**:
+```bash
+gog auth remove user@gmail.com
+gog auth add user@gmail.com
+```
+
+### 1Password: "You are not signed in"
+
+**Symptom**: op commands fail
+
+**Cause**: CLI not authenticated OR integration not enabled
+
+**Recovery**:
+```
+1. Open 1Password app → Settings → Developer → Enable CLI integration
+2. Run: op signin
+3. If using Touch ID: op signin --account my.1password.com
+```
+
+---
+
+## Rate Limiting
+
+### Apple ID Creation: "This phone number cannot be used"
+
+**Symptom**: Can't verify Apple ID with phone number
+
+**Cause**: Apple aggressively rate-limits Apple ID creation. VoIP numbers (Google Voice, TextNow) are blocked.
+
+**Recovery options**:
+```
+1. Wait 24 hours and try again
+2. Try on an iPhone/iPad instead of web (less strict)
+3. Use a real mobile SIM card
+4. Use a family member's phone temporarily (just for verification)
+5. RECOMMENDED: Use Telegram instead (no phone needed for bot)
+```
+
+**Automation potential**: NONE - this is intentionally hard to automate.
+
+### GitHub: "API rate limit exceeded"
+
+**Symptom**: gh commands fail with rate limit error
+
+**Cause**: Too many unauthenticated requests
+
+**Recovery**:
+```bash
+gh auth login  # Authenticate to get higher limits
+```
+
+### WhatsApp: "This phone number cannot be used"
+
+**Symptom**: Can't register WhatsApp with Google Voice
+
+**Cause**: WhatsApp blocks VoIP/virtual numbers
+
+**Recovery**:
+```
+Use a real mobile SIM card (eSIM from carrier works)
+```
+
+---
+
+## Installation Failures
+
+### Homebrew: "No formulae or casks found"
+
+**Symptom**: brew install fails to find package
+
+**Cause**: Formula not in default taps
+
+**Recovery**:
+```bash
+# Add the tap first
+brew tap steipete/tap
+brew install steipete/tap/wacli
+
+# Or use full path
+brew install steipete/tap/bird
+```
+
+### Go: "go: command not found"
+
+**Symptom**: Can't install Go-based tools
+
+**Cause**: Go not installed
+
+**Recovery**:
+```bash
+brew install go
+# Then retry the go install command
+```
+
+### Node: "npm: command not found"
+
+**Symptom**: Can't run node-based skills
+
+**Cause**: Node.js not installed
+
+**Recovery**:
+```bash
+brew install node
+```
+
+---
+
+## Configuration Failures
+
+### gog: "credentials.json not found"
+
+**Symptom**: Can't start OAuth flow
+
+**Cause**: Google Cloud project not set up
+
+**Recovery**: See [gog setup guide](../../gog/docs/setup.md)
+
+**Automation potential**: HIGH - this is a prime candidate for computer-use automation.
+
+### eve: Returns empty results even with FDA
+
+**Symptom**: eve messages returns nothing
+
+**Cause**: Messages.app never opened (database doesn't exist)
+
+**Recovery**:
+```bash
+# Open Messages.app at least once
+open /System/Applications/Messages.app
+# Wait a few seconds for database to initialize
+# Then retry
+eve messages --limit 5
+```
+
+### nexus gateway: "Connection refused"
+
+**Symptom**: Can't connect to gateway
+
+**Cause**: Gateway not running
+
+**Recovery**:
+```bash
+nexus gateway start
+# Or check status
+nexus gateway status
+```
+
+---
+
+## User Confusion Points
+
+### "What should I do next?"
+
+**Cause**: Unclear progression path
+
+**Fix**: Always end with a clear next step or menu of options
+
+### "I clicked something and now I'm lost"
+
+**Cause**: OAuth flow went to wrong page
+
+**Fix**: Provide "if you see X, do Y" decision trees
+
+### "It's asking for my password"
+
+**Cause**: User worried about security
+
+**Fix**: Explain what's being stored, where, and that it's encrypted
+
+### "This is taking forever"
+
+**Cause**: Slow installation or indexing
+
+**Fix**: Show progress bars, explain what's happening
+
+### "I don't understand what this does"
+
+**Cause**: Technical jargon
+
+**Fix**: Use benefit-focused language:
+- ❌ "Configure OAuth credentials"
+- ✅ "Let me read your emails"
+
+---
+
+## Recovery Scripts
+
+### Full Reset (Start Over)
+
+```bash
+# Remove all nexus state
+rm -rf ~/nexus/state
+
+# Remove tool configs
+rm -rf ~/.config/gog
+rm -rf ~/.wacli
+
+# Start fresh
+# (nexus will recreate on next run)
+```
+
+### OAuth Reset (Google)
+
+```bash
+# Remove cached tokens
+gog auth remove --all
+
+# Start fresh
+gog auth add your@gmail.com
+```
+
+### 1Password Reset
+
+```bash
+# Sign out
+op signout --all
+
+# Sign back in
+op signin
+```
+
+---
+
+## Automation Opportunities
+
+| Failure Point | Automation Feasibility | Tool |
+|---------------|----------------------|------|
+| Full Disk Access prompt | LOW (requires manual click) | Guide only |
+| Google OAuth credentials setup | HIGH | computer-use |
+| Add test users to Google project | HIGH | computer-use |
+| 1Password CLI enable | LOW (requires manual click in app) | Guide only |
+| Install homebrew packages | HIGH | bash script |
+| Apple ID creation | NONE (intentionally blocked) | Guide only |
+| WhatsApp QR scan | LOW (requires phone) | Guide only |
+| Telegram bot creation | MEDIUM | Could automate BotFather flow |
+
+---
+
+## Prevention Strategies
+
+### Before Starting
+- Check prerequisites are installed (brew, node, go)
+- Verify macOS version compatibility
+- Check available disk space
+
+### During Setup
+- Validate each step before proceeding
+- Provide "undo" instructions for each step
+- Save state frequently so user can resume
+
+### After Completion
+- Run verification tests
+- Provide "health check" command
+- Schedule periodic re-validation
+
+---
+
+*Last updated: 2025-01-08*