@damiangilgonzalez/harness 1.3.7

package/skills/godot/references/nodes-scenes-resources.md

@@ -0,0 +1,109 @@
+# Nodes, scenes, scripts & custom Resources (Godot 4.x)
+
+The four building blocks and when each is the right tool. Getting this decomposition right is what
+separates a maintainable Godot project from a monolithic scene that nobody can touch.
+
+## The mental model
+
+- **Node** — a live object in the running tree. It has a transform (2D/3D), can render, process,
+  collide, receive input. Everything on screen is a node. Pick the most specific typed subclass
+  (`Sprite2D`, `Area3D`, `CharacterBody2D`, `Timer`, `AudioStreamPlayer`).
+- **Scene** (`.tscn`) — a saved tree of nodes with a designated **root**, instanceable N times. The
+  reusable unit of a Godot game. A scene can instance other scenes (composition).
+- **Script** (`.gd` / `.cs`) — code attached to one node, giving it behavior. Attach to the scene
+  root; treat children as parts the root drives.
+- **Resource** (`.tres` / `.res`) — a reference-counted **data** object, not in the tree. Textures,
+  audio, materials are Resources; so are your **custom** data classes.
+
+## Composition over inheritance / deep trees
+
+Prefer assembling small scenes over one giant tree or a deep script inheritance chain.
+
+- A `Player` scene = `CharacterBody2D` root + `Sprite2D` + `CollisionShape2D` + `Camera2D` +
+  instanced `HealthComponent` + `HurtboxComponent` sub-scenes.
+- Behaviors as **components**: a `HealthComponent` (its own scene/script exposing `signal died`) can
+  be dropped onto a player, an enemy, or a crate — no shared base class needed.
+- Reach for `extends MyBase` only for genuine "is-a" specialization; reach for composed child nodes
+  for "has-a" behavior. The latter is the Godot-idiomatic default.
+
+## `class_name` — when to register a global type
+
+```gdscript
+class_name HealthComponent extends Node
+signal died
+@export var max_health := 100
+var _current := max_health
+```
+
+- Register (`class_name`) reusable scripts and **all** custom Resources — it enables `is`/`as`
+  checks, `HealthComponent.new()`, and a proper inspector type/slot.
+- Skip it for one-off scene-root scripts that nothing else references by type.
+- Names are global and must be unique across the project.
+
+## Custom Resources — typed game data
+
+Use a custom `Resource` instead of loose `Dictionary`/JSON whenever you have structured game data:
+stats, items, dialogue lines, wave definitions, ability configs. You get inspector editing, type
+safety, `@export` slots, and save/load for free.
+
+```gdscript
+# item.gd
+class_name Item extends Resource
+@export var display_name: String = ""
+@export var icon: Texture2D
+@export var max_stack: int = 99
+@export var value: int = 0
+```
+```gdscript
+# Use it as a typed @export slot on any node:
+@export var starting_items: Array[Item] = []
+
+# Create/save/load in code:
+var potion := Item.new()
+potion.display_name = "Potion"
+ResourceSaver.save(potion, "res://data/potion.tres")
+var loaded := load("res://data/potion.tres") as Item
+```
+
+**Gotcha — shared vs unique**: a Resource assigned in the inspector is **shared by reference** across
+all instances by default. If each node must own its copy (e.g. runtime-mutated stats), enable
+**Local to Scene** on the resource, or `duplicate()` it in `_ready()`. Otherwise mutating one
+enemy's `stats.health` mutates every enemy sharing that `.tres`.
+
+## `preload` vs `load`
+
+| | `preload("res://x")` | `load("res://x")` |
+| --- | --- | --- |
+| Resolved | parse/compile time | runtime, when the line runs |
+| Path | must be a constant literal | can be a variable/computed |
+| Use for | assets you always need; breaks fast if the path is wrong | dynamic/optional assets, avoiding circular preloads |
+| Returns | the Resource/`PackedScene` | same |
+
+```gdscript
+const BULLET := preload("res://bullet.tscn")   # PackedScene, baked in
+func shoot() -> void:
+    var b := BULLET.instantiate()               # -> a Node
+    add_child(b)
+
+# runtime path
+var scene := load("res://enemies/%s.tscn" % enemy_id) as PackedScene
+```
+
+## Instancing & freeing lifecycle
+
+- `PackedScene.instantiate()` → a detached node; add it with `add_child(node)` (or
+  `add_sibling`) to bring it into the tree and trigger `_ready`.
+- Free with `queue_free()` (deferred to end of frame — safe during signals/physics). Avoid `free()`
+  unless you know the node is out of the tree and not mid-callback.
+- After freeing, guard any retained reference with `is_instance_valid(node)` before touching it.
+- `add_child(node, true)` forces a readable unique name; useful when spawning many of one scene.
+
+## `.tscn` / `.tres` are strict text — validation rule
+
+Both formats are line-oriented with a header (`[gd_scene load_steps=N format=3 ...]`),
+`[ext_resource ...]` / `[sub_resource ...]` blocks, and `[node ...]` / property lines. A wrong
+`load_steps` count, a dangling `ExtResource("x")` id, or a malformed `[node]` path makes Godot
+refuse to open the file. **Do not machine-generate or hand-edit these beyond trivial value tweaks,
+and always open the project in the editor once before relying on a changed scene** — the editor is
+the only reliable validator. Build data-Resources in code + `ResourceSaver.save()` instead of
+writing `.tres` by hand.

package/skills/google-workspace/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: google-workspace
+description: "Use when server-side code reads or writes Gmail, Drive, Calendar, or Sheets with a GCP service account and no human in the OAuth loop: picking the auth mode (app-owned vs domain-wide delegation vs keyless), scoping to least privilege, building the authed Node/Python client, staying under per-user quota, and debugging unauthorized_client / 403 / 429. NOT SMTP providers or deliverability (that is `email-connector`), NOT slot-finding and booking UX (that is `calendar-scheduling`)."
+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.** Everything here is service-account
+/ machine auth — if a real user must click "Allow", that is interactive OAuth and
+out of scope.
+
+Where the neighbouring layers live:
+
+| Not this skill | Goes to | This skill's slice |
+|---|---|---|
+| SMTP/provider choice, transactional/marketing sends | `email-connector` | Gmail-the-API inside a Workspace mailbox |
+| SPF/DKIM, inbox placement | `email-deliverability` | — |
+| Availability search, booking-link UX, timezone-as-a-feature | `calendar-scheduling` | Raw Calendar event CRUD underneath |
+| Sheet data modeling, formulas, pivots | `spreadsheet-ops` | Sheets API read/write transport |
+| Doc/PDF parsing, extraction, OCR | `document-processing` | Drive as storage transport (upload/download/move/permissions) |
+| Chaining several connectors into one flow | `automation-flows` | The individual Google calls |
+| Notion as the backend / generic REST wrapping | `notion-connector`, `api-connector-builder` | — |
+| Receiving Gmail/Drive push notifications | `webhooks` | — |
+
+## 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. `references/auth-setup.md` has the full Cloud + Admin
+click-path, the scope catalog, DWD authorization, keyless WIF/ADC, and a longer
+troubleshooting matrix.
+
+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.** A leaked key is the single most common Workspace credential
+  compromise. 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 |
+
+Before this connector ships, run the secret-handling and key-rotation pass in
+`../secure-coding/SKILL.md`.

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 |