rsc-universal 0.1.1

package/skills/google-workspace/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: google-workspace
+description: "Use when building server-side automation that reads or writes Gmail, Drive, Calendar, or Sheets against a real Google Workspace account via the official client libraries and a GCP service account — picking the auth mode, scoping OAuth scopes, building the authed client, and debugging 403/429/unauthorized_client errors. Triggers: 'send mail from a service account in a cron', 'unauthorized_client when impersonating a user', 'which Drive scope to upload to a shared drive', 'set up domain-wide delegation client ID', 'getting 403 insufficient permissions from the Sheets API', 'automatizar Gmail con cuenta de servicio sin login del usuario', 'enviar correos desde un script sense login d'usuari'. NOT generic SMTP/marketing/deliverability email (that is email-connector)."
+tags: [google-workspace, gmail-api, drive-api, calendar-api, sheets-api, service-account, domain-wide-delegation, oauth-scopes]
+recommends: [email-connector, calendar-scheduling, spreadsheet-ops, document-processing, automation-flows, secure-coding, webhooks]
+origin: risco
+---
+
+# Google Workspace — auth + calling Gmail/Drive/Calendar/Sheets
+
+This skill owns one layer: **authenticating to and calling the four Google
+Workspace REST APIs from server-side code.** You pick the auth mode, scope the
+OAuth scopes to least privilege, build the authed client in Node or Python, and
+call Gmail / Drive / Calendar / Sheets with quota-safe patterns. It turns "I
+have a GCP project and a Workspace domain" into code that sends mail, moves
+files, books events, and reads/writes spreadsheets without a human in the OAuth
+loop.
+
+It does NOT own email-as-a-product, scheduling-as-a-product, or
+spreadsheet-as-data. See the boundaries below before you start.
+
+Operating posture:
+
+- **No human in the loop.** Everything here is service-account / machine auth.
+  If a real user must click "Allow", that is interactive OAuth — out of scope.
+- **Least scope, keyless first.** Default to the narrowest scope and to
+  Application Default Credentials / Workload Identity Federation over a
+  downloaded JSON key. A leaked key is the single most common Workspace
+  credential compromise.
+- **Quota is a real constraint, not a footnote.** The per-user limits are tight
+  (6k units/min Gmail, 60 req/min Sheets). Build backoff in from line one.
+
+## When to use / When NOT to use
+
+**Use when:** a cron, webhook handler, or agent tool reads/writes Gmail, Drive,
+Calendar, or Sheets without an interactive login; you must decide between
+app-owned resources and impersonating each Workspace user; you hit
+`403 insufficient permissions`, `403 rateLimitExceeded`, `429`, or
+`unauthorized_client` and need the scope/delegation/quota fix; you are wiring
+`googleapis` (Node) or `google-api-python-client` + `google-auth` (Python);
+you are migrating off downloaded JSON keys toward keyless auth.
+
+**Do NOT use for:**
+
+- **Generic transactional/marketing email, SMTP, providers, deliverability,
+  SPF/DKIM** → `email-connector` and `email-deliverability`. This skill covers
+  Gmail-the-API inside a Workspace mailbox, not provider choice or inbox
+  placement.
+- **Scheduling logic, availability, booking-link UX, timezone-as-a-feature** →
+  `calendar-scheduling`. This skill covers the raw Calendar event CRUD it sits
+  on top of.
+- **Spreadsheet data modeling, formulas, pivots, transforms as the deliverable**
+  → `spreadsheet-ops`. This skill covers the Sheets API read/write transport.
+- **Doc/PDF parsing, extraction, OCR** → `document-processing`. Drive here is
+  storage transport (upload/download/move/permissions), not content extraction.
+- **Multi-step orchestration across connectors** → `automation-flows`. **Notion**
+  → `notion-connector`. **Generic REST wrapping** → `api-connector-builder`.
+
+## Pick your auth mode
+
+Choose first — it dictates scopes, the Admin-console step, and the client build.
+
+| Situation | Mode | Why |
+|---|---|---|
+| App owns the data (its own Drive folder, its own calendar, a shared drive it was added to) | Service account, **no** delegation | The SA is its own identity; no need to act as a human. Simplest, no Admin step. |
+| Must act AS each Workspace user (send from `ops@acme.com`, read their inbox/calendar) | Service account + **domain-wide delegation** + `subject` | Gmail has no "shared mailbox via SA" — to touch a user's mail/calendar you impersonate them. Requires a Workspace admin to authorize the SA. |
+| Code runs on GCP (Cloud Run, GKE, Functions) or CI with WIF | **Keyless**: Application Default Credentials / Workload Identity Federation | No long-lived key file to leak or rotate. The runtime mints short-lived tokens. Always prefer this when the platform supports it. |
+
+Rule: **never reach for domain-wide delegation if app-owned resources suffice.**
+DWD lets the SA impersonate *anyone* in the org for the granted scopes — it is a
+large blast radius. Use it only when you genuinely must act as the user.
+
+## Setup checklist
+
+Do these in order. The full click-path is in `references/auth-setup.md`.
+
+1. **Enable the APIs** you will call in the Cloud console (Gmail, Drive,
+   Calendar, Sheets) for the project. A disabled API returns `403` regardless of
+   scopes.
+2. **Create the service account** in IAM & Admin → Service Accounts. For keyless
+   you stop here and attach the SA to the runtime; for a key you create a JSON
+   key (and treat it like a password — see Security).
+3. **Decide scopes** (next section) — the exact scope *strings* you will request.
+4. **Authorize DWD only if impersonating.** In the Admin console →
+   Security → Access and data control → API controls → **Manage Domain Wide
+   Delegation**, add the SA's **client ID** (the numeric `client_id`, not the
+   email) plus the **exact** comma-separated scope list. A scope requested in
+   code but not authorized here is the #1 cause of `unauthorized_client`.
+
+## Scopes: least privilege
+
+Request the narrowest scope that does the job. Broad scopes also force a stricter
+Google verification review and widen what a leaked key can touch.
+
+```text
+# Bad — full read/write to ALL of the user's Drive
+https://www.googleapis.com/auth/drive
+
+# Good — only files this app created or was explicitly shared
+https://www.googleapis.com/auth/drive.file
+```
+
+| Task | Scope | Note |
+|---|---|---|
+| Send mail only | `gmail.send` | Cannot read the inbox — ideal for notifications. |
+| Read mail | `gmail.readonly` | Read, no modify/delete. |
+| Modify labels/state | `gmail.modify` | Avoid full `mail.google.com` unless you truly need delete + settings. |
+| App-created Drive files | `drive.file` | Cannot see the user's other files — smallest footprint. |
+| Read all Drive | `drive.readonly` | Prefer over full `drive`. |
+| Calendar events | `calendar.events` | Narrower than full `calendar`. |
+| Read/write Sheets | `spreadsheets` | Use `spreadsheets.readonly` if you only read. |
+
+## Build the authed client
+
+Node uses `googleapis` (latest 173.x, maintenance mode — bugs/security only) with
+`google-auth-library` (10.6.2). Python uses `google-auth` +
+`google-api-python-client`. The impersonation line is the `subject` / `with_subject`.
+
+```javascript
+// Node — service account, optionally impersonating a Workspace user.
+import { google } from 'googleapis';
+
+const auth = new google.auth.JWT({
+  email: process.env.SA_CLIENT_EMAIL,
+  key: process.env.SA_PRIVATE_KEY.replace(/\\n/g, '\n'), // from secret mgr, never a file in the repo
+  scopes: ['https://www.googleapis.com/auth/gmail.send'],
+  subject: 'ops@acme.com', // omit this line for app-owned (no-delegation) mode
+});
+const gmail = google.gmail({ version: 'v1', auth });
+```
+
+```javascript
+// Node — keyless on GCP (Cloud Run / GKE / CI with WIF). No key in code at all.
+import { google } from 'googleapis';
+const auth = new google.auth.GoogleAuth({
+  scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly'],
+});
+const sheets = google.sheets({ version: 'v4', auth });
+```
+
+```python
+# Python — service account from credentials, impersonating a user.
+from google.oauth2 import service_account
+from googleapiclient.discovery import build
+
+SCOPES = ["https://www.googleapis.com/auth/gmail.send"]
+creds = service_account.Credentials.from_service_account_info(
+    sa_info, scopes=SCOPES         # sa_info loaded from secret mgr, not a tracked file
+).with_subject("ops@acme.com")     # drop .with_subject(...) for app-owned mode
+gmail = build("gmail", "v1", credentials=creds, cache_discovery=False)
+```
+
+## Per-API recipes (short)
+
+Copy-paste-ready minimums. Longer recipes (raw MIME with attachments, resumable
+uploads, `batchUpdate`, recurring/timezone-correct events) are in
+`references/api-recipes.md`.
+
+```javascript
+// Gmail: send. Body must be base64url-encoded RFC 822 (note -_ , no padding).
+const raw = Buffer.from(
+  'To: a@acme.com\r\nSubject: Report\r\n\r\nHello.'
+).toString('base64url');
+await gmail.users.messages.send({ userId: 'me', requestBody: { raw } });
+```
+
+```javascript
+// Drive: create a file, then grant read to one person (least-privilege share).
+const file = await drive.files.create({
+  requestBody: { name: 'report.pdf' },
+  media: { mimeType: 'application/pdf', body: stream },
+  fields: 'id', // partial response — ask only for what you use
+});
+await drive.permissions.create({
+  fileId: file.data.id,
+  requestBody: { role: 'reader', type: 'user', emailAddress: 'a@acme.com' },
+});
+```
+
+```python
+# Calendar: insert an event (always send explicit IANA timeZone).
+event = {
+    "summary": "Sync",
+    "start": {"dateTime": "2026-06-10T10:00:00", "timeZone": "Europe/Andorra"},
+    "end":   {"dateTime": "2026-06-10T10:30:00", "timeZone": "Europe/Andorra"},
+}
+cal.events().insert(calendarId="primary", body=event).execute()
+```
+
+```python
+# Sheets: write a range. Use values.batchUpdate to write many ranges in one call.
+sheets.spreadsheets().values().update(
+    spreadsheetId=SID, range="Sheet1!A2",
+    valueInputOption="USER_ENTERED",
+    body={"values": [["2026-06-02", 1290]]},
+).execute()
+```
+
+## Stay under quota
+
+The per-user ceiling is the one that bites a cron looping over a mailbox.
+
+- **Gmail:** 1.2M units/min per project, **6,000 units/min per user**, 80M
+  units/day. Costs: `messages.send` 100, `messages.get` 20, `messages.list` 5,
+  `messages.modify` 5, `drafts.create` 10. Hard cap **500 recipients/message**.
+- **Drive:** 1M units/min per project, **325,000 units/min per user**, 1 TB/day
+  egress.
+- **Sheets:** read and write each 300/min per project, **60/min per user**; 429
+  on overage; 180s request timeout; keep payloads under ~2 MB.
+- **Policy shift:** as of 2026-05-01 Google updated Workspace quota policy —
+  projects active Nov 2025–Apr 2026 keep legacy quotas, new projects get the new
+  model, and overage will start incurring Cloud billing charges later in 2026.
+  Treat quota as a cost line, not a free ceiling.
+
+Three habits keep you under it:
+
+1. **`fields` partial responses** — ask only for the fields you read; smaller
+   responses, lower cost, faster.
+2. **Batch** — Sheets `values.batchUpdate`, Gmail batch requests, Drive batch —
+   one call instead of N cuts per-user request count directly.
+3. **Exponential backoff with jitter** on `403 rateLimitExceeded` and `429` —
+   retrying immediately just burns more quota.
+
+```python
+# Backoff: min((2^n) + random_ms, max_backoff). Cap 32–64s. Jitter avoids
+# thundering-herd retries syncing up.
+import random, time
+from googleapiclient.errors import HttpError
+
+def with_backoff(call, max_retries=6, max_backoff=64):
+    for n in range(max_retries):
+        try:
+            return call()
+        except HttpError as e:
+            if e.resp.status not in (403, 429) or n == max_retries - 1:
+                raise
+            time.sleep(min((2 ** n) + random.random(), max_backoff))
+```
+
+## Security rules
+
+- **Never commit the SA key JSON.** It is a long-lived bearer credential — a
+  committed `service_account.json` is game over. Add `*.json` SA patterns to
+  `.gitignore`; the `verify.sh` here flags tracked keys.
+- **Prefer keyless.** On GCP/CI use ADC or Workload Identity Federation so there
+  is no file to leak. If you must use a key, store it in a secret manager
+  (env-injected, not a file beside the code) and rotate it.
+- **Least scope.** A leaked `drive.file` key sees app files; a leaked full
+  `drive` key sees everything. The scope IS the blast radius.
+- **Map the error before you change anything:**
+
+| Error | Likely cause | Fix |
+|---|---|---|
+| `unauthorized_client` | SA client ID / scope not authorized for DWD | Add the client ID + **exact** scopes in Admin console Manage DWD |
+| `403 insufficient permissions` | Scope too narrow, or API not enabled | Widen to the right scope (still least), enable the API |
+| `403 rateLimitExceeded` / `429` | Per-user or per-project quota hit | Exponential backoff + jitter; batch; spread load |
+| `400 failedPrecondition` on impersonation | `subject` set but DWD not configured | Either remove `subject` (app-owned) or finish DWD setup |
+| `invalid_grant` | Clock skew or stale/rotated key | Sync clock; re-issue the key |
+
+## Anti-patterns
+
+| Anti-pattern | Why it breaks | Do instead |
+|---|---|---|
+| Committing `service_account.json` to the repo | Long-lived key in git history = full compromise; can't un-leak | Keyless ADC/WIF, or key in a secret manager + `.gitignore` |
+| Requesting `auth/drive` / `mail.google.com` "to be safe" | Max blast radius, stricter Google review, more to leak | Narrowest scope: `drive.file`, `gmail.send`, `spreadsheets.readonly` |
+| Using DWD `subject` for app-owned data | Impersonating users when the SA could own the resource — needless blast radius + an Admin dependency | Drop `subject`; let the SA own the folder/calendar/shared drive |
+| Looping `messages.send`/`values.update` per row with no backoff | Trips the 6k/min (Gmail) or 60/min (Sheets) per-user cap → 429 storm | Batch (`values.batchUpdate`) + exponential backoff with jitter |
+| Reading whole resources without `fields` | Bigger payloads, higher quota cost, slower | Request only the fields you use (`fields: 'id'`) |
+| Hardcoding the private key inline in source | Can't rotate, leaks via logs/screenshots/history | Inject from env/secret manager; `\n`-unescape at load |
+| Pasting raw text into Gmail `raw` | API needs base64url RFC 822, not plain text → 400 | Build a MIME message, `base64url`-encode it |
+| Setting `subject` but skipping the Admin DWD step | `unauthorized_client` — the SA was never allowed to impersonate | Authorize client ID + exact scopes in Manage DWD first |
+
+## See also
+
+- `../secure-coding/SKILL.md` — secret handling, key rotation, and the security
+  pass before this connector ships.
+
+Recommended companions (siblings; create/link when present): `email-connector`
+for SMTP/provider/deliverability email, `calendar-scheduling` for slot-finding
+and booking UX, `spreadsheet-ops` for sheet data modeling and formulas,
+`document-processing` for parsing files you pull from Drive, `automation-flows`
+for chaining this across multiple connectors, and `webhooks` for receiving
+Gmail/Drive push notifications.
+
+Deep dives: `references/auth-setup.md` (full Cloud + Admin walkthrough, scope
+catalog, DWD authorization, keyless WIF/ADC, troubleshooting matrix) and
+`references/api-recipes.md` (extended Node + Python recipes).

