docs: add Google Workspace CLI documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

productivity/CONTEXT.md

@@ -3,6 +3,12 @@
 ## Overview
 ADHD-optimized task management system designed to break the context-switching spiral. The system uses a persistent terminal dashboard with zero-friction brain dump capture to help maintain focus while capturing interrupting thoughts.
 
+## Google Workspace CLI (gws)
+Unified CLI for Drive, Gmail, Calendar, Sheets, and all Google Workspace APIs. Dynamically discovers API endpoints at runtime.
+- **Binary**: `/usr/local/bin/gws` | **Version**: 0.11.1
+- **gcloud SDK**: `/opt/google-cloud-sdk/`
+- **Docs**: [google-workspace-cli.md](google-workspace-cli.md)
+
 ## Handy - Speech to Text
 Desktop speech-to-text app with system tray integration. Installed via RPM from GitHub.
 - **Binary**: `/usr/bin/handy` | **Version**: 0.7.6

productivity/google-workspace-cli.md

@@ -0,0 +1,132 @@
+# Google Workspace CLI (gws)
+
+## Overview
+`gws` is a unified CLI for all Google Workspace APIs — Drive, Gmail, Calendar, Sheets, and more. It reads Google's Discovery Service at runtime and builds its command surface dynamically. Installed for use by Claude via Bash for querying and managing Google Workspace resources.
+
+- **Binary**: `/usr/local/bin/gws` | **Version**: 0.11.1
+- **Repo**: https://github.com/googleworkspace/cli
+- **Config dir**: `~/.config/gws/`
+- **Not an officially supported Google product**
+
+## Dependencies
+- **gcloud SDK**: `/opt/google-cloud-sdk/` (added to fish PATH via `config.fish`)
+- **Node.js 18+**: Required for npm install route
+
+## Authentication
+- OAuth scopes authenticated: `drive`, `gmail`, `calendar`, `sheets`
+- Google Cloud project: "Claude Home"
+- Credentials encrypted at rest (AES-256-GCM) via OS keyring
+- Cal added as test user on OAuth consent screen (required for unverified/testing apps)
+- Unverified apps limited to ~25 scopes — use `gws auth login -s service1,service2` to stay under limit
+
+### Re-authenticating or Adding Scopes
+```bash
+gws auth login -s drive,gmail,calendar,sheets,docs
+```
+
+## Usage
+
+### Command Structure
+```
+gws <service> <resource> [sub-resource] <method> [flags]
+```
+
+Subcommands are **space-separated** (not dot-notation):
+```bash
+gws sheets spreadsheets values get    # correct
+gws sheets spreadsheets.values get    # WRONG
+```
+
+### Common Commands
+
+#### Drive
+```bash
+# List files
+gws drive files list --params '{"pageSize": 10}'
+
+# Search files
+gws drive files list --params '{"q": "name contains \"keyword\""}'
+
+# Upload a file
+gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf
+```
+
+#### Sheets
+```bash
+# Read cells — use \u0021 for ! in double-quoted JSON (bash history expansion)
+gws sheets spreadsheets values get \
+  --params "{\"spreadsheetId\": \"SHEET_ID\", \"range\": \"SheetName\u0021A1:Z50\"}"
+
+# Or use single quotes (safe in fish, careful in bash)
+gws sheets spreadsheets values get \
+  --params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1:C10"}'
+
+# Append rows
+gws sheets spreadsheets values append \
+  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
+  --json '{"values": [["Name", "Score"], ["Alice", 95]]}'
+
+# List all tabs in a spreadsheet
+gws sheets spreadsheets get --params '{"spreadsheetId": "ID", "fields": "sheets.properties.title"}'
+```
+
+#### Gmail
+```bash
+# List unread messages
+gws gmail users messages list --params '{"userId": "me", "q": "is:unread"}'
+
+# Read a message
+gws gmail users messages get --params '{"userId": "me", "id": "MSG_ID"}'
+```
+
+#### Calendar
+```bash
+# List upcoming events
+gws calendar events list --params '{"calendarId": "primary", "maxResults": 5}'
+```
+
+### Flags Reference
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--params <JSON>` | URL/Query parameters | — |
+| `--json <JSON>` | Request body (POST/PATCH/PUT) | — |
+| `--upload <PATH>` | File to upload (multipart) | — |
+| `--output <PATH>` | Output file for binary responses | — |
+| `--format <FMT>` | Output: json, table, yaml, csv | json |
+| `--page-all` | Auto-paginate as NDJSON | off |
+| `--page-limit <N>` | Max pages with --page-all | 10 |
+| `--dry-run` | Preview request without executing | off |
+
+### Introspecting APIs
+```bash
+# See full schema for any method
+gws schema drive.files.list
+gws schema sheets.spreadsheets.values.get
+```
+
+## Known Gotchas
+- **Sheets `!` in ranges**: Bash history expansion mangles `!`. Use `\u0021` in double-quoted JSON, or single quotes
+- **Scope limit**: Unverified OAuth apps cap at ~25 scopes. Specify only needed services with `-s`
+- **No MCP server mode**: Use via Bash only — all output is structured JSON
+- **First run may be slow**: Discovery service data is fetched and cached (24-hour cache)
+
+## Key Spreadsheets
+| ID | Description |
+|----|-------------|
+| `1ctsjx41Muy5QXvVGvpT_8ovBc5HP_YLSJSqNRUOYidM` | SBA scorecard s13w12g04 (DEN vs WV) |
+| `1K7OBSrXY3NIXUaFLn4DZRI1_P7yv-5uaVSHLSEdx1VY` | Master Umpire Central |
+| `1QU5hTrNp8GuKi4FJ6AigPT54J0JtEzXzgR_6-dieWnQ` | Seaglass Data |
+
+## Troubleshooting
+
+### "gcloud CLI not found"
+gcloud isn't in PATH. In fish: `source ~/.config/fish/config.fish` or restart terminal.
+
+### "Access blocked" on login
+Add yourself as a test user in Google Cloud Console → APIs & Services → OAuth consent screen → Test users.
+
+### "Google hasn't verified this app" warning
+Expected for testing mode. Click "Continue" to proceed.
+
+### Too many scopes error
+Use `-s` flag to limit: `gws auth login -s drive,gmail,calendar,sheets`