docs: agent-first README rewrite, stale docs cleanup

- README.md rewritten: relay auth as default (no GCP needed), agent-first
  quick start, all 18+ services, DOCX editing, safety flags, skills/plugin
  auto-installed by install.sh, gog companion mentioned
- INSTALL.md rewritten: relay auth default, BYO GCP as optional advanced,
  removed OpenClaw/build-internal/build-automagik/baked-in references
- docs/auth.md restructured: relay auth opens the doc, BYO GCP moved to
  advanced section
- docs/headless-auth.md: fix broken link to deleted infrastructure.md
- Deleted stale internal docs: deployment.md, infrastructure.md
- Deleted orphaned skills/workit/ (canonical is plugins/workit/skills/)

Author: automagik-genie

INSTALL.md

@@ -1,6 +1,8 @@
 # workit — Installation Guide
 
-> Give your OpenClaw agent full access to Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, Contacts, Tasks, and more) via CLI.
+> Give your agent full access to Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, Contacts, Tasks, and more) via CLI.
+
+---
 
 ## 1. Quick Install (Recommended)
 
@@ -47,172 +49,126 @@ wk update
 
 ---
 
-## 2. Configure Credentials
-
-**Option A: Pre-built binary (recommended for internal use)**
-
-If the binary was built with `make build-internal`, it already has OAuth credentials baked in. Skip to step 3.
+## 2. What Gets Installed
 
-**Option B: Environment variables**
-
-```bash
-export WK_CLIENT_ID="your-client-id"
-export WK_CLIENT_SECRET="your-client-secret"
-export WK_CALLBACK_SERVER="https://auth.example.com"
-```
+The installer places the following on your system:
 
-**Option C: Credentials file (standard workit way)**
+| Path | Description |
+|------|-------------|
+| `~/.local/bin/wk` | The `wk` CLI binary |
+| `~/.local/bin/gog` | The `gog` companion binary |
+| `~/.workit/plugin/` | Plugin directory containing 28 skills |
+| `~/.claude/plugins/workit` | Symlink registering the plugin with Claude Code |
 
-```bash
-wk auth credentials ~/path/to/client_secret.json
-```
+The Claude Code symlink means Claude Code automatically picks up the `wk` skills — no manual configuration required.
 
 ---
 
-## 3. Authenticate a Google Account
+## 3. Authentication
 
-### For agents (headless — no browser needed):
+Authentication uses the **Automagik relay** at `auth.automagik.dev`. No GCP project setup is needed by default.
 
-```bash
-# Start headless auth flow
-wk auth add you@gmail.com --headless --services=user
-
-# Output:
-#   Visit this URL to authorize:
-#   https://accounts.google.com/o/oauth2/v2/auth?...
-#   Waiting for authorization...
-```
-
-The agent sends this URL to the user (via WhatsApp, Telegram, etc). User taps the link on their phone, logs in, and the CLI automatically picks up the token.
-
-### For interactive use (has browser):
+### Interactive (default)
 
 ```bash
-wk auth add you@gmail.com --services=user
-# Opens browser, complete login, done.
+wk auth manage
 ```
 
----
-
-## 4. Set Up Keyring (Headless Environments)
+This opens a browser-based flow. Log in with your Google account and the token is stored locally.
 
-On servers without a desktop keychain:
+### Headless (agents and servers without a browser)
 
 ```bash
-# Use file-based keyring
-wk auth keyring file
-
-# Set password via env (for non-interactive use)
-export WK_KEYRING_PASSWORD="your-secure-password"
+wk auth add user@example.com --headless --no-input
 ```
 
----
+The command prints an authorization URL. Send that URL to the user (via chat, email, etc.). When they complete the login in their browser, the CLI automatically receives the token.
 
-## 5. Verify It Works
+### Check Auth Status
 
 ```bash
-# Check auth status
-wk auth list --check
+# Show auth state for all accounts
+wk auth status
 
-# Test some commands
-wk gmail labels list --account you@gmail.com
-wk drive list --account you@gmail.com
-wk calendar events list --account you@gmail.com
+# List authenticated accounts
+wk auth list
 ```
 
 ---
 