package/skills/google-workspace/evals/README.md

@@ -0,0 +1,16 @@
+# Evals — google-workspace
+
+These cases are routing and coverage checks for the skill harness, not live
+Google API calls. `should_trigger` asserts a prompt should load and use this
+skill (server-side Gmail/Drive/Calendar/Sheets via a service account, scope and
+delegation decisions, 403/429/unauthorized_client debugging), including a
+Spanish phrasing and non-obvious error-symptom triggers. `should_not_trigger`
+asserts that a neighboring concern instead routes to the named real sibling
+(email-deliverability, calendar-scheduling, spreadsheet-ops, document-processing,
+automation-flows), guarding the boundaries in SKILL.md. The single `capability`
+case is a rubric: feed the scenario to the skill and check the generated answer
+covers every `must_include` bullet (correct DWD `subject`, minimal scopes, the
+Admin-console client-ID authorization, the googleapis client build, backoff on
+429, and the never-commit-the-key / keyless guidance). Nothing here touches a
+real GCP project or sends mail; `scripts/verify.sh` is the only executable
+artifact and it is a no-network static linter you can run against any repo.

package/skills/google-workspace/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: google-workspace
+
+should_trigger:
+  - prompt: "I need a Node cron job to send a daily email through the Gmail API using a service account, no user clicking Allow. How do I authenticate?"
+    why: "Core use case: server-side, no-human-in-the-loop Gmail send via a service account. Names the auth-mode decision this skill owns."
+  - prompt: "I'm getting unauthorized_client when my service account tries to impersonate ops@acme.com. What did I miss?"
+    why: "Non-obvious error-symptom trigger. unauthorized_client maps directly to a missing/incorrect domain-wide-delegation client-ID + scope authorization in the Admin console — the skill's troubleshooting core."
+  - prompt: "Read values from a Google Sheet in a Python script with a service account and write a couple of rows back."
+    why: "Sheets API read/write transport via SA — exactly this skill, not the data-modeling concern of spreadsheet-ops."
+  - prompt: "Necesito automatizar Gmail con una cuenta de servicio sin login del usuario, ¿qué scope y delegación uso?"
+    why: "Spanish phrasing of the flagship: service-account Gmail automation, scope + delegation question. Must fire across language."
+  - prompt: "Which OAuth scope do I need to upload a file into a shared drive with the Drive API — is drive.file enough?"
+    why: "Scope-selection question, the least-privilege table is the skill's job. Non-obvious because the answer hinges on shared-drive support + drive.file semantics."
+  - prompt: "Walk me through setting up the domain-wide delegation client ID in the Google Admin console for my service account."
+    why: "Setup step unique to this skill: authorizing the SA's numeric client ID plus exact scopes under Manage Domain Wide Delegation. Non-obvious that it's the client ID, not the email."
+  - prompt: "My Drive API integration keeps throwing 403 rateLimitExceeded under load — how should I handle it?"
+    why: "Quota-safe calling (per-user limits + exponential backoff with jitter) is a named section. Error symptom routes here, not to a generic performance skill."
+
+should_not_trigger:
+  - prompt: "Help me configure SPF, DKIM, and DMARC so our cold outreach stops landing in spam."
+    route_to: "email-deliverability"
+    why: "Deliverability / DNS auth records / inbox placement — provider-and-domain concern, explicitly out of scope. This skill is Gmail-the-API, not email reputation."
+  - prompt: "Build a booking page that finds free 30-minute slots across attendees in different timezones and generates a meeting link."
+    route_to: "calendar-scheduling"
+    why: "Scheduling-as-a-product: availability search, timezone UX, booking-link generation. This skill only covers the raw Calendar event CRUD underneath."
+  - prompt: "Write the formulas and a pivot table to summarize monthly sales by region in this spreadsheet."
+    route_to: "spreadsheet-ops"
+    why: "Spreadsheet data modeling and formulas as the deliverable — spreadsheet-ops. This skill is the Sheets API transport, not the analysis."
+  - prompt: "Extract the line items and totals from these invoice PDFs sitting in a Drive folder."
+    route_to: "document-processing"
+    why: "Content extraction / OCR from documents. Drive here is only storage transport; parsing file contents belongs to document-processing."
+  - prompt: "When a Stripe payment succeeds, create a Drive folder, add a Sheets row, and ping Slack — wire up the whole flow."
+    route_to: "automation-flows"
+    why: "Multi-step orchestration spanning several connectors. This skill owns the individual Google calls; chaining across connectors is automation-flows."
+
+capability:
+  - scenario: "A Node cron must run as a service account impersonating ops@acme.com to (1) send a Gmail summary and (2) append a row to a Sheet. It currently throws 403 insufficient permissions on the send. Diagnose and give working code."
+    must_include:
+      - "Identify the auth mode as service-account + domain-wide delegation, setting subject/with_subject to ops@acme.com on the JWT/credentials"
+      - "Prescribe minimal scopes: gmail.send + spreadsheets (not full drive / mail.google.com), and note the scope IS the blast radius"
+      - "Call out the Admin console Manage Domain Wide Delegation step: authorize the SA's numeric client ID plus the exact scope list (mismatch -> unauthorized_client; missing scope here -> 403 insufficient permissions)"
+      - "Show a googleapis Node client build (google.auth.JWT with email/key/scopes/subject, then google.gmail and google.sheets)"
+      - "Add exponential backoff with jitter on 403 rateLimitExceeded / 429 around the calls"
+      - "Warn never to commit the SA key JSON; prefer keyless ADC/WIF or a secret manager, unescape the private key newlines from env"

