# Google Workspace OAuth — Setup Gotchas Reference

## Credential creation in Google Cloud Console

**No organization → Personal Google account (not Workspace):**
- Select "No organization" — this is correct when using a personal `@lfcs.com.au` Gmail address with no Google Workspace org behind it.
- App type: **Desktop app** (not Web application).
- Internal/External: **External** (Internal requires a Google Workspace org).

## Manual JSON creation when Console doesn't offer download

If the OAuth flow shows `client_id` + `client_secret` as text fields instead of a JSON download button, build the file manually:

```json
{
  "installed": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost"]
  }
}
```

Path: `/root/.hermes/google_client_secret.json`

## Step sequence (correct order)

```bash
# 1. Store client secret
$GSETUP --client-secret /root/.hermes/google_client_secret.json

# 2. Get auth URL (no extra flags)
$GSETUP --auth-url

# 3. Exchange code
$GSETUP --auth-code "FULL_URL_WITH_CODE"

# 4. Verify
$GSETUP --check
```

> `--auth-url` does NOT accept `--services` or `--format` flags — the skill documentation had these incorrectly. Run it bare.

## `localhost:1` redirect failure

Browser redirects to `http://localhost:1/?code=...` which fails with `ERR_UNSAFE_PORT` — **this is expected**, not an error. The full URL is visible in the browser's error page. Copy the URL or just the code parameter from the address bar.

## Drive API "project not linked" error

After successful auth, if Drive calls fail with:
```
Caller does not have required permission to use project opsman-lfcs-27665
```

The OAuth client was created in a different Google Cloud project than the one where Drive API is enabled. Two fixes:

1. **Enable Drive API in the OAuth client's project** — visit `https://console.cloud.google.com/apis/library/drive.googleapis.com?project=YOUR_PROJECT` and enable it there.
2. **Create a fresh OAuth client in `hermes-lfcs` project** — the `opsman-lfcs-27665` project is a residual from prior setup. For a clean slate, use `hermes-lfcs`.

The Drive API project does not need to match the project where the OAuth client was created — the API just needs to be enabled in some project the user has access to.

## `gws` CLI vs Python wrapper path bug

The skill documents a shorthand:
```bash
GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/.../google_api.py"
```

But `$HOME` doesn't expand inside single-quoted strings. Use the full path explicitly:
```bash
GAPI="python /root/.hermes/skills/productivity/google-workspace/scripts/google_api.py"
```

## When the LFCS Google account has no org

- No Cloud organization → personal account auth only
- Advanced Protection (hardware keys) would block the OAuth flow — user would need their Workspace admin to allowlist the client. Unlikely to be active for this account.
- All Drive/Docs/Sheets are personal to the account, not a shared company Drive — unless LFCS has a shared Drive already set up, files land in the user's personal Drive.