-## 6. Add to OpenClaw Config
+## 4. Advanced: BYO GCP Credentials (Optional)
 
-Add `wk` to your agent's workspace. In your agent's `TOOLS.md`:
+> This section is for users who want to use their own Google Cloud OAuth client instead of the Automagik relay. Most users do not need this.
 
-```markdown
-## Google Workspace (workit)
+### Steps
 
-Access Gmail, Calendar, Drive, Docs, Sheets, Contacts, Tasks via `wk` CLI.
+1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create an OAuth 2.0 client ID (Desktop app type).
+2. Download the `client_secret_*.json` file.
+3. Register it with `wk`:
 
-### Auth
-- `wk auth list --check` — Check authenticated accounts
-- `wk auth add EMAIL --headless --services=user` — Auth a new account (sends URL for mobile login)
-- `wk auth status` — Show current auth state
+```bash
+wk auth credentials ~/path/to/client_secret.json
+```
 
-### Gmail
-- `wk gmail search "newer_than:1d" --account EMAIL` — Search recent emails
-- `wk gmail send --to X --subject Y --body Z --account EMAIL` — Send email
-- `wk gmail labels list --account EMAIL` — List labels
+For environments with multiple OAuth clients:
 
-### Calendar
-- `wk calendar events list --account EMAIL` — List upcoming events
-- `wk calendar events create --title "Meeting" --start "2025-01-15T10:00" --account EMAIL`
+```bash
+# Register and name a specific client
+wk auth credentials ~/path/to/client_secret.json --name my-project
 
-### Drive
-- `wk drive list --account EMAIL` — List files
-- `wk drive upload FILE --account EMAIL` — Upload a file
-- `wk drive download FILE_ID --account EMAIL` — Download a file
-- `wk drive search "name contains 'report'" --account EMAIL`
+# List registered credential sets
+wk auth credentials list
 
-### Drive Sync (bidirectional)
-- `wk sync init ~/drive-folder --drive-folder "My Folder" --account EMAIL`
-- `wk sync start ~/drive-folder --daemon --account EMAIL`
-- `wk sync status`
-- `wk sync stop`
+# Select which credential set to use
+wk auth credentials use my-project
+```
 
-### Docs & Sheets
-- `wk docs export DOC_ID --format pdf --account EMAIL`
-- `wk sheets read SHEET_ID --range "A1:D10" --account EMAIL`
-- `wk sheets write SHEET_ID --range "A1" --values '["hello","world"]' --account EMAIL`
+After registering credentials, run `wk auth manage` or `wk auth add` as normal.
 
-### Contacts & Tasks
-- `wk contacts search "John" --account EMAIL`
-- `wk tasks list --account EMAIL`
-- `wk tasks add "Buy milk" --account EMAIL`
+---
 
-### Tips
-- Add `--json` to any command for machine-parseable output
-- Use `--account EMAIL` or set `WK_ACCOUNT=EMAIL` globally
-- Multiple accounts supported: `wk auth add second@gmail.com`
-```
+## 5. Keyring Configuration
 
----
+`wk` stores tokens in the system keyring. The default backend is chosen automatically:
+
+| Platform | Default Backend |
+|----------|----------------|
+| macOS | macOS Keychain |
+| Linux (desktop) | GNOME Keyring |
+| Windows | Windows Credential Manager |
+| Linux (headless) | File backend (see below) |
 
-## 7. Drive Sync Setup (optional)
+### File Backend (Headless / Server Environments)
 
-To sync a Google Drive folder to a local directory:
+On servers without a desktop keyring, use the file backend:
 
 ```bash
-# Initialize sync for a folder
-wk sync init ~/my-drive --drive-folder "Work Documents" --account you@gmail.com
+export WK_KEYRING_BACKEND=file
+export WK_KEYRING_PASSWORD="your-secure-passphrase"
+```
 
-# Start sync daemon (runs in background)
-wk sync start ~/my-drive --daemon --account you@gmail.com
+Add these to your shell profile or systemd environment to persist across sessions.
 
-# Check status
-wk sync status
+### Service Account
 
-# Stop sync
-wk sync stop
+For server-to-server automation without interactive login:
 