package/skills/google-workspace/references/api-recipes.md

@@ -0,0 +1,148 @@
+# API recipes — extended Node + Python
+
+Longer, copy-paste recipes that did not fit in SKILL.md. All assume an authed
+client built per SKILL.md "Build the authed client". Versions as of 2026-06-02:
+`googleapis` latest 173.x (maintenance mode), `google-auth-library` 10.6.2.
+
+## Gmail — raw MIME with an attachment
+
+Gmail's `messages.send` wants a base64url-encoded RFC 822 message. For
+attachments you build a `multipart/mixed` MIME body.
+
+```python
+# Python — MIME with one attachment, base64url-encoded.
+import base64
+from email.message import EmailMessage
+
+msg = EmailMessage()
+msg["To"] = "a@acme.com"
+msg["From"] = "ops@acme.com"
+msg["Subject"] = "Monthly report"
+msg.set_content("Report attached.")
+with open("report.pdf", "rb") as f:
+    msg.add_attachment(
+        f.read(), maintype="application", subtype="pdf", filename="report.pdf"
+    )
+raw = base64.urlsafe_b64encode(msg.as_bytes()).decode()
+gmail.users().messages().send(userId="me", body={"raw": raw}).execute()
+```
+
+Hard cap: 500 recipients per message. For bulk, fan out in batches and keep the
+per-user 6,000 units/min ceiling in mind (`send` costs 100 units each → ~60
+sends/min/user before you risk 429).
+
+## Drive — resumable upload of a large file
+
+Use a resumable upload for anything large or over a flaky connection.
+
+```javascript
+// Node — resumable upload. googleapis handles the resumable protocol.
+import fs from 'node:fs';
+const res = await drive.files.create(
+  {
+    requestBody: { name: 'big.zip' },
+    media: { mimeType: 'application/zip', body: fs.createReadStream('big.zip') },
+    fields: 'id',
+  },
+  { /* per-call options */ },
+);
+```
+
+To upload into a **shared drive**, set `supportsAllDrives: true` and pass the
+parent folder id; `drive.file` scope lets the app manage files it created there.
+
+## Sheets — batch read and write
+
+One `values.batchUpdate` beats N single `update` calls against the 60/min
+per-user limit.
+
+```javascript
+// Node — write several ranges in a single call.
+await sheets.spreadsheets.values.batchUpdate({
+  spreadsheetId: SID,
+  requestBody: {
+    valueInputOption: 'USER_ENTERED',
+    data: [
+      { range: 'Sheet1!A2', values: [['2026-06-02', 1290]] },
+      { range: 'Sheet1!A3', values: [['2026-06-03', 1310]] },
+    ],
+  },
+});
+```
+
+```python
+# Python — append rows (auto-finds the next empty row).
+sheets.spreadsheets().values().append(
+    spreadsheetId=SID, range="Sheet1!A1",
+    valueInputOption="USER_ENTERED",
+    insertDataOption="INSERT_ROWS",
+    body={"values": [["2026-06-02", 1290], ["2026-06-03", 1310]]},
+).execute()
+```
+
+```python
+# Python — batch READ many ranges in one request (cheaper than N gets).
+res = sheets.spreadsheets().values().batchGet(
+    spreadsheetId=SID, ranges=["Sheet1!A:A", "Sheet2!B2:B"],
+).execute()
+```
+
+Keep request payloads under ~2 MB and expect a 180s server timeout per request.
+
+## Calendar — recurring, timezone-correct events
+
+Always send an explicit IANA `timeZone`; never rely on the server default. Use
+RFC 5545 `RRULE` for recurrence.
+
+```python
+# Python — weekly recurring event, 8 occurrences, explicit timezone.
+event = {
+    "summary": "Weekly sync",
+    "start": {"dateTime": "2026-06-10T10:00:00", "timeZone": "Europe/Andorra"},
+    "end":   {"dateTime": "2026-06-10T10:30:00", "timeZone": "Europe/Andorra"},
+    "recurrence": ["RRULE:FREQ=WEEKLY;COUNT=8"],
+    "attendees": [{"email": "a@acme.com"}],
+}
+cal.events().insert(
+    calendarId="primary", body=event, sendUpdates="all"
+).execute()
+```
+
+## Gmail — watch / push notifications
+
+To get pushed mail events instead of polling, `users.watch` publishes change
+notifications to a Cloud Pub/Sub topic; your endpoint receives them. The
+delivery/handling side (verifying and processing the push) is the `webhooks`
+sibling's territory — this skill only sets up the `watch`.
+
+```javascript
+// Node — start watching the mailbox; renew before the ~7-day expiry.
+await gmail.users.watch({
+  userId: 'me',
+  requestBody: {
+    topicName: 'projects/PROJECT/topics/gmail-events',
+    labelIds: ['INBOX'],
+  },
+});
+```
+
+## Backoff helper (shared)
+
+Wrap every quota-sensitive call. Retries only on `403 rateLimitExceeded` / `429`;
+re-raises everything else immediately.
+
+```javascript
+// Node — exponential backoff with jitter, cap 64s.
+async function withBackoff(call, { maxRetries = 6, maxBackoff = 64 } = {}) {
+  for (let n = 0; ; n++) {
+    try {
+      return await call();
+    } catch (e) {
+      const status = e?.code ?? e?.response?.status;
+      if ((status !== 403 && status !== 429) || n >= maxRetries - 1) throw e;
+      const wait = Math.min(2 ** n + Math.random(), maxBackoff);
+      await new Promise((r) => setTimeout(r, wait * 1000));
+    }
+  }
+}
+```

