Gw Setup

---
name: gw-setup
description: >
  First-run setup for the Google Workspace (gw) plugin. Creates the plugin venv,
  installs deps, walks the user through a Google Cloud project + Desktop OAuth
  client (driving a browser when possible), authenticates, and verifies. Use for
  "set up gw", "gw setup", "authenticate google workspace", "gw first run",
  "connect my google account", "install gw".
  TRIGGERS: "gw setup", "set up google workspace", "gw auth setup", "gw first run",
  "connect google account", "google workspace login", "oauth setup"
---

# gw-setup — get from install to first result

Do everything you safely can **for** the user. The only unavoidable human actions
are clicking buttons inside the Google Cloud Console (Enable, tick the consent
box, download the client JSON) and approving the OAuth consent screen. Navigate to
the exact page, tell the user precisely what to click, wait, then verify by reading
the page before moving on. Report progress as you go.

Throughout, run the CLI via the launcher `"$PLUGIN_ROOT/bin/gw"` once it exists, or
`python3 "$PLUGIN_ROOT/cli/gw.py"` (fall back to `python`) before that. Resolve
`PLUGIN_ROOT` to this plugin's root (`$CLAUDE_PLUGIN_ROOT` if set, else the repo
root that contains `cli/gw.py`).

## Step 1 — Environment

1. Detect Python: prefer `uv` if present (`uv --version`), else `python3 --version`
   (fall back to `python`). Require Python 3.10+.
2. Create the plugin-local venv and install deps from `requirements.txt`
   (idempotent — the single source of truth for the dependency set):
   - With uv: `uv venv "$PLUGIN_ROOT/.venv"` then
     `uv pip install --python "$PLUGIN_ROOT/.venv" -r "$PLUGIN_ROOT/requirements.txt"`
   - Without uv: `python3 -m venv "$PLUGIN_ROOT/.venv"` then
     `"$PLUGIN_ROOT/.venv/bin/pip" install -r "$PLUGIN_ROOT/requirements.txt"`
     (Windows: `"$PLUGIN_ROOT\.venv\Scripts\pip.exe"`).
   `keyring` is listed in `requirements.txt` but optional at runtime (OS-keychain
   token storage); if it fails to build, install the rest and continue — tokens
   fall back to a 0600 file.
3. Ensure the launcher is executable: `chmod +x "$PLUGIN_ROOT/bin/gw"` (POSIX).
   On Windows use `bin/gw.cmd` or `bin/gw.ps1`.
4. Verify: `gw --version` prints `gw, version 1.0.0`. If not, fix before continuing.

## Step 2 — Google Cloud project + Desktop OAuth client

This plugin ships **no** OAuth client — each user brings their own. This is the
part that needs a browser.

1. **Get the machine-readable checklist.** Run `gw auth setup` (or
   `gw auth setup --compact`). It returns JSON:
   `{ "config_dir": "...", "steps": [ {step,title,url,instructions,verify}, ... ] }`.
   Drive the rest of this step from that output — do not hardcode URLs.

2. **Offer browser automation.** If a browser-automation MCP is available
   (e.g. Chrome DevTools MCP tools `mcp__chrome-devtools__*`), use it. If none is
   available, offer to add one:
   `claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest`
   (claude-in-chrome is an alternative). If the user declines automation, **print
   each step's `url` + `instructions` + `verify`** and let them do it manually,
   then resume at Step 3.

3. **Walk the steps** (drive the browser or guide the user), verifying each via the
   step's `verify` string before continuing:
   - Create a Google Cloud project (`projectcreate`). No billing needed.
   - Enable the 7 APIs: Gmail, Calendar, Drive, Docs, Sheets, Tasks, Forms. For
     each, open the library `url` and click **Enable**; verify it shows "API Enabled".
   - Configure the **OAuth consent screen**: user type **External**; add the user's
     own Google account as a **Test user** (Gmail scopes are sensitive — consent is
     blocked for unlisted users). Explain the unverified-app ~25-scope cap; the gw
     default set is well under it. Verify status is "Testing" and the email is listed.
   - Create a **Desktop app** OAuth client (Credentials → OAuth client ID →
     Application type **Desktop app**). Click Create, then **Download** the client
     JSON. Some pages require you to reopen the client to download — do so and verify
     a Desktop client is listed.
   - **Save the client JSON** to `<config_dir>/client_secret.json` (the `config_dir`
     from the checklist, default `~/.config/gw/`). If the browser downloaded it to
     the Downloads folder, move it there for the user and confirm the file exists.

   Where Google requires a relaunch/reopen (e.g. after first enabling APIs, or to
   reveal the download), navigate back to the exact page and re-verify rather than
   assuming success.

## Step 3 — Authenticate

Run `gw auth login`. It starts a localhost callback and opens the consent URL; you
may open that URL in the browser too. On the consent screen the user picks their
Google account and approves. Use `--no-browser` to print the URL instead of opening
one (headless/SSH), and `--account <name>` to add more accounts later.

If login reports **no refresh token**, have the user revoke prior access at
`https://myaccount.google.com/permissions` and log in again.

## Step 4 — Verify it works

1. `gw auth status` → expect `token_present: true` and `valid: true`.
2. A real read, e.g. `gw calendar calendars` or `gw gmail labels`. A successful JSON
   response means setup is complete.

## Step 5 — Optional: knowledge-base connector

The CRM sync, meeting-prep (`/prep-meeting`), and outreach features are optional and
need a knowledge base. Suggest (do not force):
`/plugin marketplace add Elnora-AI/knowledge-vault` then
`/plugin install knowledge-base@knowledge-vault`, and run its setup. Once
`.claude/knowledge-base.local.md` exists, the connector auto-enables. Without it,
those commands no-op with a message and every core Google command still works.
CRM CSV writes stay off until the user opts in: `sync-crm` needs `crm_dir` set in
that file, and sends update the CRM only with `GW_CRM_TRACK=on`.

## Notes / troubleshooting

- **Config lives outside the repo**: tokens, `accounts.json`, and
  `client_secret.json` live under `$GW_CONFIG_DIR` (default `~/.config/gw`), never in
  the repo. Nothing secret is ever written into the plugin directory.
- **Keyring vs file**: with the `keyring` package and an OS backend, tokens go to the
  OS keychain; otherwise a 0600 JSON file. `GW_KEYRING=off` forces file storage.
- **Alternate OAuth client sources**: instead of `client_secret.json` you can set
  `GW_CLIENT_ID`/`GW_CLIENT_SECRET`, or pass `gw auth login --client-secret-file PATH`.
- **Narrow scopes**: `gw auth login --scopes gmail,calendar` (and `--readonly`) if the
  user wants a smaller grant than the default all-services set.