-# Add more folders
-wk sync init ~/another-folder --drive-folder "Photos" --account you@gmail.com
-wk sync start ~/another-folder --daemon --account you@gmail.com
+```bash
+wk auth service-account set --key /path/to/key.json impersonate@company.com
 ```
 
-Changes sync bidirectionally:
-- Save a local file → uploaded to Drive within seconds
-- Edit on Drive web → downloaded locally within 5 seconds
-
 ---
 
-## 8. Build from Source (Developer / Contributor)
+## 6. Build from Source (Developer / Contributor)
 
-If you want to contribute to workit or build a custom binary, you need Go 1.21+ and the repo cloned locally.
+If you want to contribute to workit or build a custom binary, you need Go 1.21+ and GNU Make.
 
 ### Requirements
 
 - Go 1.21 or newer — [go.dev/doc/install](https://go.dev/doc/install)
 - GNU Make
 
-### Quick Build
+### Steps
 
 ```bash
 git clone https://github.com/automagik-dev/workit.git
@@ -225,66 +181,37 @@ make build
 
 | Target | Description |
 |--------|-------------|
-| `make build` | Build binary to `bin/wk` (community build, no baked-in credentials) |
-| `make build-automagik` | Build with Automagik OAuth credentials (requires internal secrets) |
-| `make build-internal` | Build with internal-use baked-in credentials |
-| `make tools` | Install dev tools (`gofumpt`, `goimports`, `golangci-lint`) to `.tools/` |
+| `make build` | Build binary to `bin/wk` |
 | `make test` | Run test suite |
 | `make lint` | Run linter |
 | `make install` | Install `bin/wk` to `~/.local/bin` |
 
-### Developer Credential Setup
-
-When building from source you need to supply your own OAuth credentials:
-
-```bash
-# Option A: Environment variables
-export WK_CLIENT_ID="your-client-id"
-export WK_CLIENT_SECRET="your-client-secret"
-export WK_CALLBACK_SERVER="https://auth.example.com"
-
-# Option B: Credentials file
-mkdir -p ~/.config/workit && chmod 700 ~/.config/workit
-cat > ~/.config/workit/credentials.env << 'CRED'
-WK_CLIENT_ID=your-client-id
-WK_CLIENT_SECRET=your-client-secret
-WK_CALLBACK_SERVER=https://your-callback-server.example.com
-CRED
-```
-
-Then build and install:
-
-```bash
-make build
-make install   # copies bin/wk to ~/.local/bin
-```
-
-After building, proceed with [Configure Credentials](#2-configure-credentials) above.
+After building from source, authenticate using `wk auth manage` or the headless flow described in [Authentication](#3-authentication).
 
 ---
 
 ## TL;DR for Agents
 
+Copy-paste block to get up and running immediately. Uses relay auth — no GCP setup or credential env vars needed.
+
 ```bash
 # Install
 curl -sSL https://raw.githubusercontent.com/automagik-dev/workit/main/install.sh | sh
 
-# Update
-wk update
+# Ensure wk is on PATH (add to shell profile if needed)
+export PATH="$HOME/.local/bin:$PATH"
 
-# Configure (if not using pre-built binary)
-export WK_CLIENT_ID="xxx"
-export WK_CLIENT_SECRET="xxx"
-export WK_CALLBACK_SERVER="https://auth.example.com"
-export WK_KEYRING_BACKEND=file
-export WK_KEYRING_PASSWORD="secure-password"
+# Check auth status
+wk auth status
+
+# Authenticate interactively (opens browser)
+wk auth manage
 
-# Auth
-wk auth add user@gmail.com --headless --services=user
-# → Send the URL to user → they login → done
+# Authenticate headlessly (prints URL for user to open)
+# wk auth add user@example.com --headless --no-input
 
-# Use
-wk gmail search "is:unread" --account user@gmail.com --json
-wk drive list --account user@gmail.com --json
-wk calendar events list --account user@gmail.com --json
+# First queries
+wk gmail search "is:unread" --account user@example.com --json
+wk drive ls --account user@example.com --json
+wk calendar events --account user@example.com --json
 ```