---
name: gws-workspace
description: Use Sellable Admin's configured Google Workspace access for Gmail, Calendar, Drive, Docs, Sheets, and related GWS work. Trigger for today's meetings, calendar changes, adding or deleting events, reading or searching email, Gmail threads, Drive files, Docs, Sheets, contacts, or explicit GWS requests.
allowed-tools:
  - Bash
  - Read
  - Skill
---

# Sellable Admin Google Workspace

Use the existing Google Workspace integration through the host terminal. Do not
look for Gmail or Calendar under `mcp__sellable-admin__*`, and do not claim the
integration is unavailable merely because the Admin MCP tool list has no GWS
method.

On Hermes, load the built-in `google-workspace` skill for its current command
contract and Gmail search reference. The Sellable Admin profile uses these
known paths:

```bash
PROFILE_HOME="${SELLABLE_ADMIN_PROFILE_HOME:?set the named Admin profile home}"
export HERMES_HOME="$PROFILE_HOME"
export GOOGLE_WORKSPACE_CLI_CONFIG_DIR="$PROFILE_HOME/.config/gws"
umask 077
mkdir -p "$GOOGLE_WORKSPACE_CLI_CONFIG_DIR"
chmod 700 "$GOOGLE_WORKSPACE_CLI_CONFIG_DIR"
GWS_SKILL="$PROFILE_HOME/skills/productivity/google-workspace"
GAPI="env HERMES_HOME=$PROFILE_HOME /opt/hermes/.venv/bin/python $GWS_SKILL/scripts/google_api.py"
GSETUP="env HERMES_HOME=$PROFILE_HOME /opt/hermes/.venv/bin/python $GWS_SKILL/scripts/setup.py"
ADMIN_HOME="${SELLABLE_ADMIN_HOME:-$PROFILE_HOME/.sellable-admin}"
```

`SELLABLE_ADMIN_PROFILE_HOME` names the Admin profile and `PROFILE_HOME` is its
source of truth. Do not preserve or
reuse an inherited dashboard/root `HERMES_HOME`; it resolves OAuth at
`/opt/data/google_token.json` instead of the authenticated Admin token. Keep the
explicit `env HERMES_HOME=$PROFILE_HOME` prefix in both `$GSETUP` and `$GAPI` so
every Gmail, Drive, Docs, Sheets, and contacts command uses the same profile.

## Capability routing

### Calendar

Calendar reads and writes use the profile's service-account credential with the
pinned Google Workspace CLI:

```bash
GOOGLE_APPLICATION_CREDENTIALS="$ADMIN_HOME/google-service-account.json" \
  npm exec --yes --package @googleworkspace/cli@0.22.5 -- \
  gws calendar events list \
  --params '{"calendarId":"admin@dittto.ai","timeMin":"<ISO>","timeMax":"<ISO>","singleEvents":true,"orderBy":"startTime"}' \
  --format json
```

Supported Calendar work includes listing, creating, updating, and deleting
events. Use `gws schema calendar.events.<method>` when a write needs the current
request schema. Event creation uses `calendar events insert` with `--params`
and `--json`; never invent request fields.

Calendar ID is `admin@dittto.ai`. Interpret relative dates in
`America/Los_Angeles`, and always send ISO-8601 timestamps with an explicit
offset or `Z`.

### Gmail

Gmail requires the profile's user OAuth token, not the Calendar service
account. Check authentication before the first Gmail operation:

```bash
chmod 600 "$PROFILE_HOME/google_token.json" \
  "$PROFILE_HOME/google_client_secret.json" 2>/dev/null || true
$GSETUP --check
```

When authenticated, use the compatibility wrapper so token refresh and JSON
normalization remain owned by Hermes:

```bash
$GAPI gmail search 'newer_than:7d from:person@example.com' --max 10
$GAPI gmail get MESSAGE_ID
```

Supported Gmail work includes search, reading messages, labels, and—after the
approval rules below—send or reply. Do not use the service-account credential
for Gmail; it returns a Google precondition error for this account.

### Drive, Docs, Sheets, and contacts

After `$GSETUP --check` returns `AUTHENTICATED`, use `$GAPI` and the built-in
`google-workspace` skill for read and write commands. Prefer the wrapper over
handwritten REST calls because it owns token refresh and normalized output.
If one of these services returns `accessNotConfigured`, report that the
specific Google API is disabled for the OAuth client project; do not treat it
as evidence that Gmail or the service-account Calendar route is unavailable.

## Approval rules

Reads do not require confirmation. External mutations do:

- Before creating, updating, or deleting a Calendar event, show the exact
  calendar, title, start, end, timezone, attendees, recurrence, and location,
  then obtain explicit approval.
- Before modifying Gmail labels, Drive permissions/files, Docs, or Sheets,
  show the exact intended change and obtain explicit approval.
- Never send or reply to Gmail directly without first drafting the exact
  recipient(s), subject, and full body in chat and waiting for Christian's
  explicit approval. An initial request to “send” is permission to draft, not
  permission to transmit.
- Prefer reversible mutations: trash Drive files rather than permanent delete.

## Failure handling

- If Calendar fails, report the sanitized GWS CLI error and the attempted
  method. If the error is a discovery-cache permission failure, verify
  `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` points inside `$PROFILE_HOME`. Never print
  the service-account file.
- If `$GSETUP --check` returns `NOT_AUTHENTICATED`, report that Gmail and the
  user-OAuth Workspace services need their profile OAuth setup completed.
- Do not use `$GSETUP --check-live` as a combined Gmail/Calendar health gate.
  It probes Calendar through the user-OAuth project, while this profile routes
  Calendar through the separate service-account credential above. Verify the
  requested service with its actual read command.
- Do not ask the user to paste a calendar screenshot or email body before
  attempting the configured integration.