feat(mcp): add bounded Gmail exports and scoped Calendar tools

.agents/skills/gog-gmail/SKILL.md

@@ -33,6 +33,7 @@ gog --readonly --account user@example.com gmail search 'newer_than:7d' --max 10
 | `autoreply` | Reply once to matching messages |
 | `batch` | Batch operations (permanent delete requires broader Gmail scope; use gmail trash for normal trashing) |
 | `drafts` | Draft operations |
+| `export` | Export bounded exact message or attachment bytes |
 | `forward` | Forward a message to new recipients |
 | `get` | Get a message (full\|metadata\|raw) |
 | `history` | Gmail history |

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## 0.43.1 - Unreleased
 
+- MCP: add bounded exact Gmail exports, compact paged thread reads, typed Calendar and Gmail settings tools, independent notification/settings-delete/Calendar-delete gates, private snapshots and non-retryable mutation receipts. Add a verified export client example and migration guidance. (#1181) — thanks @salmonumbrella.
+- Gmail/Calendar: add atomic exact-byte exports, metadata-only thread enumeration, compact search, literal array flags, Calendar search pagination and explicit source PATCH fields. (#1181) — thanks @salmonumbrella.
+
 ## 0.43.0 - 2026-09-30
 
 **Highlights:** JSON error envelopes and page metadata, a default auth/config status view, and clearer Gmail MIME guidance.

docs/commands.generated.md

@@ -456,6 +456,9 @@ Generated from `gog schema --json`.
       - [`gog gmail (mail,email) drafts (draft) reply-all (replyall) <messageId> [flags]`](commands/gog-gmail-drafts-reply-all.md) - Save a reply-all as a draft
       - [`gog gmail (mail,email) drafts (draft) send (post) <draftId>`](commands/gog-gmail-drafts-send.md) - Send a draft
       - [`gog gmail (mail,email) drafts (draft) update (edit,set) <draftId> [flags]`](commands/gog-gmail-drafts-update.md) - Update a draft
+    - [`gog gmail (mail,email) export <command>`](commands/gog-gmail-export.md) - Export bounded exact message or attachment bytes
+      - [`gog gmail (mail,email) export attachment --out=STRING <messageId> <attachmentId> [flags]`](commands/gog-gmail-export-attachment.md) - Export exact attachment bytes to a file
+      - [`gog gmail (mail,email) export raw --out=STRING <messageId> [flags]`](commands/gog-gmail-export-raw.md) - Export exact raw message bytes to a file
     - [`gog gmail (mail,email) forward (fwd) <messageId> [flags]`](commands/gog-gmail-forward.md) - Forward a message to new recipients
     - [`gog gmail (mail,email) get (info,show) <messageId> [flags]`](commands/gog-gmail-get.md) - Get a message (full|metadata|raw)
     - [`gog gmail (mail,email) history [flags]`](commands/gog-gmail-history.md) - Gmail history
@@ -517,6 +520,7 @@ Generated from `gog schema --json`.
     - [`gog gmail (mail,email) thread (threads,read) <command>`](commands/gog-gmail-thread.md) - Thread operations (get, modify)
       - [`gog gmail (mail,email) thread (threads,read) attachments (files) <threadId> [flags]`](commands/gog-gmail-thread-attachments.md) - List all attachments in a thread
       - [`gog gmail (mail,email) thread (threads,read) get (info,show) <threadId> [flags]`](commands/gog-gmail-thread-get.md) - Get a thread with all messages (optionally download attachments)
+      - [`gog gmail (mail,email) thread (threads,read) ids <threadId>`](commands/gog-gmail-thread-ids.md) - Read bounded ordered message metadata without bodies or attachments
       - [`gog gmail (mail,email) thread (threads,read) modify (update,edit,set) <threadId> [flags]`](commands/gog-gmail-thread-modify.md) - Modify labels on all messages in a thread
     - [`gog gmail (mail,email) track <command>`](commands/gog-gmail-track.md) - Email open tracking
       - [`gog gmail (mail,email) track key <command>`](commands/gog-gmail-track-key.md) - Manage tracking encryption keys

docs/commands/README.md

@@ -2,7 +2,7 @@
 
 Every `gog` command has a generated docs page. The source of truth is the live CLI schema; run `make docs-commands` after changing command names, flags, help text, aliases, or arguments.
 
-Generated pages: 775.
+Generated pages: 779.
 
 ## Top-level Commands
 
@@ -510,6 +510,9 @@ Generated pages: 775.
       - [gog gmail drafts reply-all](gog-gmail-drafts-reply-all.md) - Save a reply-all as a draft
       - [gog gmail drafts send](gog-gmail-drafts-send.md) - Send a draft
       - [gog gmail drafts update](gog-gmail-drafts-update.md) - Update a draft
+    - [gog gmail export](gog-gmail-export.md) - Export bounded exact message or attachment bytes
+      - [gog gmail export attachment](gog-gmail-export-attachment.md) - Export exact attachment bytes to a file
+      - [gog gmail export raw](gog-gmail-export-raw.md) - Export exact raw message bytes to a file
     - [gog gmail forward](gog-gmail-forward.md) - Forward a message to new recipients
     - [gog gmail get](gog-gmail-get.md) - Get a message (full|metadata|raw)
     - [gog gmail history](gog-gmail-history.md) - Gmail history
@@ -571,6 +574,7 @@ Generated pages: 775.
     - [gog gmail thread](gog-gmail-thread.md) - Thread operations (get, modify)
       - [gog gmail thread attachments](gog-gmail-thread-attachments.md) - List all attachments in a thread
       - [gog gmail thread get](gog-gmail-thread-get.md) - Get a thread with all messages (optionally download attachments)
+      - [gog gmail thread ids](gog-gmail-thread-ids.md) - Read bounded ordered message metadata without bodies or attachments
       - [gog gmail thread modify](gog-gmail-thread-modify.md) - Modify labels on all messages in a thread
     - [gog gmail track](gog-gmail-track.md) - Email open tracking
       - [gog gmail track key](gog-gmail-track-key.md) - Manage tracking encryption keys

docs/commands/gog-calendar-create.md

@@ -22,6 +22,8 @@ gog calendar (cal) create (add,new) <calendarId> [flags]
 | `-a`<br>`--account`<br>`--acct` | `string` |  | Account email, alias, or auto for authenticated Google API commands |
 | `--all-day` | `bool` |  | All-day event (use date-only in --from/--to) |
 | `--attachment` | `[]string` |  | File attachment URL (can be repeated) |
+| `--attachment-url` | `[]string` |  | Literal attachment URL (repeatable; commas preserved) |
+| `--attendee-entry` | `[]string` |  | Literal attendee email with optional modifiers (repeatable; commas preserved) |
 | `--attendees` | `string` |  | Comma-separated attendee emails; modifiers: ;optional, ;resource, ;comment=TEXT |
 | `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
 | `--color` | `string` | auto | Color output: auto\|always\|never |
@@ -60,6 +62,7 @@ gog calendar (cal) create (add,new) <calendarId> [flags]
 | `--quota-project` | `string` |  | Google Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC) |
 | `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--reminder` | `[]string` |  | Custom reminders as method:duration (e.g., popup:30m, email:1d). Can be repeated (max 5). |
+| `--reminder-entry` | `[]string` |  | Literal reminder method:duration (repeatable; max 5) |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
 | `--rrule` | `[]string` |  | Recurrence rules (e.g., 'RRULE:FREQ=MONTHLY;BYMONTHDAY=11'). Can be repeated. |
 | `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |

docs/commands/gog-calendar-freebusy.md

@@ -22,6 +22,7 @@ gog calendar (cal) freebusy [<calendarIds>] [flags]
 | `-a`<br>`--account`<br>`--acct` | `string` |  | Account email, alias, or auto for authenticated Google API commands |
 | `--all` | `bool` |  | Query all calendars |
 | `--cal` | `[]string` |  | Calendar ID, name, or index (can be repeated) |
+| `--calendar-id` | `[]string` |  | Literal calendar selector; commas are preserved (repeatable) |
 | `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
 | `--color` | `string` | auto | Color output: auto\|always\|never |
 | `--disable-commands` | `string` |  | Comma-separated list of disabled commands; dot paths allowed |

docs/commands/gog-calendar-respond.md

@@ -38,6 +38,7 @@ gog calendar (cal) respond (rsvp,reply) <calendarId> <eventId> [flags]
 | `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
 | `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
+| `--send-updates` | `string` |  | Notification mode: all, externalOnly, none |
 | `--status` | `string` |  | Response status (accepted, declined, tentative, needsAction) |
 | `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
 | `--version` | `kong.VersionFlag` |  | Print version and exit |

docs/commands/gog-calendar-search.md

@@ -36,6 +36,7 @@ gog calendar (cal) search (find,query) <query> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--max`<br>`--limit` | `int64` | 25 | Max results |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `--page`<br>`--cursor` | `string` |  | Provider page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--quota-project` | `string` |  | Google Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC) |
 | `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |

docs/commands/gog-calendar-update.md

@@ -21,8 +21,11 @@ gog calendar (cal) update (edit,set) <calendarId> <eventId> [flags]
 | `--access-token` | `string` |  | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
 | `-a`<br>`--account`<br>`--acct` | `string` |  | Account email, alias, or auto for authenticated Google API commands |
 | `--add-attendee` | `string` |  | Comma-separated attendee emails to add (preserves existing attendees); modifiers: ;optional, ;resource, ;comment=TEXT |
+| `--add-attendee-entry` | `[]string` |  | Literal attendee to add (repeatable; commas preserved) |
 | `--all-day` | `bool` |  | All-day event (use date-only in --from/--to) |
 | `--attachment` | `[]string` |  | File attachment URL (can be repeated; replaces all; set empty to clear) |
+| `--attachment-url` | `[]string` |  | Literal attachment URL (repeatable; commas preserved) |
+| `--attendee-entry` | `[]string` |  | Literal attendee email with optional modifiers (repeatable; commas preserved) |
 | `--attendees` | `string` |  | Comma-separated attendee emails (replaces all; set empty to clear); modifiers: ;optional, ;resource, ;comment=TEXT |
 | `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
 | `--color` | `string` | auto | Color output: auto\|always\|never |
@@ -64,13 +67,16 @@ gog calendar (cal) update (edit,set) <calendarId> <eventId> [flags]
 | `--regenerate-meet` | `bool` |  | Replace the event's Google Meet video conference |
 | `--regenerate-zoom` | `bool` |  | Replace the event's Zoom video conference |
 | `--reminder` | `[]string` |  | Custom reminders as method:duration (e.g., popup:30m, email:1d). Can be repeated (max 5). Set empty to restore calendar defaults. |
+| `--reminder-entry` | `[]string` |  | Literal reminder method:duration (repeatable; max 5) |
 | `--remove-zoom` | `bool` |  | Remove the event's Zoom video conference |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
 | `--rrule` | `[]string` |  | Recurrence rules (e.g., 'RRULE:FREQ=MONTHLY;BYMONTHDAY=11'). Can be repeated. Set empty to clear. |
 | `--scope` | `string` | all | For recurring events: single, future, all |
 | `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
 | `--send-updates` | `string` |  | Notification mode: all, externalOnly, none (default: none) |
 | `--shared-prop` | `[]string` |  | Shared extended property (key=value, can be repeated) |
+| `--source-title` | `string` |  | New source title (set empty to clear title) |
+| `--source-url` | `string` |  | New source URL (set empty to clear source) |
 | `--start-timezone`<br>`--from-timezone` | `string` |  | IANA timezone metadata for --from (e.g., Europe/Rome) |
 | `--summary` | `string` |  | New summary/title (set empty to clear) |
 | `--to` | `string` |  | New end time (RFC3339; set empty to clear) |

docs/commands/gog-gmail-export-attachment.md

@@ -0,0 +1,49 @@
+# `gog gmail export attachment`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Export exact attachment bytes to a file
+
+## Usage
+
+```bash
+gog gmail (mail,email) export attachment --out=STRING <messageId> <attachmentId> [flags]
+```
+
+## Parent
+
+- [gog gmail export](gog-gmail-export.md)
+
+## Flags
+
+| Flag | Type | Default | Help |
+| --- | --- | --- | --- |
+| `--access-token` | `string` |  | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
+| `-a`<br>`--account`<br>`--acct` | `string` |  | Account email, alias, or auto for authenticated Google API commands |
+| `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
+| `--color` | `string` | auto | Color output: auto\|always\|never |
+| `--disable-commands` | `string` |  | Comma-separated list of disabled commands; dot paths allowed |
+| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` |  | Do not make changes; print intended actions and exit successfully |
+| `--enable-commands` | `string` |  | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
+| `--enable-commands-exact` | `string` |  | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
+| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` |  | Skip confirmations for destructive commands |
+| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
+| `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
+| `--home` | `string` |  | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
+| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
+| `--max-bytes` | `int64` | 52428800 | Decoded byte limit (1..52428800) |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `--out` | `string` |  | Destination file (written atomically) |
+| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--quota-project` | `string` |  | Google Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
+| `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
+| `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
+| `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
+| `--version` | `kong.VersionFlag` |  | Print version and exit |
+| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
+
+## See Also
+
+- [gog gmail export](gog-gmail-export.md)
+- [Command index](README.md)

docs/commands/gog-gmail-export-raw.md

@@ -0,0 +1,49 @@
+# `gog gmail export raw`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Export exact raw message bytes to a file
+
+## Usage
+
+```bash
+gog gmail (mail,email) export raw --out=STRING <messageId> [flags]
+```
+
+## Parent
+
+- [gog gmail export](gog-gmail-export.md)
+
+## Flags
+
+| Flag | Type | Default | Help |
+| --- | --- | --- | --- |
+| `--access-token` | `string` |  | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
+| `-a`<br>`--account`<br>`--acct` | `string` |  | Account email, alias, or auto for authenticated Google API commands |
+| `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
+| `--color` | `string` | auto | Color output: auto\|always\|never |
+| `--disable-commands` | `string` |  | Comma-separated list of disabled commands; dot paths allowed |
+| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` |  | Do not make changes; print intended actions and exit successfully |
+| `--enable-commands` | `string` |  | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
+| `--enable-commands-exact` | `string` |  | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
+| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` |  | Skip confirmations for destructive commands |
+| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
+| `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
+| `--home` | `string` |  | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
+| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
+| `--max-bytes` | `int64` | 52428800 | Decoded byte limit (1..52428800) |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `--out` | `string` |  | Destination file (written atomically) |
+| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--quota-project` | `string` |  | Google Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
+| `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
+| `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
+| `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
+| `--version` | `kong.VersionFlag` |  | Print version and exit |
+| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
+
+## See Also
+
+- [gog gmail export](gog-gmail-export.md)
+- [Command index](README.md)