@acedatacloud/skills 2026.504.0 → 2026.504.2

package/skills/google-drive/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: google-drive
+description: Read and search Google Drive files / folders / shared content via the Drive v3 REST API. Use when the user mentions Drive files, "my drive", shared documents, Google Docs / Sheets / Slides, exporting / downloading a Drive file, or searching by name / owner / folder.
+when_to_use: |
+  Trigger when the user wants to list, search, read or download files
+  in their Google Drive — including Google-native docs (Docs / Sheets /
+  Slides) which need a special "export" call to get plain content. The
+  installed connector grants read-only scope (`drive.readonly`); writes
+  are out of scope.
+connections: [google/drive]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Drive Google Drive via `curl + jq`. The user's OAuth bearer token is
+in `$GOOGLE_DRIVE_TOKEN`; every call needs it as
+`Authorization: Bearer $GOOGLE_DRIVE_TOKEN`. The token already carries
+the `drive.readonly` scope the user agreed to at install plus the
+identity scopes (`openid email profile`).
+
+The Drive API returns standard JSON; failures surface as
+`{"error": {"code": 401|403|..., "message": "..."}}` — show that
+error verbatim to the user. `401` means the token expired and the
+user must re-install the connector. `403 insufficientPermissions`
+means the connector grants only `drive.readonly` and the user is
+asking for a write — say so explicitly.
+
+**Always start with `/about?fields=user`** to confirm the connection
+works AND learn which Google account you're operating against.
+
+## Recipes
+
+### Verify auth (always run first)
+
+```sh
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  "https://www.googleapis.com/drive/v3/about?fields=user(displayName,emailAddress,photoLink),storageQuota(usage,limit)" \
+  | jq '{user, quota: .storageQuota}'
+```
+
+### List recent files (last modified first)
+
+```sh
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  "https://www.googleapis.com/drive/v3/files?orderBy=modifiedTime%20desc&pageSize=20&fields=files(id,name,mimeType,modifiedTime,owners(emailAddress),webViewLink,parents)" \
+  | jq '.files[] | {id, name, mimeType, modified: .modifiedTime, owner: .owners[0].emailAddress, webViewLink}'
+```
+
+`pageSize` max is 1000; default is 100. Use `pageToken` from the
+response (`nextPageToken`) for follow-up pages.
+
+### Search by name / fulltext
+
+```sh
+# Exact-name fragments — note "name contains" supports tokens, not regex
+Q='name contains "季度复盘" and trashed = false'
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  --get "https://www.googleapis.com/drive/v3/files" \
+  --data-urlencode "q=$Q" \
+  --data-urlencode 'fields=files(id,name,mimeType,modifiedTime,webViewLink,owners(emailAddress))' \
+  --data-urlencode 'pageSize=20' \
+  | jq '.files[] | {id, name, modified: .modifiedTime, owner: .owners[0].emailAddress}'
+
+# Full-text search (body + title)
+Q='fullText contains "OKR 2026Q2" and trashed = false'
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  --get "https://www.googleapis.com/drive/v3/files" \
+  --data-urlencode "q=$Q" \
+  --data-urlencode 'fields=files(id,name,modifiedTime,webViewLink)' \
+  | jq '.files[]'
+```
+
+The `q` param uses [Drive's mini query language](https://developers.google.com/drive/api/guides/search-files):
+`name`, `fullText`, `mimeType`, `parents`, `'<email>' in owners`,
+`'<email>' in writers`, `modifiedTime > '2026-01-01T00:00:00'`,
+`sharedWithMe`, `trashed`, joined by `and` / `or` / `not`.
+
+### List files shared with me
+
+```sh
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  --get "https://www.googleapis.com/drive/v3/files" \
+  --data-urlencode 'q=sharedWithMe and trashed = false' \
+  --data-urlencode 'orderBy=sharedWithMeTime desc' \
+  --data-urlencode 'fields=files(id,name,mimeType,sharedWithMeTime,owners(displayName,emailAddress))' \
+  --data-urlencode 'pageSize=30' \
+  | jq '.files[] | {name, sharedAt: .sharedWithMeTime, sharedBy: .owners[0]}'
+```
+
+### List children of a folder
+
+```sh
+FOLDER_ID='1A2B3CdEfGhIjKlMn'
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  --get "https://www.googleapis.com/drive/v3/files" \
+  --data-urlencode "q='$FOLDER_ID' in parents and trashed = false" \
+  --data-urlencode 'fields=files(id,name,mimeType,size,modifiedTime),nextPageToken' \
+  | jq '.files'
+```
+
+### Get metadata for a single file
+
+```sh
+FILE_ID='1A2B3CdEfGhIjKlMn'
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  "https://www.googleapis.com/drive/v3/files/$FILE_ID?fields=id,name,mimeType,size,modifiedTime,parents,owners,webViewLink,description"
+```
+
+### Download a binary file (PDF / image / zip / …)
+
+```sh
+FILE_ID='1A2B3CdEfGhIjKlMn'
+OUT=/tmp/download.bin
+curl -sS -L -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  "https://www.googleapis.com/drive/v3/files/$FILE_ID?alt=media" \
+  -o "$OUT"
+file "$OUT" && wc -c "$OUT"
+```
+
+### Read a Google Doc as plain markdown / text
+
+Google-native files (Docs, Sheets, Slides) **don't have raw bytes** —
+you have to ask Drive to *export* them to a concrete MIME type:
+
+```sh
+DOC_ID='1A2B3CdEfGhIjKlMn'
+
+# Markdown (best for chat-friendly summaries)
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  "https://www.googleapis.com/drive/v3/files/$DOC_ID/export?mimeType=text/markdown" \
+  > /tmp/doc.md
+head -40 /tmp/doc.md
+
+# Plain text fallback for older docs
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  "https://www.googleapis.com/drive/v3/files/$DOC_ID/export?mimeType=text/plain" \
+  > /tmp/doc.txt
+```
+
+Common export MIME types:
+
+| native MIME | export to |
+|---|---|
+| `application/vnd.google-apps.document` | `text/markdown`, `text/plain`, `text/html`, `application/pdf`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
+| `application/vnd.google-apps.spreadsheet` | `text/csv`, `application/pdf`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
+| `application/vnd.google-apps.presentation` | `application/pdf`, `text/plain`, `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
+
+### Read a Google Sheet as CSV
+
+```sh
+SHEET_ID='1A2B3CdEfGhIjKlMn'
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  "https://www.googleapis.com/drive/v3/files/$SHEET_ID/export?mimeType=text/csv" \
+  > /tmp/sheet.csv
+head /tmp/sheet.csv
+```
+
+The Drive `export` endpoint returns the **first sheet only**. For
+multi-tab access the user needs to install a separate Google Sheets
+connector (currently out of catalog) — explain that and stop.
+
+### Get permissions / sharing on a file
+
+```sh
+FILE_ID='1A2B3CdEfGhIjKlMn'
+curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+  "https://www.googleapis.com/drive/v3/files/$FILE_ID/permissions?fields=permissions(id,type,role,emailAddress,domain,deleted)" \
+  | jq '.permissions[] | {who: (.emailAddress // .domain // .type), role}'
+```
+
+### Pagination boilerplate
+
+```sh
+PAGE_TOKEN=''
+while : ; do
+  RESP=$(curl -sS -H "Authorization: Bearer $GOOGLE_DRIVE_TOKEN" \
+    --get "https://www.googleapis.com/drive/v3/files" \
+    --data-urlencode 'q=trashed = false' \
+    --data-urlencode 'fields=files(id,name),nextPageToken' \
+    --data-urlencode 'pageSize=200' \
+    ${PAGE_TOKEN:+--data-urlencode "pageToken=$PAGE_TOKEN"})
+  echo "$RESP" | jq -c '.files[]'
+  PAGE_TOKEN=$(echo "$RESP" | jq -r '.nextPageToken // empty')
+  [ -z "$PAGE_TOKEN" ] && break
+done
+```
+
+## Common error codes
+
+| HTTP | meaning | what to tell the user |
+|---|---|---|
+| `401 UNAUTHENTICATED` | token expired / revoked | "Reconnect the Google Drive connector on the Connections page." |
+| `403 insufficientPermissions` | scope missing | "Your installed connector only grants read access — this action needs a write scope we don't have." |
+| `403 userRateLimitExceeded` | quota | retry once after 5–10s; if it persists, tell the user. |
+| `404 notFound` | wrong file id OR file isn't visible to this account | double-check the id; if shared, use `sharedWithMe` query above. |
+| `400 invalidQuery` | malformed `q` | print the `q` you sent + the error message back to the user. |
+
+Never log or echo `$GOOGLE_DRIVE_TOKEN` — treat it as a secret.

package/skills/google-gmail/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: google-gmail
+description: Read, search and triage Gmail mail / threads / labels / attachments via the Gmail v1 REST API. Use when the user mentions Gmail, "my inbox", unread mail, recent emails from someone, summarising a thread, downloading an attachment, or finding mail by label / query.
+when_to_use: |
+  Trigger when the user wants to read, list, search, summarise or
+  inspect Gmail mail — including triaging the inbox, surfacing unread,
+  pulling a single thread for review, or downloading an attachment.
+  The installed connector grants read-only scope (`gmail.readonly`);
+  sending / replying / archiving / labelling are out of scope.
+connections: [google/gmail]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Drive Gmail via `curl + jq`. The user's OAuth bearer token is in
+`$GOOGLE_GMAIL_TOKEN`; every call needs it as
+`Authorization: Bearer $GOOGLE_GMAIL_TOKEN`. The token already
+carries the `gmail.readonly` scope the user agreed to at install plus
+the identity scopes (`openid email profile`).
+
+The Gmail API returns standard JSON; failures surface as
+`{"error": {"code": 401|403|..., "message": "..."}}` — show that
+error verbatim. `401` means the token expired (re-install). `403`
+or `400 insufficientPermissions` means the user is asking for a write
+this connector cannot satisfy — say so.
+
+**Always start with `users/me/profile`** to confirm the connection works
+AND learn which Gmail account you're operating against. Mailbox payloads
+can be huge — fetch metadata first, only `format=full` when the user
+actually wants the body of a specific message.
+
+## Recipes
+
+### Verify auth (always run first)
+
+```sh
+curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  "https://gmail.googleapis.com/gmail/v1/users/me/profile" \
+  | jq '{email: .emailAddress, totalMessages, totalThreads, historyId}'
+```
+
+### List recent unread inbox
+
+```sh
+curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  --get "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
+  --data-urlencode 'q=is:unread in:inbox newer_than:7d' \
+  --data-urlencode 'maxResults=20' \
+  | jq '.messages[]'
+```
+
+The `messages.list` endpoint returns only `{id, threadId}` — you have
+to fan out to `messages.get` for headers / body. Cheap pattern: list
+ids → get with `format=metadata&metadataHeaders=From,Subject,Date` for
+each. Use `format=full` only if the user wants the body.
+
+### List + enrich with headers (one-shot inbox triage)
+
+```sh
+IDS=$(curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  --get "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
+  --data-urlencode 'q=is:unread in:inbox' \
+  --data-urlencode 'maxResults=10' \
+  | jq -r '.messages[].id')
+
+for ID in $IDS; do
+  curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+    --get "https://gmail.googleapis.com/gmail/v1/users/me/messages/$ID" \
+    --data-urlencode 'format=metadata' \
+    --data-urlencode 'metadataHeaders=From' \
+    --data-urlencode 'metadataHeaders=Subject' \
+    --data-urlencode 'metadataHeaders=Date' \
+    | jq '{id: .id, snippet: .snippet, headers: (.payload.headers | map({(.name): .value}) | add), labels: .labelIds}'
+done | jq -s '.'
+```
+
+### Read a single message body (plain text and html)
+
+```sh
+ID='18f1a2b3c4d5e6f0'
+RESP=$(curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  --get "https://gmail.googleapis.com/gmail/v1/users/me/messages/$ID" \
+  --data-urlencode 'format=full')
+
+echo "$RESP" | jq '{id, snippet, headers: (.payload.headers | map({(.name): .value}) | add)}'
+
+# Body is base64url-encoded inside payload.parts[].body.data — Gmail
+# splits multipart messages, so collect every text/plain or text/html
+# leaf and base64url-decode them.
+echo "$RESP" | jq -r '
+  def walk(p):
+    if (p.parts // null) then (p.parts | map(walk(.)) | add) else [p] end;
+  walk(.payload)
+  | map(select(.mimeType=="text/plain" and (.body.data // "") != ""))
+  | .[].body.data' \
+  | tr '_-' '/+' | base64 -d 2>/dev/null
+```
+
+If the plain-text leaf is empty, fall back to the `text/html` leaf
+(same walk, swap the mimeType filter) and tell the user it's HTML.
+
+### Read a whole thread
+
+```sh
+THREAD_ID='18f1a2b3c4d5e6f0'
+curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  --get "https://gmail.googleapis.com/gmail/v1/users/me/threads/$THREAD_ID" \
+  --data-urlencode 'format=metadata' \
+  --data-urlencode 'metadataHeaders=From' \
+  --data-urlencode 'metadataHeaders=Subject' \
+  --data-urlencode 'metadataHeaders=Date' \
+  | jq '{id, historyId, messages: [.messages[] | {id, snippet, from: (.payload.headers | from_entries.From), date: (.payload.headers | from_entries.Date)}]}'
+```
+
+### Search by Gmail query
+
+```sh
+# Same query DSL the Gmail UI uses: from:, to:, subject:, has:attachment,
+# is:unread, label:Work, after:2026/04/01, before:2026/05/01, …
+Q='from:boss@example.com subject:OKR newer_than:30d'
+curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  --get "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
+  --data-urlencode "q=$Q" \
+  --data-urlencode 'maxResults=20' \
+  | jq '.messages // []'
+```
+
+`q` syntax reference: <https://support.google.com/mail/answer/7190> —
+the model-friendly bits are `from:`, `to:`, `cc:`, `subject:`, `label:`,
+`is:unread`, `is:read`, `is:starred`, `has:attachment`, `filename:pdf`,
+`newer_than:7d`, `older_than:30d`, `after:YYYY/MM/DD`, `before:`, `in:inbox`,
+`in:trash`. Combine with `OR` / `()` / `-`.
+
+### List labels (system + user-defined)
+
+```sh
+curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  "https://gmail.googleapis.com/gmail/v1/users/me/labels" \
+  | jq '.labels[] | {id, name, type, color: .color.backgroundColor}'
+```
+
+The system labels are `INBOX`, `SENT`, `DRAFT`, `IMPORTANT`, `UNREAD`,
+`STARRED`, `SPAM`, `TRASH`, plus `CATEGORY_*` (Personal / Social /
+Promotions / Updates / Forums).
+
+### Filter by label
+
+```sh
+LABEL_ID='Label_4'  # from labels.list above
+curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  --get "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
+  --data-urlencode "labelIds=$LABEL_ID" \
+  --data-urlencode 'maxResults=20' \
+  | jq '.messages // []'
+```
+
+Multiple `labelIds` query params behave like AND.
+
+### Download an attachment
+
+```sh
+MSG_ID='18f1a2b3c4d5e6f0'
+
+# 1. find the attachment leaf
+RESP=$(curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  --get "https://gmail.googleapis.com/gmail/v1/users/me/messages/$MSG_ID" \
+  --data-urlencode 'format=full')
+
+echo "$RESP" | jq '
+  def walk(p):
+    if (p.parts // null) then (p.parts | map(walk(.)) | add) else [p] end;
+  walk(.payload)
+  | map(select(.body.attachmentId? != null))
+  | .[] | {filename, mimeType, attachmentId: .body.attachmentId, size: .body.size}'
+
+# 2. fetch the attachment by id
+ATT_ID='ANGjdJ-abc123'
+OUT=/tmp/attachment.bin
+curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+  "https://gmail.googleapis.com/gmail/v1/users/me/messages/$MSG_ID/attachments/$ATT_ID" \
+  | jq -r .data | tr '_-' '/+' | base64 -d > "$OUT"
+file "$OUT"
+```
+
+### Pagination
+
+```sh
+PAGE_TOKEN=''
+while : ; do
+  RESP=$(curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
+    --get "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
+    --data-urlencode 'q=in:inbox' \
+    --data-urlencode 'maxResults=100' \
+    ${PAGE_TOKEN:+--data-urlencode "pageToken=$PAGE_TOKEN"})
+  echo "$RESP" | jq -c '.messages[]?'
+  PAGE_TOKEN=$(echo "$RESP" | jq -r '.nextPageToken // empty')
+  [ -z "$PAGE_TOKEN" ] && break
+done
+```
+
+## Common error codes
+
+| HTTP | meaning | what to tell the user |
+|---|---|---|
+| `401 UNAUTHENTICATED` | token expired / revoked | "Reconnect the Gmail connector on the Connections page." |
+| `403 insufficientPermissions` | scope missing | "This connector grants only read access — modifying mail isn't possible." |
+| `403 userRateLimitExceeded` / `429` | quota / throttling | back off ~5s, then retry once. |
+| `404 notFound` | wrong message / thread / attachment id | double-check the id, or fall back to `messages.list` with the right query. |
+| `400 invalidQuery` | malformed `q` | print the `q` you sent + the error back to the user. |
+
+Never log or echo `$GOOGLE_GMAIL_TOKEN` — treat it as a secret.

package/skills/google-tasks/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: google-tasks
+description: Read Google Tasks task lists and individual tasks via the Tasks v1 REST API. Use when the user mentions Google Tasks, todo / pending / overdue tasks, weekly task recap, or grouping todos by list.
+when_to_use: |
+  Trigger when the user wants to inspect their Google Tasks — list
+  task lists, surface pending items, group by due date, or pull
+  details for one task. The installed connector grants read-only
+  scope (`tasks.readonly`); creating / updating / deleting tasks is
+  out of scope.
+connections: [google/tasks]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Drive Google Tasks via `curl + jq`. The user's OAuth bearer token is
+in `$GOOGLE_TASKS_TOKEN`; every call needs it as
+`Authorization: Bearer $GOOGLE_TASKS_TOKEN`. The token already
+carries the `tasks.readonly` scope the user agreed to at install plus
+the identity scopes (`openid email profile`).
+
+The Tasks API returns standard JSON; failures surface as
+`{"error": {"code": 401|403|..., "message": "..."}}` — show that
+error verbatim. `401` means the token expired (re-install). `403
+insufficientPermissions` means the user is asking for a write this
+connector cannot satisfy — say so.
+
+**Always start with `users/@me/lists`** to discover which task lists
+the account has — the user's default plus any extras they created on
+calendar.google.com or in the Tasks app.
+
+## Recipes
+
+### Verify auth + list all task lists (always run first)
+
+```sh
+curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
+  | jq '.items[] | {id, title, updated}'
+```
+
+The default list is usually titled "我的任务" / "My Tasks" but the
+**id** (a long opaque string like `MTAxMjM0NTY3OA`) is what every
+subsequent `lists/{id}/tasks` call needs.
+
+### List all unfinished tasks across every list
+
+```sh
+curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
+  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
+    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
+      --data-urlencode 'showCompleted=false' \
+      --data-urlencode 'maxResults=100' \
+      | jq --arg list "$LIST_TITLE" '.items[]? | {list: $list, title, due, status, notes}'
+  done | jq -s '. | sort_by(.due // "9999")'
+```
+
+`showCompleted=false` filters out done items at the API level. The
+default `showCompleted=true&showHidden=false` returns done tasks too.
+
+### Pending tasks in one specific list, sorted by due date
+
+```sh
+LIST_ID='MTAxMjM0NTY3OA'
+curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
+  --data-urlencode 'showCompleted=false' \
+  --data-urlencode 'maxResults=100' \
+  | jq '.items // [] | sort_by(.due // "9999") | .[] | {title, due, notes, status, position}'
+```
+
+`position` is the user's drag-to-reorder rank inside the list — useful
+when the user says "what's at the top of my tasks". Tasks without a
+`due` field are open-ended.
+
+### Tasks due today
+
+```sh
+TODAY=$(date -u +%Y-%m-%d)
+TOMORROW=$(date -u -d "+1 day" +%Y-%m-%d 2>/dev/null \
+  || date -u -v+1d +%Y-%m-%d)
+TODAY_START="${TODAY}T00:00:00.000Z"
+TOMORROW_START="${TOMORROW}T00:00:00.000Z"
+
+curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
+  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
+    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
+      --data-urlencode "dueMin=$TODAY_START" \
+      --data-urlencode "dueMax=$TOMORROW_START" \
+      --data-urlencode 'showCompleted=false' \
+      | jq --arg list "$LIST_TITLE" '.items[]? | {list: $list, title, due, notes}'
+  done | jq -s
+```
+
+`dueMin` / `dueMax` are RFC 3339 timestamps. The Tasks API stores
+`due` at midnight UTC, so the local-day window is approximate around
+the date boundary — that's fine for "due today" semantics, mention
+the caveat only if the user pushes back.
+
+### Overdue tasks (everything still pending with a due date in the past)
+
+```sh
+NOW=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
+  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
+    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
+      --data-urlencode "dueMax=$NOW" \
+      --data-urlencode 'showCompleted=false' \
+      | jq --arg list "$LIST_TITLE" '.items[]? | {list: $list, title, due, daysOverdue: (((now * 1000) - (.due | sub("Z"; "+00:00") | fromdateiso8601 * 1000)) / 86400000 | floor)}'
+  done | jq -s
+```
+
+### Recently completed tasks (this week, for a recap)
+
+```sh
+ONE_WEEK_AGO=$(date -u -d "-7 days" +%Y-%m-%dT%H:%M:%S.000Z 2>/dev/null \
+  || date -u -v-7d +%Y-%m-%dT%H:%M:%S.000Z)
+
+curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
+  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
+    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
+      --data-urlencode 'showCompleted=true' \
+      --data-urlencode 'showHidden=true' \
+      --data-urlencode "completedMin=$ONE_WEEK_AGO" \
+      | jq --arg list "$LIST_TITLE" '.items[]? | select(.status=="completed") | {list: $list, title, completed}'
+  done | jq -s '. | sort_by(.completed)'
+```
+
+`completedMin` / `completedMax` mirror `dueMin`/`Max` and only apply
+to tasks already moved to the "completed" state. You **must** pass
+`showCompleted=true` AND `showHidden=true` to see them — Google hides
+completed tasks from the default list.
+
+### Get one task's details
+
+```sh
+LIST_ID='MTAxMjM0NTY3OA'
+TASK_ID='dGFza0lkRXhhbXBsZQ'
+curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
+  | jq '{title, due, status, notes, completed, position, links: .links}'
+```
+
+`links` exposes the user's manual hyperlinks (e.g. an attached email
+or Drive doc) — render them as a list to the user when present.
+
+### Pagination
+
+`maxResults` caps at 100 per page. Use `nextPageToken`:
+
+```sh
+LIST_ID='MTAxMjM0NTY3OA'
+PAGE_TOKEN=''
+while : ; do
+  RESP=$(curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
+    --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
+    --data-urlencode 'maxResults=100' \
+    --data-urlencode 'showCompleted=false' \
+    ${PAGE_TOKEN:+--data-urlencode "pageToken=$PAGE_TOKEN"})
+  echo "$RESP" | jq -c '.items[]?'
+  PAGE_TOKEN=$(echo "$RESP" | jq -r '.nextPageToken // empty')
+  [ -z "$PAGE_TOKEN" ] && break
+done
+```
+
+## Common error codes
+
+| HTTP | meaning | what to tell the user |
+|---|---|---|
+| `401 UNAUTHENTICATED` | token expired / revoked | "Reconnect the Google Tasks connector on the Connections page." |
+| `403 insufficientPermissions` | scope missing | "This connector is read-only — adding or completing tasks isn't possible." |
+| `404 notFound` | wrong list / task id | re-list with `users/@me/lists` to find the right id. |
+| `429 quotaExceeded` | quota / throttling | back off ~5s, then retry once. |
+
+Never log or echo `$GOOGLE_TASKS_TOKEN` — treat it as a secret.