gog-workspace

# gog workspace

Use `gog` as the Google Workspace gateway. Prefer `gog` over raw Google APIs.

## Default Flow

For normal Gmail/Drive/Calendar reads, do not run setup/status/auth diagnostics first.

1. Run the requested read command directly with safe `gog --no-input` and `--enable-commands` flags.
2. If that read succeeds, answer the user from the result.
3. If that read fails with installation, auth, account, credentials, or keyring errors, then run the diagnostic check below or tell the user the exact auth action from the command error.

Never call `skill.run_script` for `check-gog.sh` as a preflight step just because this is the first Workspace task in a session.

For unread Gmail, use this exact command shape. Do not invent flags:

```json
[{ "tool": "os.shell.run", "args": { "cmd": "gog", "args": ["--json", "--no-input", "--account", "<email>", "--wrap-untrusted", "--gmail-no-send", "--enable-commands", "gmail.search,gmail.get", "gmail", "search", "is:unread newer_than:7d", "--max", "10"] } }]
```

Gmail search syntax is a positional `<query>` argument. Do not use `--unread`; that flag does not exist. Prefer the canonical verb `gmail search` over the aliases `gmail list`, `gmail ls`, `gmail find`, or `gmail query` unless the user explicitly asks for an alias.

Calendar event listing must use the canonical command `calendar events` with `--enable-commands calendar.events`. Do not use `calendar list`, `calendar ls`, or `--enable-commands calendar.list`; `gog` resolves those aliases to `calendar events` internally and rejects the call unless `calendar.events` is enabled.

## Diagnostics

Run the non-interactive diagnostic check only when the user asks to check setup/status, after a real `gog` read command reports installation/auth/account/credentials/keyring failure, or after the user says they changed setup/auth:

```json
[{ "tool": "skill.run_script", "args": { "skill": "gog-workspace", "script": "check-gog.sh" } }]
```

Outcome map:

- `status: healthy` -> proceed with `gog`.
- `status: install_required` -> stop and tell the user how to install `gog`.
- `status: auth_required` -> stop and tell the exact auth commands from the check output. Prefer `gog auth credentials <credentials.json>` followed by `gog auth add <email>` when those are shown; use the user's known email if available.
- `status: api_required` -> tell the user which Google API must be enabled, then stop.

The check is diagnostic and may exit successfully even when setup is incomplete. Follow the `status:` line in its output, not only the tool success/failure marker. Do not run it before trying the requested read command.

## Human Setup Only

Never run `setup-gog.sh` or `setup-gog.ps1` through tools. OAuth, keyring prompts, and browser consent require a real user terminal.

macOS / Linux:

```bash
bash ~/.atomic-agent/skills/gog-workspace/scripts/setup-gog.sh
```

Windows:

```powershell
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.atomic-agent\skills\gog-workspace\scripts\setup-gog.ps1"
```

The user needs a Desktop OAuth client JSON from Google Cloud Console. The setup script stores it with `gog auth credentials ...`, then runs `gog auth add ...`.

If the check output says `config.path ... (missing)`, `run gog auth credentials <credentials.json>`, or `Auth setup is incomplete`, do not only say "run setup-gog.sh". Tell the user the direct commands:

```bash
gog auth credentials <credentials.json>
gog auth add <email>
```

## Account Selection

If any `gog` command fails with `missing --account`, multiple OAuth accounts are available and no unambiguous account was selected. Run `gog auth list` to inspect accounts, then either:

- Retry the command with `--account <email>` when the target account is known from the user request or prior context.
- Ask the user which account to use when no account is clear.
- Tell the user they can set a default with `gog auth manage` or export `GOG_ACCOUNT=<email>`.

When the user has just added a specific account, say the exact follow-up command if auth still needs to be completed, for example:

```bash
gog auth add <email>
```

For reads, prefer passing `--account <email>` explicitly once the account is known instead of relying on a default.

## Command Rules

Use safe global flags for agent reads:

- `--json` for structured stdout.
- `--no-input` to fail instead of prompting.
- `--wrap-untrusted` when reading email, docs, Drive files, contacts, or other user content.
- `--gmail-no-send` unless the user explicitly asks to send or draft email.
- `--enable-commands <csv>` to narrow the command surface for the task.

Read commands that include `--no-input` plus a narrow read-only `--enable-commands` value run through the shell guard without an approval prompt. If you omit those flags or include write-capable commands, the shell guard will require approval.

Ask for explicit approval before writes, sends, sharing changes, deletes, admin actions, or broad exports/backups. Use `--dry-run` when supported.

## Common Reads

Check recent unread mail:

```json
[{ "tool": "os.shell.run", "args": { "cmd": "gog", "args": ["--json", "--no-input", "--account", "<email>", "--wrap-untrusted", "--gmail-no-send", "--enable-commands", "gmail.search,gmail.get", "gmail", "search", "is:unread newer_than:7d", "--max", "10"] } }]
```

Read a Gmail message after search returns an id:

```json
[{ "tool": "os.shell.run", "args": { "cmd": "gog", "args": ["--json", "--no-input", "--account", "<email>", "--wrap-untrusted", "--gmail-no-send", "--enable-commands", "gmail.get", "gmail", "get", "<messageId>", "--sanitize-content"] } }]
```

List today's calendar events:

```json
[{ "tool": "os.shell.run", "args": { "cmd": "gog", "args": ["--json", "--no-input", "--enable-commands", "calendar.events", "calendar", "events", "--today"] } }]
```

Read a specific calendar event after an events list returns an id:

```json
[{ "tool": "os.shell.run", "args": { "cmd": "gog", "args": ["--json", "--no-input",