@intent-systems/nexus 2026.1.5-3

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

@@ -0,0 +1,640 @@
+# Skill Deep-Dive: gog
+
+**Skill**: `gog`
+**Category**: Communication Data + Agent Reachability
+**Setup Difficulty**: 🔴 Very Hard
+**Time Estimate**: ~20-40 minutes (manual) or ~10 minutes (automated)
+**Platform**: Cross-platform (macOS, Windows, Linux)
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| Gmail access | Read, search, send emails; manage labels | `gog gmail search "is:unread" --max 10` |
+| Calendar access | Read, create, update events across all calendars | `gog calendar events --json` |
+| Drive access | List, search, download, upload files | `gog drive ls --max 5` |
+| Contacts access | Read and manage contacts | `gog contacts list --max 50` |
+| Sheets access | Read, write, append to spreadsheets | `gog sheets get <id> "A1:D10"` |
+| Docs/Slides access | Export documents and presentations | `gog docs export <id> --format txt` |
+| Tasks access | Manage Google Tasks | `gog tasks list <id>` |
+| People API | Access user profile information | `gog people me` |
+| Multi-account support | Manage multiple Google accounts simultaneously | `gog gmail search "test" --account user@gmail.com` |
+
+---
+
+## Dual-Purpose Usage
+
+### For User Data Access
+- Read user's Gmail, Calendar, Drive, etc.
+- Power unified comms layer (aggregates with eve, wacli)
+- Enable agent to understand user's communication context
+
+### For Agent Identity
+- Give agent its own Gmail address for sending/receiving
+- Agent can manage its own calendar
+- Agent can store files in its own Drive
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] `1password` skill — For storing OAuth tokens securely and portably
+- [ ] `brew` or equivalent package manager — For installing gog CLI
+- [ ] `Google Cloud account` — For creating OAuth credentials
+- [ ] `Google account(s)` — The accounts to connect (user's personal/work)
+
+### Soft Dependencies (Recommended)
+- [ ] `computer-use` skill — For automating OAuth consent flow
+- [ ] `uv` and Python 3.11+ — For browser automation scripts
+- [ ] Chrome browser — For CDP (Chrome DevTools Protocol) automation
+
+### This Skill Enables
+- [ ] `comms` — Provides Gmail data to unified communication layer
+- [ ] Agent email identity — Agent can send/receive emails
+- [ ] Morning briefings — Pull calendar events for daily summaries
+- [ ] Contact search — Find people across Google Workspace
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check if brew is installed
+which brew || echo "❌ Need to install Homebrew first"
+
+# Check if 1Password CLI is ready
+op whoami || echo "❌ Need to setup 1password skill first"
+
+# Check if you have a Google account
+echo "✓ You need at least one Google account (gmail.com or Workspace)"
+```
+
+### Installation Steps
+
+```bash
+# Step 1: Install gog CLI
+brew install steipete/tap/gogcli
+
+# Step 2: Verify installation
+gog --version
+# Expected output: e.g., "gog version 1.x.x"
+```
+
+### Verification
+
+```bash
+# Check gog is accessible
+gog --version
+
+# Check if credentials.json exists (empty if not setup yet)
+ls -la ~/.config/gog/credentials.json 2>/dev/null || echo "No credentials yet"
+```
+
+---
+
+## Configuration
+
+### Phase 1: OAuth Client Setup (credentials.json)
+
+This is the MOST COMPLEX part. You have 2 options:
+
+#### Option A: Browser Automation (Recommended - Fastest)
+
+Prerequisites:
+```bash
+# Install uv if not already installed
+brew install uv
+
+# Setup Python environment (one-time)
+mkdir -p ~/nexus/state/browser/cdp
+cd ~/nexus/state/browser/cdp
+uv venv --python 3.11
+source .venv/bin/activate
+uv pip install playwright==1.57.0
+python -m playwright install chromium
+```
+
+Run automation:
+```bash
+# Navigate to gog scripts
+cd ~/nexus/skills/gog/scripts/cdp
+
+# Launch CDP Chrome (uses your existing Chrome login)
+bash launch_cdp_chrome.sh
+
+# Verify CDP is running
+curl -s http://127.0.0.1:9222/json/version
+
+# Create OAuth client automatically (requires GCP_PROJECT_ID)
+python create_oauth_client.py
+```
+
+This creates `~/.config/gog/credentials.json` automatically.
+
+#### Option B: Manual Setup (More Control)
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com)
+2. Create a new project:
+   - Click "Select a project" dropdown → "New Project"
+   - Name it (e.g., "Nexus gog CLI")
+   - Click "Create"
+3. Enable required APIs:
+   - Go to "APIs & Services" → "Library"
+   - Search and enable: Gmail API, Google Calendar API, Google Drive API, Google People API, Google Sheets API, Google Tasks API
+4. Create OAuth consent screen:
+   - Go to "APIs & Services" → "OAuth consent screen"
+   - Choose "External" (unless you have Workspace)
+   - Fill in app name: "gog CLI"
+   - Add your email as support email
+   - Add scopes (or skip - gog will request scopes dynamically)
+   - **CRITICAL**: Set Publishing status to "Testing" (NOT Production)
+5. Create OAuth credentials:
+   - Go to "APIs & Services" → "Credentials"
+   - Click "Create Credentials" → "OAuth client ID"
+   - Application type: "Desktop app"
+   - Name: "gog CLI"
+   - Click "Create"
+   - Click "Download JSON" (downloads `client_secret_xxx.json`)
+6. Install credentials:
+   ```bash
+   gog auth credentials ~/Downloads/client_secret_xxx.json
+   ```
+
+### Phase 2: Add Test Users (CRITICAL STEP)
+
+If you skipped this, you'll get "access_denied" errors.
+
+#### Manual Method:
+1. Go to [Google Auth Platform → Audience](https://console.cloud.google.com/auth/audience)
+2. Under "Test users" section, click "Add users"
+3. Add your email address(es) - one per line
+4. Press Enter after each email
+5. Click "Save"
+
+#### Automated Method:
+```bash
+cd ~/nexus/skills/gog/scripts/cdp
+python add_test_users.py \
+  --project "$GCP_PROJECT_ID" \
+  --emails you@gmail.com work@company.com
+```
+
+### Phase 3: Authorize Accounts
+
+#### Manual Method (for each account):
+```bash
+# Authorize account with all services
+gog auth add you@gmail.com --services gmail,calendar,drive,contacts,sheets,people,tasks
+
+# Browser opens automatically → Follow OAuth consent flow:
+# 1. "Choose an account" → select your account
+# 2. "Google hasn't verified this app" → Click "Advanced" → "Go to gog-cli (unsafe)"
+# 3. Review permissions list → Click "Allow"
+
+# IMMEDIATELY export token to 1Password for portability
+gog auth tokens export you@gmail.com --out /tmp/gog-token.json
+op document create /tmp/gog-token.json --title "gog-you@gmail.com" --vault Personal
+rm /tmp/gog-token.json
+```
+
+#### Automated Method (for multiple accounts):
+```bash
+cd ~/nexus/skills/gog/scripts/cdp
+
+# Ensure CDP Chrome is still running
+curl -s http://127.0.0.1:9222/json/version
+
+# Authorize all accounts at once
+python auth_add_accounts.py \
+  --emails you@gmail.com work@company.com other@gmail.com
+```
+
+### Phase 4: Verification
+
+```bash
+# List all authorized accounts
+gog auth list
+
+# Test each account
+gog gmail labels list --account you@gmail.com
+gog calendar calendars --account you@gmail.com
+gog drive ls --account you@gmail.com
+
+# Set a default account (optional)
+export GOG_ACCOUNT=you@gmail.com
+```
+
+---
+
+## User Actions Required
+
+List any manual steps the user MUST perform (can't be automated):
+
+1. **Create Google Cloud account** (if they don't have one)
+2. **Create OAuth consent screen** (manual web form)
+3. **Add themselves as test users** (if manual setup)
+4. **Click "Allow" in OAuth consent flow** (unless using browser automation)
+5. **Keep credentials.json safe** (should be backed up to 1Password)
+
+---
+
+## Common Failure Points
+
+### Failure: "The developer hasn't given you access to this app" (access_denied)
+
+**Symptom**: OAuth consent screen shows: "access_denied" or "The developer hasn't given you access to this app"
+
+**Cause**: Email address not added as a test user in Google Cloud Console
+
+**Recovery**:
+```bash
+# Option 1: Manual (via web console)
+# 1. Go to https://console.cloud.google.com/auth/audience
+# 2. Under "Test users", click "Add users"
+# 3. Add your email, press Enter, click Save
+# 4. Wait 1-2 minutes for propagation
+# 5. Re-run: gog auth add you@gmail.com --services gmail,calendar,drive,contacts,sheets,people,tasks
+
+# Option 2: Automated (if CDP setup exists)
+cd ~/nexus/skills/gog/scripts/cdp
+python add_test_users.py --project "$GCP_PROJECT_ID" --emails you@gmail.com
+```
+
+**Prevention**: Always add test users immediately after creating OAuth consent screen
+
+---
+
+### Failure: APIs not enabled
+
+**Symptom**: Errors like "Gmail API has not been used in project XXX" or "accessNotConfigured"
+
+**Cause**: Required Google APIs not enabled for the project
+
+**Recovery**:
+```bash
+# Manual: Go to Google Cloud Console → APIs & Services → Library
+# Search for and enable:
+# - Gmail API
+# - Google Calendar API
+# - Google Drive API
+# - Google People API
+# - Google Sheets API
+# - Google Tasks API
+
+# Or use gcloud CLI (if installed):
+gcloud services enable gmail.googleapis.com
+gcloud services enable calendar-json.googleapis.com
+gcloud services enable drive.googleapis.com
+gcloud services enable people.googleapis.com
+gcloud services enable sheets.googleapis.com
+gcloud services enable tasks.googleapis.com
+```
+
+**Prevention**: Enable all APIs during initial OAuth setup
+
+---
+
+### Failure: Tokens not portable between machines
+
+**Symptom**: gog works on one machine but not another; need to re-auth
+
+**Cause**: Tokens stored in macOS Keychain (not synced) or not exported to 1Password
+
+**Recovery**:
+```bash
+# On OLD machine: Export tokens
+gog auth tokens export you@gmail.com --out /tmp/gog-token.json
+op document create /tmp/gog-token.json --title "gog-you@gmail.com" --vault Personal
+rm /tmp/gog-token.json
+
+# On NEW machine: Import tokens
+# 1. Install gog: brew install steipete/tap/gogcli
+# 2. Copy credentials.json (same one works everywhere)
+cp ~/.config/gog/credentials.json /path/to/backup/
+# Or download from 1Password if stored there
+
+# 3. Import token
+op document get "gog-you@gmail.com" --out-file /tmp/gog-token.json
+gog auth tokens import /tmp/gog-token.json
+rm /tmp/gog-token.json
+
+# 4. Verify
+gog auth list
+```
+
+**Prevention**: ALWAYS export tokens to 1Password immediately after auth
+
+---
+
+### Failure: Workspace account requires admin approval
+
+**Symptom**: OAuth consent shows "Admin approval required" for Google Workspace accounts
+
+**Cause**: Organization policy requires admin to approve third-party apps
+
+**Recovery**:
+```bash
+# Option 1: Ask IT admin to approve the app
+# Option 2: Use personal Gmail account instead
+# Option 3: Admin can pre-approve via Workspace Admin Console
+
+# For personal projects, avoid Workspace accounts for gog
+```
+
+**Prevention**: Check if target account is Workspace account; use personal Gmail if possible
+
+---
+
+### Failure: CDP Chrome automation fails
+
+**Symptom**: Browser automation scripts error out or hang
+
+**Cause**: CDP port not open, Chrome not running, or profile issues
+
+**Recovery**:
+```bash
+# Check if CDP Chrome is running
+curl -s http://127.0.0.1:9222/json/version
+
+# If not running, kill any existing Chrome and restart
+pkill -9 "Google Chrome"
+cd ~/nexus/skills/gog/scripts/cdp
+bash launch_cdp_chrome.sh
+
+# Verify again
+curl -s http://127.0.0.1:9222/json/version
+
+# Re-run automation script
+python auth_add_accounts.py --emails you@gmail.com
+```
+
+**Prevention**: Verify CDP Chrome is running before running automation scripts
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Install gog CLI | ✅ Yes | bash | `brew install steipete/tap/gogcli` |
+| Create GCP project | 🟡 Partial | computer-use | Requires web form interaction |
+| Enable APIs | 🟡 Partial | gcloud CLI | If user has gcloud installed |
+| Create OAuth client | ✅ Yes | CDP scripts | `create_oauth_client.py` |
+| Add test users | ✅ Yes | CDP scripts | `add_test_users.py` |
+| OAuth consent flow | ✅ Yes | CDP scripts | `auth_add_accounts.py` |
+| Export to 1Password | ✅ Yes | bash | `gog auth tokens export` + `op document create` |
+| Import from 1Password | ✅ Yes | bash | `op document get` + `gog auth tokens import` |
+
+### Full Automation Script
+
+```bash
+#!/bin/bash
+# Full gog setup automation (requires CDP environment setup)
+
+set -e
+
+# Prerequisite checks
+command -v gog >/dev/null || { echo "❌ gog not installed"; exit 1; }
+command -v op >/dev/null || { echo "❌ 1Password CLI not installed"; exit 1; }
+op whoami >/dev/null || { echo "❌ Not signed in to 1Password"; exit 1; }
+
+# Configuration
+GCP_PROJECT_ID="${GCP_PROJECT_ID:-nexus-gog-cli}"
+EMAILS="${1:-$(whoami)@gmail.com}"  # Pass as argument or default
+
+echo "Setting up gog for: $EMAILS"
+
+# Setup CDP environment (one-time)
+mkdir -p ~/nexus/state/browser/cdp
+cd ~/nexus/state/browser/cdp
+if [ ! -d ".venv" ]; then
+    uv venv --python 3.11
+    source .venv/bin/activate
+    uv pip install playwright==1.57.0
+    python -m playwright install chromium
+else
+    source .venv/bin/activate
+fi
+
+# Launch CDP Chrome
+cd ~/nexus/skills/gog/scripts/cdp
+bash launch_cdp_chrome.sh &
+sleep 5
+
+# Verify CDP
+curl -s http://127.0.0.1:9222/json/version >/dev/null || { echo "❌ CDP Chrome not running"; exit 1; }
+
+# Create OAuth client (if needed)
+if [ ! -f ~/.config/gog/credentials.json ]; then
+    python create_oauth_client.py
+fi
+
+# Add test users
+python add_test_users.py --project "$GCP_PROJECT_ID" --emails "$EMAILS"
+
+# Authorize accounts
+python auth_add_accounts.py --emails "$EMAILS"
+
+# Export tokens to 1Password
+for email in $(echo "$EMAILS" | tr ',' ' '); do
+    gog auth tokens export "$email" --out "/tmp/gog-${email}.json"
+    op document create "/tmp/gog-${email}.json" --title "gog-${email}" --vault Personal
+    rm "/tmp/gog-${email}.json"
+    echo "✅ Exported $email to 1Password"
+done
+
+# Verify
+echo "✅ Setup complete!"
+gog auth list
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| Read user's unread emails | Search and display unread emails with sender, subject, snippet | Right after first successful auth |
+| Access calendar events | Show today's calendar events across all calendars | Morning briefing use case |
+| Search across Drive | Find files by keyword, show how fast it is | After Drive auth |
+| Multi-account switching | Show seamless switching between personal and work accounts | When user mentions multiple accounts |
+| Agent sends email | Agent uses its own Gmail to send a message | Agent identity demo |
+
+### Demo Script
+
+```
+Agent: "Let me show you what gog enables. I can now read your unread emails directly from Gmail."
+
+gog gmail search "is:unread" --max 5 --json | jq -r '.[] | "\(.from): \(.subject)"'
+
+Agent: "I can also check your calendar for today:"
+
+gog calendar events --json | jq -r '.[] | select(.start.dateTime) | "\(.start.dateTime | split("T")[1] | split("-")[0]): \(.summary)"'
+
+Agent: "And search your Drive:"
+
+gog drive search "budget" --max 3 --plain
+
+Agent: "All of this data now flows into the unified comms system, so I can help you find information across Gmail, Calendar, and Drive in one query."
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **1password** | Stores OAuth tokens for portability | CRITICAL: Export tokens immediately after auth |
+| **comms** | Provides Gmail data to unified layer | One of three primary data sources (eve, gog, wacli) |
+| **computer-use** | Automates OAuth consent flow | CDP scripts use browser automation |
+| **cron** | Schedule periodic Gmail/Calendar sync | E.g., morning briefing pulls calendar events |
+| **qmd** | Email content can be indexed for search | Semantic search across email history |
+
+---
+
+## Testing Checklist
+
+- [ ] Fresh install works: `brew install steipete/tap/gogcli`
+- [ ] Version check: `gog --version`
+- [ ] credentials.json created (manual or automated)
+- [ ] Test users added to OAuth consent screen
+- [ ] First account auth works: `gog auth add you@gmail.com`
+- [ ] OAuth consent flow completes (manual or automated)
+- [ ] Token exported to 1Password
+- [ ] Gmail works: `gog gmail labels list --account you@gmail.com`
+- [ ] Calendar works: `gog calendar calendars --account you@gmail.com`
+- [ ] Drive works: `gog drive ls --account you@gmail.com`
+- [ ] Multi-account works (if multiple accounts)
+- [ ] Token import works on new machine (simulate portability)
+- [ ] Failure recovery: Remove account, re-add, export again
+
+---
+
+## Notes for Onboarding Agent
+
+- **WARN USERS UPFRONT**: This is the most complex skill setup. Set expectations.
+- **Recommend automation**: If user is technical, strongly recommend CDP automation route
+- **1Password first**: ALWAYS ensure 1password skill is setup before starting gog
+- **Test users are critical**: Emphasize adding test users to avoid "access_denied" errors
+- **Export immediately**: After EVERY auth, export token to 1Password
+- **Multi-account strategy**: Ask if user wants personal + work, setup both at once
+- **When NOT to recommend**:
+  - User doesn't have Google account (rare)
+  - User is not comfortable with OAuth security (explain it's standard practice)
+  - User's organization blocks third-party apps (check Workspace policies)
+- **Agent identity use case**: Mention that agent can have its own Gmail for sending/receiving
+- **Time estimate**:
+  - Automated: ~10 minutes
+  - Manual: ~20-40 minutes (first time)
+  - With issues: could be 1+ hours (test user errors, API enabling, etc.)
+
+---
+
+## Dual-Purpose Setup Details
+
+### For User Data Access
+```bash
+# Setup user's personal Gmail
+gog auth add user@gmail.com --services gmail,calendar,drive,contacts,sheets,people,tasks
+
+# Export to 1Password
+gog auth tokens export user@gmail.com --out /tmp/gog-user.json
+op document create /tmp/gog-user.json --title "gog-user@gmail.com" --vault Personal
+rm /tmp/gog-user.json
+
+# Use for comms integration
+export GOG_ACCOUNT=user@gmail.com
+gog gmail search "is:unread"
+```
+
+### For Agent Identity
+```bash
+# Create a new Gmail account for the agent (e.g., agent@example.com)
+# Then authorize it
+gog auth add agent@example.com --services gmail,calendar,drive
+
+# Export to 1Password
+gog auth tokens export agent@example.com --out /tmp/gog-agent.json
+op document create /tmp/gog-agent.json --title "gog-agent@example.com" --vault Personal
+rm /tmp/gog-agent.json
+
+# Agent can now send emails
+gog gmail send --account agent@example.com --to user@gmail.com --subject "Test" --body "Hi from agent"
+```
+
+**NOTE**: Agent identity requires a separate Gmail account. This is typically:
+- A new free Gmail account created specifically for the agent
+- OR a Google Workspace account provisioned by the user's organization
+
+---
+
+## Portability Pattern
+
+The key to gog portability is **1Password as source of truth**:
+
+1. **After auth on Machine A**:
+   ```bash
+   gog auth tokens export you@gmail.com --out /tmp/gog-token.json
+   op document create /tmp/gog-token.json --title "gog-you@gmail.com" --vault Personal
+   rm /tmp/gog-token.json
+   ```
+
+2. **On Machine B** (or after OS reinstall):
+   ```bash
+   brew install steipete/tap/gogcli
+   # Copy credentials.json (same one works everywhere)
+   op document get "gog-credentials.json" --out-file ~/.config/gog/credentials.json
+   # Import token
+   op document get "gog-you@gmail.com" --out-file /tmp/gog-token.json
+   gog auth tokens import /tmp/gog-token.json
+   rm /tmp/gog-token.json
+   # Verify
+   gog auth list
+   ```
+
+3. **Bulk export all accounts**:
+   ```bash
+   for email in $(gog auth list --plain | cut -f1); do
+     gog auth tokens export "$email" --out "/tmp/gog-${email}.json"
+     op document create "/tmp/gog-${email}.json" --title "gog-${email}" --vault Personal
+     rm "/tmp/gog-${email}.json"
+   done
+   ```
+
+---
+
+## Security Considerations
+
+- **credentials.json is NOT a secret**: It's just OAuth client config, safe to share/backup
+- **Refresh tokens ARE secrets**: Must be stored securely (1Password, encrypted)
+- **Tokens in keychain**: macOS Keychain is secure but not portable
+- **1Password pattern**: Encrypted, portable, scriptable - best of all worlds
+- **OAuth scopes**: Only request scopes you need; gog defaults are reasonable
+- **Token expiration**: Refresh tokens rarely expire (can last years), but if they do, just re-auth
+
+---
+
+## Google Cloud Console Quick Links
+
+- [Cloud Console Home](https://console.cloud.google.com)
+- [OAuth Consent Screen](https://console.cloud.google.com/apis/credentials/consent)
+- [OAuth Test Users](https://console.cloud.google.com/auth/audience)
+- [Credentials](https://console.cloud.google.com/apis/credentials)
+- [API Library](https://console.cloud.google.com/apis/library)
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*