package/skills/google-workspace/references/auth-setup.md

@@ -0,0 +1,100 @@
+# Auth setup — full walkthrough
+
+The end-to-end path from a fresh GCP project to a working authed client, plus the
+complete scope catalog, domain-wide delegation authorization, keyless setup, and
+a troubleshooting matrix. Facts current as of 2026-06-02.
+
+## 1. Enable the APIs
+
+In the Cloud console, for the project that owns the service account, enable each
+API you will call:
+
+- **Gmail API**
+- **Google Drive API**
+- **Google Calendar API**
+- **Google Sheets API**
+
+A disabled API returns `403` (`accessNotConfigured` / `SERVICE_DISABLED`) no
+matter how the scopes or delegation are set. Enable first, debug later.
+
+## 2. Create the service account
+
+IAM & Admin → Service Accounts → Create. You get an account with:
+
+- `client_email` — `name@project.iam.gserviceaccount.com`, the SA's identity.
+- a numeric **`client_id`** — used for the DWD authorization step (NOT the email).
+
+Two ways to give code its credentials:
+
+- **Keyless (preferred):** attach the SA to the runtime (Cloud Run/GKE/Functions)
+  or federate from CI via Workload Identity Federation. No key file exists.
+- **JSON key:** Service Account → Keys → Add key → JSON. This downloads a
+  long-lived private key. Treat it like a root password: never commit it, store
+  it in a secret manager, rotate it.
+
+## 3. Scope catalog
+
+Request the narrowest scope that does the job. Common ones:
+
+| API | Scope | Grants |
+|---|---|---|
+| Gmail | `gmail.send` | Send only; no inbox read |
+| Gmail | `gmail.readonly` | Read messages/labels; no modify |
+| Gmail | `gmail.modify` | Read + modify labels/state; no settings/delete-all |
+| Gmail | `gmail.labels` | Manage labels only |
+| Gmail | `mail.google.com/` | Full mailbox incl. permanent delete — avoid unless required |
+| Drive | `drive.file` | Only files this app created or was shared into |
+| Drive | `drive.readonly` | Read all of the user's Drive |
+| Drive | `drive` | Full read/write to all Drive — broad, avoid by default |
+| Drive | `drive.metadata.readonly` | Metadata only, no content |
+| Calendar | `calendar.events` | Read/write events |
+| Calendar | `calendar.readonly` | Read events/calendars |
+| Calendar | `calendar` | Full calendar management |
+| Sheets | `spreadsheets.readonly` | Read values/metadata |
+| Sheets | `spreadsheets` | Read + write values and structure |
+
+Picking a broad scope (`drive`, full Gmail) also triggers Google's stricter app
+verification and restricted-scope review. Narrow scopes ship faster.
+
+## 4. Domain-wide delegation (only if impersonating users)
+
+You only need this when the SA must act AS a Workspace user (send from their
+address, read their inbox/calendar). App-owned resources need none of it.
+
+1. Note the SA's numeric **client ID** (step 2).
+2. Admin console → Security → Access and data control → API controls →
+   **Manage Domain Wide Delegation** → Add new.
+3. Enter the **client ID** and a **comma-separated list of the exact scope
+   strings** your code requests. They must match character-for-character.
+4. In code set `subject` (Node) / `.with_subject(...)` (Python) to the email of
+   the user to impersonate.
+
+A scope your code requests that is missing from this list → `unauthorized_client`.
+Adding or removing a scope in code means updating this list too.
+
+## 5. Keyless: ADC and Workload Identity Federation
+
+Downloaded JSON keys are long-lived, leak-prone, and a top GCP credential-exposure
+source. Prefer keyless:
+
+- **ADC on GCP runtimes:** attach the SA to Cloud Run/GKE/Functions. The
+  metadata server mints short-lived tokens; `GoogleAuth` / ADC picks them up
+  automatically — no key in code or env.
+- **Workload Identity Federation (CI / non-GCP):** federate your CI's OIDC
+  identity (e.g. GitHub Actions) to impersonate the SA without a stored key. The
+  provider exchanges a short-lived OIDC token for SA credentials.
+
+Both eliminate the static secret. Reserve JSON keys for environments that
+genuinely cannot federate, and then secret-manage + rotate them.
+
+## 6. Troubleshooting matrix
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `unauthorized_client` | Client ID/scope not authorized for DWD | Add client ID + exact scopes in Manage DWD |
+| `403 accessNotConfigured` / `SERVICE_DISABLED` | API not enabled on the project | Enable it in the Cloud console |
+| `403 insufficient permissions` | Scope too narrow for the call | Use the correct (still least) scope |
+| `400 failedPrecondition` | `subject` set without DWD configured | Finish DWD, or drop `subject` for app-owned |
+| `invalid_grant` | Clock skew, or rotated/revoked key | Sync clock (NTP); re-issue key |
+| `404` on a user's resource via SA, no DWD | SA can't see resources it doesn't own | Share the resource to the SA, or impersonate via DWD |
+| `403 rateLimitExceeded` / `429` | Per-user/project quota hit | Exponential backoff + jitter; batch; spread load |