From 96cbf740695685c9541ab0e540820a4b3d13b627 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 21 Jun 2026 23:53:22 -0400
Subject: [PATCH 1/7] feat(safety): enforce runtime read-only mode

---
 CHANGELOG.md                                  |   1 +
 README.md                                     |   2 +
 docs/automation.md                            |  15 +++
 docs/commands/gog-admin-groups-list.md        |   1 +
 docs/commands/gog-admin-groups-members-add.md |   1 +
 .../commands/gog-admin-groups-members-list.md |   1 +
 .../gog-admin-groups-members-remove.md        |   1 +
 docs/commands/gog-admin-groups-members.md     |   1 +
 docs/commands/gog-admin-groups.md             |   1 +
 docs/commands/gog-admin-orgunits-create.md    |   1 +
 docs/commands/gog-admin-orgunits-delete.md    |   1 +
 docs/commands/gog-admin-orgunits-get.md       |   1 +
 docs/commands/gog-admin-orgunits-list.md      |   1 +
 docs/commands/gog-admin-orgunits-update.md    |   1 +
 docs/commands/gog-admin-orgunits.md           |   1 +
 docs/commands/gog-admin-users-create.md       |   1 +
 docs/commands/gog-admin-users-delete.md       |   1 +
 docs/commands/gog-admin-users-get.md          |   1 +
 docs/commands/gog-admin-users-list.md         |   1 +
 docs/commands/gog-admin-users-suspend.md      |   1 +
 docs/commands/gog-admin-users.md              |   1 +
 docs/commands/gog-admin.md                    |   1 +
 docs/commands/gog-analytics-accounts.md       |   1 +
 docs/commands/gog-analytics-report.md         |   1 +
 docs/commands/gog-analytics.md                |   1 +
 docs/commands/gog-appscript-content.md        |   1 +
 docs/commands/gog-appscript-create.md         |   1 +
 docs/commands/gog-appscript-get.md            |   1 +
 docs/commands/gog-appscript-run.md            |   1 +
 docs/commands/gog-appscript.md                |   1 +
 docs/commands/gog-auth-add.md                 |   2 +-
 docs/commands/gog-auth-alias-list.md          |   1 +
 docs/commands/gog-auth-alias-set.md           |   1 +
 docs/commands/gog-auth-alias-unset.md         |   1 +
 docs/commands/gog-auth-alias.md               |   1 +
 docs/commands/gog-auth-credentials-list.md    |   1 +
 docs/commands/gog-auth-credentials-remove.md  |   1 +
 docs/commands/gog-auth-credentials-set.md     |   1 +
 docs/commands/gog-auth-credentials.md         |   1 +
 docs/commands/gog-auth-doctor.md              |   1 +
 docs/commands/gog-auth-import.md              |   1 +
 docs/commands/gog-auth-keep.md                |   1 +
 docs/commands/gog-auth-keyring.md             |   1 +
 docs/commands/gog-auth-list.md                |   1 +
 docs/commands/gog-auth-manage.md              |   1 +
 docs/commands/gog-auth-remove.md              |   1 +
 docs/commands/gog-auth-service-account-set.md |   1 +
 .../gog-auth-service-account-status.md        |   1 +
 .../gog-auth-service-account-unset.md         |   1 +
 docs/commands/gog-auth-service-account.md     |   1 +
 docs/commands/gog-auth-services.md            |   1 +
 docs/commands/gog-auth-status.md              |   1 +
 docs/commands/gog-auth-tokens-delete.md       |   1 +
 docs/commands/gog-auth-tokens-export.md       |   1 +
 docs/commands/gog-auth-tokens-import.md       |   1 +
 docs/commands/gog-auth-tokens-list.md         |   1 +
 docs/commands/gog-auth-tokens.md              |   1 +
 docs/commands/gog-auth.md                     |   1 +
 docs/commands/gog-backup-cat.md               |   1 +
 docs/commands/gog-backup-export.md            |   1 +
 docs/commands/gog-backup-gmail-push.md        |   1 +
 docs/commands/gog-backup-gmail.md             |   1 +
 docs/commands/gog-backup-init.md              |   1 +
 docs/commands/gog-backup-push.md              |   1 +
 docs/commands/gog-backup-status.md            |   1 +
 docs/commands/gog-backup-verify.md            |   1 +
 docs/commands/gog-backup.md                   |   1 +
 docs/commands/gog-batch-abort.md              |   1 +
 docs/commands/gog-batch-begin.md              |   1 +
 docs/commands/gog-batch-end.md                |   1 +
 docs/commands/gog-batch-list.md               |   1 +
 docs/commands/gog-batch-prune.md              |   1 +
 docs/commands/gog-batch-show.md               |   1 +
 docs/commands/gog-batch.md                    |   1 +
 docs/commands/gog-calendar-acl.md             |   1 +
 docs/commands/gog-calendar-alias-list.md      |   1 +
 docs/commands/gog-calendar-alias-set.md       |   1 +
 docs/commands/gog-calendar-alias-unset.md     |   1 +
 docs/commands/gog-calendar-alias.md           |   1 +
 docs/commands/gog-calendar-calendars.md       |   1 +
 docs/commands/gog-calendar-colors.md          |   1 +
 docs/commands/gog-calendar-conflicts.md       |   1 +
 docs/commands/gog-calendar-create-calendar.md |   1 +
 docs/commands/gog-calendar-create.md          |   1 +
 docs/commands/gog-calendar-delete-calendar.md |   1 +
 docs/commands/gog-calendar-delete.md          |   1 +
 docs/commands/gog-calendar-event.md           |   1 +
 docs/commands/gog-calendar-events.md          |   1 +
 docs/commands/gog-calendar-focus-time.md      |   1 +
 docs/commands/gog-calendar-freebusy.md        |   1 +
 docs/commands/gog-calendar-move.md            |   1 +
 docs/commands/gog-calendar-out-of-office.md   |   1 +
 docs/commands/gog-calendar-propose-time.md    |   1 +
 docs/commands/gog-calendar-raw.md             |   1 +
 docs/commands/gog-calendar-respond.md         |   1 +
 docs/commands/gog-calendar-search.md          |   1 +
 docs/commands/gog-calendar-subscribe.md       |   1 +
 docs/commands/gog-calendar-team.md            |   1 +
 docs/commands/gog-calendar-time.md            |   1 +
 docs/commands/gog-calendar-unsubscribe.md     |   1 +
 docs/commands/gog-calendar-update.md          |   1 +
 docs/commands/gog-calendar-users.md           |   1 +
 .../commands/gog-calendar-working-location.md |   1 +
 docs/commands/gog-calendar.md                 |   1 +
 docs/commands/gog-chat-dm-send.md             |   1 +
 docs/commands/gog-chat-dm-space.md            |   1 +
 docs/commands/gog-chat-dm.md                  |   1 +
 docs/commands/gog-chat-messages-list.md       |   1 +
 docs/commands/gog-chat-messages-react.md      |   1 +
 .../gog-chat-messages-reactions-create.md     |   1 +
 .../gog-chat-messages-reactions-delete.md     |   1 +
 .../gog-chat-messages-reactions-list.md       |   1 +
 docs/commands/gog-chat-messages-reactions.md  |   1 +
 docs/commands/gog-chat-messages-send.md       |   1 +
 docs/commands/gog-chat-messages.md            |   1 +
 docs/commands/gog-chat-spaces-create.md       |   1 +
 docs/commands/gog-chat-spaces-find.md         |   1 +
 docs/commands/gog-chat-spaces-list.md         |   1 +
 docs/commands/gog-chat-spaces.md              |   1 +
 docs/commands/gog-chat-threads-list.md        |   1 +
 docs/commands/gog-chat-threads.md             |   1 +
 docs/commands/gog-chat.md                     |   1 +
 .../gog-classroom-announcements-assignees.md  |   1 +
 .../gog-classroom-announcements-create.md     |   1 +
 .../gog-classroom-announcements-delete.md     |   1 +
 .../gog-classroom-announcements-get.md        |   1 +
 .../gog-classroom-announcements-list.md       |   1 +
 .../gog-classroom-announcements-update.md     |   1 +
 docs/commands/gog-classroom-announcements.md  |   1 +
 .../commands/gog-classroom-courses-archive.md |   1 +
 docs/commands/gog-classroom-courses-create.md |   1 +
 docs/commands/gog-classroom-courses-delete.md |   1 +
 docs/commands/gog-classroom-courses-get.md    |   1 +
 docs/commands/gog-classroom-courses-join.md   |   1 +
 docs/commands/gog-classroom-courses-leave.md  |   1 +
 docs/commands/gog-classroom-courses-list.md   |   1 +
 .../gog-classroom-courses-unarchive.md        |   1 +
 docs/commands/gog-classroom-courses-update.md |   1 +
 docs/commands/gog-classroom-courses-url.md    |   1 +
 docs/commands/gog-classroom-courses.md        |   1 +
 .../gog-classroom-coursework-assignees.md     |   1 +
 .../gog-classroom-coursework-create.md        |   1 +
 .../gog-classroom-coursework-delete.md        |   1 +
 docs/commands/gog-classroom-coursework-get.md |   1 +
 .../commands/gog-classroom-coursework-list.md |   1 +
 .../gog-classroom-coursework-update.md        |   1 +
 docs/commands/gog-classroom-coursework.md     |   1 +
 ...g-classroom-guardian-invitations-create.md |   1 +
 .../gog-classroom-guardian-invitations-get.md |   1 +
 ...gog-classroom-guardian-invitations-list.md |   1 +
 .../gog-classroom-guardian-invitations.md     |   1 +
 .../gog-classroom-guardians-delete.md         |   1 +
 docs/commands/gog-classroom-guardians-get.md  |   1 +
 docs/commands/gog-classroom-guardians-list.md |   1 +
 docs/commands/gog-classroom-guardians.md      |   1 +
 .../gog-classroom-invitations-accept.md       |   1 +
 .../gog-classroom-invitations-create.md       |   1 +
 .../gog-classroom-invitations-delete.md       |   1 +
 .../commands/gog-classroom-invitations-get.md |   1 +
 .../gog-classroom-invitations-list.md         |   1 +
 docs/commands/gog-classroom-invitations.md    |   1 +
 .../gog-classroom-materials-create.md         |   1 +
 .../gog-classroom-materials-delete.md         |   1 +
 docs/commands/gog-classroom-materials-get.md  |   1 +
 docs/commands/gog-classroom-materials-list.md |   1 +
 .../gog-classroom-materials-update.md         |   1 +
 docs/commands/gog-classroom-materials.md      |   1 +
 docs/commands/gog-classroom-profile-get.md    |   1 +
 docs/commands/gog-classroom-profile.md        |   1 +
 docs/commands/gog-classroom-roster.md         |   1 +
 docs/commands/gog-classroom-students-add.md   |   1 +
 docs/commands/gog-classroom-students-get.md   |   1 +
 docs/commands/gog-classroom-students-list.md  |   1 +
 .../commands/gog-classroom-students-remove.md |   1 +
 docs/commands/gog-classroom-students.md       |   1 +
 .../commands/gog-classroom-submissions-get.md |   1 +
 .../gog-classroom-submissions-grade.md        |   1 +
 .../gog-classroom-submissions-list.md         |   1 +
 .../gog-classroom-submissions-reclaim.md      |   1 +
 .../gog-classroom-submissions-return.md       |   1 +
 .../gog-classroom-submissions-turn-in.md      |   1 +
 docs/commands/gog-classroom-submissions.md    |   1 +
 docs/commands/gog-classroom-teachers-add.md   |   1 +
 docs/commands/gog-classroom-teachers-get.md   |   1 +
 docs/commands/gog-classroom-teachers-list.md  |   1 +
 .../commands/gog-classroom-teachers-remove.md |   1 +
 docs/commands/gog-classroom-teachers.md       |   1 +
 docs/commands/gog-classroom-topics-create.md  |   1 +
 docs/commands/gog-classroom-topics-delete.md  |   1 +
 docs/commands/gog-classroom-topics-get.md     |   1 +
 docs/commands/gog-classroom-topics-list.md    |   1 +
 docs/commands/gog-classroom-topics-update.md  |   1 +
 docs/commands/gog-classroom-topics.md         |   1 +
 docs/commands/gog-classroom.md                |   1 +
 docs/commands/gog-completion.md               |   1 +
 docs/commands/gog-config-get.md               |   1 +
 docs/commands/gog-config-keys.md              |   1 +
 docs/commands/gog-config-list.md              |   1 +
 docs/commands/gog-config-no-send-list.md      |   1 +
 docs/commands/gog-config-no-send-remove.md    |   1 +
 docs/commands/gog-config-no-send-set.md       |   1 +
 docs/commands/gog-config-no-send.md           |   1 +
 docs/commands/gog-config-path.md              |   1 +
 docs/commands/gog-config-set.md               |   1 +
 docs/commands/gog-config-unset.md             |   1 +
 docs/commands/gog-config.md                   |   1 +
 docs/commands/gog-contacts-create.md          |   1 +
 docs/commands/gog-contacts-dedupe.md          |   1 +
 docs/commands/gog-contacts-delete.md          |   1 +
 docs/commands/gog-contacts-directory-list.md  |   1 +
 .../commands/gog-contacts-directory-search.md |   1 +
 docs/commands/gog-contacts-directory.md       |   1 +
 docs/commands/gog-contacts-export.md          |   1 +
 docs/commands/gog-contacts-get.md             |   1 +
 docs/commands/gog-contacts-list.md            |   1 +
 docs/commands/gog-contacts-other-list.md      |   1 +
 docs/commands/gog-contacts-other-search.md    |   1 +
 docs/commands/gog-contacts-other.md           |   1 +
 docs/commands/gog-contacts-raw.md             |   1 +
 docs/commands/gog-contacts-search.md          |   1 +
 docs/commands/gog-contacts-update.md          |   1 +
 docs/commands/gog-contacts.md                 |   1 +
 docs/commands/gog-docs-add-tab.md             |   1 +
 docs/commands/gog-docs-cat.md                 |   1 +
 docs/commands/gog-docs-cell-style.md          |   1 +
 docs/commands/gog-docs-cell-update.md         |   1 +
 docs/commands/gog-docs-clear.md               |   1 +
 docs/commands/gog-docs-comments-add.md        |   1 +
 docs/commands/gog-docs-comments-delete.md     |   1 +
 docs/commands/gog-docs-comments-get.md        |   1 +
 docs/commands/gog-docs-comments-list.md       |   1 +
 docs/commands/gog-docs-comments-locate.md     |   1 +
 docs/commands/gog-docs-comments-poll.md       |   1 +
 docs/commands/gog-docs-comments-reopen.md     |   1 +
 docs/commands/gog-docs-comments-reply.md      |   1 +
 docs/commands/gog-docs-comments-resolve.md    |   1 +
 docs/commands/gog-docs-comments.md            |   1 +
 docs/commands/gog-docs-copy.md                |   1 +
 docs/commands/gog-docs-create.md              |   1 +
 docs/commands/gog-docs-delete-tab.md          |   1 +
 docs/commands/gog-docs-delete.md              |   1 +
 docs/commands/gog-docs-edit.md                |   1 +
 docs/commands/gog-docs-export.md              |   1 +
 docs/commands/gog-docs-find-range.md          |   1 +
 docs/commands/gog-docs-find-replace.md        |   1 +
 docs/commands/gog-docs-footer-create.md       |   1 +
 docs/commands/gog-docs-footer-delete.md       |   1 +
 docs/commands/gog-docs-footer-list.md         |   1 +
 docs/commands/gog-docs-footer.md              |   1 +
 docs/commands/gog-docs-format.md              |   1 +
 docs/commands/gog-docs-header-create.md       |   1 +
 docs/commands/gog-docs-header-delete.md       |   1 +
 docs/commands/gog-docs-header-list.md         |   1 +
 docs/commands/gog-docs-header.md              |   1 +
 docs/commands/gog-docs-headings-list.md       |   1 +
 docs/commands/gog-docs-headings.md            |   1 +
 docs/commands/gog-docs-images-list.md         |   1 +
 docs/commands/gog-docs-images.md              |   1 +
 docs/commands/gog-docs-info.md                |   1 +
 docs/commands/gog-docs-insert-date-chip.md    |   1 +
 docs/commands/gog-docs-insert-file-chip.md    |   1 +
 docs/commands/gog-docs-insert-footnote.md     |   1 +
 .../gog-docs-insert-horizontal-rule.md        |   1 +
 docs/commands/gog-docs-insert-image.md        |   1 +
 docs/commands/gog-docs-insert-page-break.md   |   1 +
 docs/commands/gog-docs-insert-person.md       |   1 +
 .../commands/gog-docs-insert-section-break.md |   1 +
 docs/commands/gog-docs-insert-table.md        |   1 +
 docs/commands/gog-docs-insert.md              |   1 +
 docs/commands/gog-docs-list-tabs.md           |   1 +
 docs/commands/gog-docs-named-range-create.md  |   1 +
 docs/commands/gog-docs-named-range-delete.md  |   1 +
 docs/commands/gog-docs-named-range-list.md    |   1 +
 docs/commands/gog-docs-named-range-replace.md |   1 +
 docs/commands/gog-docs-named-range.md         |   1 +
 docs/commands/gog-docs-page-layout.md         |   1 +
 docs/commands/gog-docs-paragraphs-list.md     |   1 +
 docs/commands/gog-docs-paragraphs.md          |   1 +
 docs/commands/gog-docs-raw.md                 |   1 +
 docs/commands/gog-docs-rename-tab.md          |   1 +
 docs/commands/gog-docs-replace-image.md       |   1 +
 docs/commands/gog-docs-section-columns.md     |   1 +
 docs/commands/gog-docs-sed.md                 |   1 +
 docs/commands/gog-docs-structure.md           |   1 +
 docs/commands/gog-docs-table-column-delete.md |   1 +
 docs/commands/gog-docs-table-column-insert.md |   1 +
 docs/commands/gog-docs-table-column-width.md  |   1 +
 docs/commands/gog-docs-table-column.md        |   1 +
 docs/commands/gog-docs-table-merge.md         |   1 +
 docs/commands/gog-docs-table-row-delete.md    |   1 +
 docs/commands/gog-docs-table-row-insert.md    |   1 +
 .../commands/gog-docs-table-row-pin-header.md |   1 +
 docs/commands/gog-docs-table-row-style.md     |   1 +
 docs/commands/gog-docs-table-row.md           |   1 +
 docs/commands/gog-docs-table-unmerge.md       |   1 +
 docs/commands/gog-docs-tables-list.md         |   1 +
 docs/commands/gog-docs-tables.md              |   1 +
 docs/commands/gog-docs-tabs-add.md            |   1 +
 docs/commands/gog-docs-tabs-delete.md         |   1 +
 docs/commands/gog-docs-tabs-list.md           |   1 +
 docs/commands/gog-docs-tabs-rename.md         |   1 +
 docs/commands/gog-docs-tabs.md                |   1 +
 docs/commands/gog-docs-update.md              |   1 +
 docs/commands/gog-docs-write.md               |   1 +
 docs/commands/gog-docs.md                     |   1 +
 docs/commands/gog-download.md                 |   1 +
 docs/commands/gog-drive-activity-query.md     |   1 +
 docs/commands/gog-drive-activity.md           |   1 +
 docs/commands/gog-drive-audit-sharing.md      |   1 +
 docs/commands/gog-drive-audit-user.md         |   1 +
 docs/commands/gog-drive-audit.md              |   1 +
 docs/commands/gog-drive-bulk-remove-public.md |   1 +
 docs/commands/gog-drive-bulk-update-role.md   |   1 +
 docs/commands/gog-drive-bulk.md               |   1 +
 docs/commands/gog-drive-changes-list.md       |   1 +
 docs/commands/gog-drive-changes-poll.md       |   1 +
 docs/commands/gog-drive-changes-serve.md      |   1 +
 .../commands/gog-drive-changes-start-token.md |   1 +
 docs/commands/gog-drive-changes-stop.md       |   1 +
 docs/commands/gog-drive-changes-watch.md      |   1 +
 docs/commands/gog-drive-changes.md            |   1 +
 docs/commands/gog-drive-comments-create.md    |   1 +
 docs/commands/gog-drive-comments-delete.md    |   1 +
 docs/commands/gog-drive-comments-get.md       |   1 +
 docs/commands/gog-drive-comments-list.md      |   1 +
 docs/commands/gog-drive-comments-reopen.md    |   1 +
 docs/commands/gog-drive-comments-reply.md     |   1 +
 docs/commands/gog-drive-comments-resolve.md   |   1 +
 docs/commands/gog-drive-comments-update.md    |   1 +
 docs/commands/gog-drive-comments.md           |   1 +
 docs/commands/gog-drive-copy.md               |   1 +
 docs/commands/gog-drive-delete.md             |   1 +
 docs/commands/gog-drive-download.md           |   1 +
 docs/commands/gog-drive-drives.md             |   1 +
 docs/commands/gog-drive-du.md                 |   1 +
 docs/commands/gog-drive-get.md                |   1 +
 docs/commands/gog-drive-inventory.md          |   1 +
 docs/commands/gog-drive-labels-file-apply.md  |   1 +
 docs/commands/gog-drive-labels-file-list.md   |   1 +
 docs/commands/gog-drive-labels-file-remove.md |   1 +
 docs/commands/gog-drive-labels-file.md        |   1 +
 docs/commands/gog-drive-labels-get.md         |   1 +
 docs/commands/gog-drive-labels-list.md        |   1 +
 docs/commands/gog-drive-labels.md             |   1 +
 docs/commands/gog-drive-ls.md                 |   1 +
 docs/commands/gog-drive-mkdir.md              |   1 +
 docs/commands/gog-drive-move.md               |   1 +
 docs/commands/gog-drive-permissions.md        |   1 +
 docs/commands/gog-drive-raw.md                |   1 +
 docs/commands/gog-drive-rename.md             |   1 +
 docs/commands/gog-drive-revisions-get.md      |   1 +
 docs/commands/gog-drive-revisions-list.md     |   1 +
 docs/commands/gog-drive-revisions.md          |   1 +
 docs/commands/gog-drive-search.md             |   1 +
 docs/commands/gog-drive-share.md              |   1 +
 docs/commands/gog-drive-shortcut-create.md    |   1 +
 docs/commands/gog-drive-shortcut.md           |   1 +
 docs/commands/gog-drive-tree.md               |   1 +
 docs/commands/gog-drive-unshare.md            |   1 +
 docs/commands/gog-drive-upload.md             |   1 +
 docs/commands/gog-drive-url.md                |   1 +
 docs/commands/gog-drive.md                    |   1 +
 docs/commands/gog-forms-add-question.md       |   1 +
 docs/commands/gog-forms-create.md             |   1 +
 docs/commands/gog-forms-delete-question.md    |   1 +
 docs/commands/gog-forms-get.md                |   1 +
 docs/commands/gog-forms-move-question.md      |   1 +
 docs/commands/gog-forms-publish.md            |   1 +
 docs/commands/gog-forms-questions-add.md      |   1 +
 docs/commands/gog-forms-questions-delete.md   |   1 +
 docs/commands/gog-forms-questions-move.md     |   1 +
 docs/commands/gog-forms-questions.md          |   1 +
 docs/commands/gog-forms-raw.md                |   1 +
 docs/commands/gog-forms-responses-get.md      |   1 +
 docs/commands/gog-forms-responses-list.md     |   1 +
 docs/commands/gog-forms-responses.md          |   1 +
 docs/commands/gog-forms-update.md             |   1 +
 docs/commands/gog-forms-watch-create.md       |   1 +
 docs/commands/gog-forms-watch-delete.md       |   1 +
 docs/commands/gog-forms-watch-list.md         |   1 +
 docs/commands/gog-forms-watch-renew.md        |   1 +
 docs/commands/gog-forms-watch.md              |   1 +
 docs/commands/gog-forms.md                    |   1 +
 docs/commands/gog-gmail-archive.md            |   1 +
 docs/commands/gog-gmail-attachment.md         |   1 +
 docs/commands/gog-gmail-autoreply.md          |   1 +
 docs/commands/gog-gmail-batch-delete.md       |   1 +
 docs/commands/gog-gmail-batch-modify.md       |   1 +
 docs/commands/gog-gmail-batch.md              |   1 +
 docs/commands/gog-gmail-drafts-create.md      |   1 +
 docs/commands/gog-gmail-drafts-delete.md      |   1 +
 docs/commands/gog-gmail-drafts-get.md         |   1 +
 docs/commands/gog-gmail-drafts-list.md        |   1 +
 docs/commands/gog-gmail-drafts-send.md        |   1 +
 docs/commands/gog-gmail-drafts-update.md      |   1 +
 docs/commands/gog-gmail-drafts.md             |   1 +
 docs/commands/gog-gmail-forward.md            |   1 +
 docs/commands/gog-gmail-get.md                |   1 +
 docs/commands/gog-gmail-history.md            |   1 +
 docs/commands/gog-gmail-labels-create.md      |   1 +
 docs/commands/gog-gmail-labels-delete.md      |   1 +
 docs/commands/gog-gmail-labels-get.md         |   1 +
 docs/commands/gog-gmail-labels-list.md        |   1 +
 docs/commands/gog-gmail-labels-modify.md      |   1 +
 docs/commands/gog-gmail-labels-rename.md      |   1 +
 docs/commands/gog-gmail-labels-style.md       |   1 +
 docs/commands/gog-gmail-labels.md             |   1 +
 docs/commands/gog-gmail-mark-read.md          |   1 +
 docs/commands/gog-gmail-messages-modify.md    |   1 +
 docs/commands/gog-gmail-messages-search.md    |   1 +
 docs/commands/gog-gmail-messages.md           |   1 +
 docs/commands/gog-gmail-raw.md                |   1 +
 docs/commands/gog-gmail-reply-all.md          |   1 +
 docs/commands/gog-gmail-reply.md              |   1 +
 docs/commands/gog-gmail-search.md             |   1 +
 docs/commands/gog-gmail-send.md               |   1 +
 .../gog-gmail-settings-autoforward-get.md     |   1 +
 .../gog-gmail-settings-autoforward-update.md  |   1 +
 .../gog-gmail-settings-autoforward.md         |   1 +
 .../gog-gmail-settings-delegates-add.md       |   1 +
 .../gog-gmail-settings-delegates-get.md       |   1 +
 .../gog-gmail-settings-delegates-list.md      |   1 +
 .../gog-gmail-settings-delegates-remove.md    |   1 +
 docs/commands/gog-gmail-settings-delegates.md |   1 +
 .../gog-gmail-settings-filters-create.md      |   1 +
 .../gog-gmail-settings-filters-delete.md      |   1 +
 .../gog-gmail-settings-filters-export.md      |   1 +
 .../gog-gmail-settings-filters-get.md         |   1 +
 .../gog-gmail-settings-filters-list.md        |   1 +
 docs/commands/gog-gmail-settings-filters.md   |   1 +
 .../gog-gmail-settings-forwarding-create.md   |   1 +
 .../gog-gmail-settings-forwarding-delete.md   |   1 +
 .../gog-gmail-settings-forwarding-get.md      |   1 +
 .../gog-gmail-settings-forwarding-list.md     |   1 +
 .../commands/gog-gmail-settings-forwarding.md |   1 +
 .../gog-gmail-settings-sendas-create.md       |   1 +
 .../gog-gmail-settings-sendas-delete.md       |   1 +
 .../commands/gog-gmail-settings-sendas-get.md |   1 +
 .../gog-gmail-settings-sendas-list.md         |   1 +
 .../gog-gmail-settings-sendas-update.md       |   1 +
 .../gog-gmail-settings-sendas-verify.md       |   1 +
 docs/commands/gog-gmail-settings-sendas.md    |   1 +
 .../gog-gmail-settings-vacation-get.md        |   1 +
 .../gog-gmail-settings-vacation-update.md     |   1 +
 docs/commands/gog-gmail-settings-vacation.md  |   1 +
 .../commands/gog-gmail-settings-watch-pull.md |   1 +
 .../gog-gmail-settings-watch-renew.md         |   1 +
 .../gog-gmail-settings-watch-serve.md         |   1 +
 .../gog-gmail-settings-watch-start.md         |   1 +
 .../gog-gmail-settings-watch-status.md        |   1 +
 .../commands/gog-gmail-settings-watch-stop.md |   1 +
 docs/commands/gog-gmail-settings-watch.md     |   1 +
 docs/commands/gog-gmail-settings.md           |   1 +
 docs/commands/gog-gmail-thread-attachments.md |   1 +
 docs/commands/gog-gmail-thread-get.md         |   1 +
 docs/commands/gog-gmail-thread-modify.md      |   1 +
 docs/commands/gog-gmail-thread.md             |   1 +
 docs/commands/gog-gmail-track-key-rotate.md   |   1 +
 docs/commands/gog-gmail-track-key.md          |   1 +
 docs/commands/gog-gmail-track-opens.md        |   1 +
 docs/commands/gog-gmail-track-setup.md        |   1 +
 docs/commands/gog-gmail-track-status.md       |   1 +
 docs/commands/gog-gmail-track.md              |   1 +
 docs/commands/gog-gmail-trash.md              |   1 +
 docs/commands/gog-gmail-unread.md             |   1 +
 docs/commands/gog-gmail-url.md                |   1 +
 docs/commands/gog-gmail.md                    |   1 +
 docs/commands/gog-groups-list.md              |   1 +
 docs/commands/gog-groups-members.md           |   1 +
 docs/commands/gog-groups.md                   |   1 +
 docs/commands/gog-keep-attachment.md          |   1 +
 docs/commands/gog-keep-create.md              |   1 +
 docs/commands/gog-keep-delete.md              |   1 +
 docs/commands/gog-keep-get.md                 |   1 +
 docs/commands/gog-keep-list.md                |   1 +
 docs/commands/gog-keep-search.md              |   1 +
 docs/commands/gog-keep.md                     |   1 +
 docs/commands/gog-login.md                    |   2 +-
 docs/commands/gog-logout.md                   |   1 +
 docs/commands/gog-ls.md                       |   1 +
 docs/commands/gog-maps-directions.md          |   1 +
 docs/commands/gog-maps-distance.md            |   1 +
 docs/commands/gog-maps-geocode.md             |   1 +
 docs/commands/gog-maps-places-details.md      |   1 +
 docs/commands/gog-maps-places-search.md       |   1 +
 docs/commands/gog-maps-places.md              |   1 +
 docs/commands/gog-maps-reverse-geocode.md     |   1 +
 docs/commands/gog-maps.md                     |   1 +
 docs/commands/gog-mcp.md                      |   1 +
 docs/commands/gog-me.md                       |   1 +
 docs/commands/gog-meet-create.md              |   1 +
 docs/commands/gog-meet-end.md                 |   1 +
 docs/commands/gog-meet-get.md                 |   1 +
 docs/commands/gog-meet-history.md             |   1 +
 docs/commands/gog-meet-participants.md        |   1 +
 docs/commands/gog-meet-update.md              |   1 +
 docs/commands/gog-meet.md                     |   1 +
 docs/commands/gog-open.md                     |   1 +
 docs/commands/gog-people-get.md               |   1 +
 docs/commands/gog-people-me.md                |   1 +
 docs/commands/gog-people-raw.md               |   1 +
 docs/commands/gog-people-relations.md         |   1 +
 docs/commands/gog-people-search.md            |   1 +
 docs/commands/gog-people.md                   |   1 +
 docs/commands/gog-photos-download.md          |   1 +
 docs/commands/gog-photos-get.md               |   1 +
 docs/commands/gog-photos-list.md              |   1 +
 docs/commands/gog-photos-picker-create.md     |   1 +
 docs/commands/gog-photos-picker-delete.md     |   1 +
 docs/commands/gog-photos-picker-download.md   |   1 +
 docs/commands/gog-photos-picker-get.md        |   1 +
 docs/commands/gog-photos-picker-list.md       |   1 +
 docs/commands/gog-photos-picker-wait.md       |   1 +
 docs/commands/gog-photos-picker.md            |   1 +
 docs/commands/gog-photos-search.md            |   1 +
 docs/commands/gog-photos.md                   |   1 +
 docs/commands/gog-schema.md                   |   1 +
 docs/commands/gog-search.md                   |   1 +
 docs/commands/gog-searchconsole-query.md      |   1 +
 ...gog-searchconsole-searchanalytics-query.md |   1 +
 .../gog-searchconsole-searchanalytics.md      |   1 +
 .../gog-searchconsole-sitemaps-delete.md      |   1 +
 .../gog-searchconsole-sitemaps-get.md         |   1 +
 .../gog-searchconsole-sitemaps-list.md        |   1 +
 .../gog-searchconsole-sitemaps-submit.md      |   1 +
 docs/commands/gog-searchconsole-sitemaps.md   |   1 +
 docs/commands/gog-searchconsole-sites-get.md  |   1 +
 docs/commands/gog-searchconsole-sites-list.md |   1 +
 docs/commands/gog-searchconsole-sites.md      |   1 +
 docs/commands/gog-searchconsole.md            |   1 +
 docs/commands/gog-send.md                     |   1 +
 docs/commands/gog-sheets-add-tab.md           |   1 +
 docs/commands/gog-sheets-append.md            |   1 +
 docs/commands/gog-sheets-banding-clear.md     |   1 +
 docs/commands/gog-sheets-banding-list.md      |   1 +
 docs/commands/gog-sheets-banding-set.md       |   1 +
 docs/commands/gog-sheets-banding.md           |   1 +
 docs/commands/gog-sheets-batch-update.md      |   1 +
 docs/commands/gog-sheets-chart-create.md      |   1 +
 docs/commands/gog-sheets-chart-delete.md      |   1 +
 docs/commands/gog-sheets-chart-get.md         |   1 +
 docs/commands/gog-sheets-chart-list.md        |   1 +
 docs/commands/gog-sheets-chart-update.md      |   1 +
 docs/commands/gog-sheets-chart.md             |   1 +
 docs/commands/gog-sheets-clear.md             |   1 +
 .../gog-sheets-conditional-format-add.md      |   1 +
 .../gog-sheets-conditional-format-clear.md    |   1 +
 .../gog-sheets-conditional-format-list.md     |   1 +
 .../commands/gog-sheets-conditional-format.md |   1 +
 docs/commands/gog-sheets-copy-paste.md        |   1 +
 docs/commands/gog-sheets-copy.md              |   1 +
 docs/commands/gog-sheets-create.md            |   1 +
 docs/commands/gog-sheets-delete-dimension.md  |   1 +
 docs/commands/gog-sheets-delete-tab.md        |   1 +
 docs/commands/gog-sheets-export.md            |   1 +
 docs/commands/gog-sheets-find-replace.md      |   1 +
 docs/commands/gog-sheets-format.md            |   1 +
 docs/commands/gog-sheets-freeze.md            |   1 +
 docs/commands/gog-sheets-get.md               |   1 +
 docs/commands/gog-sheets-insert.md            |   1 +
 docs/commands/gog-sheets-links-get.md         |   1 +
 docs/commands/gog-sheets-links-set.md         |   1 +
 docs/commands/gog-sheets-links.md             |   1 +
 docs/commands/gog-sheets-merge.md             |   1 +
 docs/commands/gog-sheets-metadata.md          |   1 +
 docs/commands/gog-sheets-named-ranges-add.md  |   1 +
 .../gog-sheets-named-ranges-delete.md         |   1 +
 docs/commands/gog-sheets-named-ranges-get.md  |   1 +
 docs/commands/gog-sheets-named-ranges-list.md |   1 +
 .../gog-sheets-named-ranges-update.md         |   1 +
 docs/commands/gog-sheets-named-ranges.md      |   1 +
 docs/commands/gog-sheets-notes.md             |   1 +
 docs/commands/gog-sheets-number-format.md     |   1 +
 docs/commands/gog-sheets-raw.md               |   1 +
 docs/commands/gog-sheets-read-format.md       |   1 +
 docs/commands/gog-sheets-rename-tab.md        |   1 +
 docs/commands/gog-sheets-reorder-tab.md       |   1 +
 docs/commands/gog-sheets-resize-columns.md    |   1 +
 docs/commands/gog-sheets-resize-rows.md       |   1 +
 docs/commands/gog-sheets-table-append.md      |   1 +
 docs/commands/gog-sheets-table-clear.md       |   1 +
 docs/commands/gog-sheets-table-create.md      |   1 +
 docs/commands/gog-sheets-table-delete.md      |   1 +
 docs/commands/gog-sheets-table-get.md         |   1 +
 docs/commands/gog-sheets-table-list.md        |   1 +
 docs/commands/gog-sheets-table.md             |   1 +
 docs/commands/gog-sheets-unmerge.md           |   1 +
 docs/commands/gog-sheets-update-note.md       |   1 +
 docs/commands/gog-sheets-update.md            |   1 +
 docs/commands/gog-sheets-validation-clear.md  |   1 +
 docs/commands/gog-sheets-validation-get.md    |   1 +
 docs/commands/gog-sheets-validation-set.md    |   1 +
 docs/commands/gog-sheets-validation.md        |   1 +
 docs/commands/gog-sheets.md                   |   1 +
 docs/commands/gog-sites-get.md                |   1 +
 docs/commands/gog-sites-list.md               |   1 +
 docs/commands/gog-sites-search.md             |   1 +
 docs/commands/gog-sites-url.md                |   1 +
 docs/commands/gog-sites.md                    |   1 +
 docs/commands/gog-slides-add-slide.md         |   1 +
 docs/commands/gog-slides-bullets.md           |   1 +
 docs/commands/gog-slides-copy.md              |   1 +
 .../gog-slides-create-from-markdown.md        |   1 +
 .../gog-slides-create-from-template.md        |   1 +
 docs/commands/gog-slides-create.md            |   1 +
 docs/commands/gog-slides-delete-slide.md      |   1 +
 docs/commands/gog-slides-duplicate-slide.md   |   1 +
 docs/commands/gog-slides-element-alt-text.md  |   1 +
 .../gog-slides-element-create-line.md         |   1 +
 .../gog-slides-element-create-shape.md        |   1 +
 docs/commands/gog-slides-element-delete.md    |   1 +
 docs/commands/gog-slides-element-group.md     |   1 +
 docs/commands/gog-slides-element-style.md     |   1 +
 docs/commands/gog-slides-element-transform.md |   1 +
 docs/commands/gog-slides-element-ungroup.md   |   1 +
 docs/commands/gog-slides-element-z-order.md   |   1 +
 docs/commands/gog-slides-element.md           |   1 +
 docs/commands/gog-slides-export.md            |   1 +
 docs/commands/gog-slides-info.md              |   1 +
 docs/commands/gog-slides-insert-image.md      |   1 +
 docs/commands/gog-slides-insert-text.md       |   1 +
 docs/commands/gog-slides-link.md              |   1 +
 docs/commands/gog-slides-list-slides.md       |   1 +
 docs/commands/gog-slides-locate.md            |   1 +
 docs/commands/gog-slides-move-slide.md        |   1 +
 docs/commands/gog-slides-new-slide.md         |   1 +
 docs/commands/gog-slides-raw.md               |   1 +
 docs/commands/gog-slides-read-slide.md        |   1 +
 docs/commands/gog-slides-replace-slide.md     |   1 +
 docs/commands/gog-slides-replace-text.md      |   1 +
 docs/commands/gog-slides-style-text.md        |   1 +
 .../commands/gog-slides-table-border-style.md |   1 +
 docs/commands/gog-slides-table-border.md      |   1 +
 docs/commands/gog-slides-table-cell-style.md  |   1 +
 docs/commands/gog-slides-table-cell.md        |   1 +
 .../gog-slides-table-column-delete.md         |   1 +
 .../gog-slides-table-column-insert.md         |   1 +
 docs/commands/gog-slides-table-column-size.md |   1 +
 docs/commands/gog-slides-table-column.md      |   1 +
 docs/commands/gog-slides-table-create.md      |   1 +
 docs/commands/gog-slides-table-merge.md       |   1 +
 docs/commands/gog-slides-table-row-delete.md  |   1 +
 docs/commands/gog-slides-table-row-insert.md  |   1 +
 docs/commands/gog-slides-table-row-size.md    |   1 +
 docs/commands/gog-slides-table-row.md         |   1 +
 docs/commands/gog-slides-table-unmerge.md     |   1 +
 docs/commands/gog-slides-table.md             |   1 +
 docs/commands/gog-slides-thumbnail.md         |   1 +
 docs/commands/gog-slides-update-notes.md      |   1 +
 docs/commands/gog-slides.md                   |   1 +
 docs/commands/gog-status.md                   |   1 +
 docs/commands/gog-tasks-add.md                |   1 +
 docs/commands/gog-tasks-clear.md              |   1 +
 docs/commands/gog-tasks-delete.md             |   1 +
 docs/commands/gog-tasks-done.md               |   1 +
 docs/commands/gog-tasks-get.md                |   1 +
 docs/commands/gog-tasks-list.md               |   1 +
 docs/commands/gog-tasks-lists-create.md       |   1 +
 docs/commands/gog-tasks-lists-list.md         |   1 +
 docs/commands/gog-tasks-lists.md              |   1 +
 docs/commands/gog-tasks-raw.md                |   1 +
 docs/commands/gog-tasks-undo.md               |   1 +
 docs/commands/gog-tasks-update.md             |   1 +
 docs/commands/gog-tasks.md                    |   1 +
 docs/commands/gog-time-now.md                 |   1 +
 docs/commands/gog-time.md                     |   1 +
 docs/commands/gog-upload.md                   |   1 +
 docs/commands/gog-version.md                  |   1 +
 docs/commands/gog-whoami.md                   |   1 +
 docs/commands/gog-youtube-activities-list.md  |   1 +
 docs/commands/gog-youtube-activities.md       |   1 +
 docs/commands/gog-youtube-channels-list.md    |   1 +
 docs/commands/gog-youtube-channels.md         |   1 +
 docs/commands/gog-youtube-comments-list.md    |   1 +
 docs/commands/gog-youtube-comments.md         |   1 +
 docs/commands/gog-youtube-playlists-add.md    |   1 +
 docs/commands/gog-youtube-playlists-create.md |   1 +
 docs/commands/gog-youtube-playlists-delete.md |   1 +
 .../gog-youtube-playlists-items-list.md       |   1 +
 docs/commands/gog-youtube-playlists-items.md  |   1 +
 docs/commands/gog-youtube-playlists-list.md   |   1 +
 docs/commands/gog-youtube-playlists-remove.md |   1 +
 docs/commands/gog-youtube-playlists.md        |   1 +
 docs/commands/gog-youtube-search-list.md      |   1 +
 docs/commands/gog-youtube-search.md           |   1 +
 .../gog-youtube-subscriptions-list.md         |   1 +
 .../gog-youtube-subscriptions-subscribe.md    |   1 +
 .../gog-youtube-subscriptions-unsubscribe.md  |   1 +
 docs/commands/gog-youtube-subscriptions.md    |   1 +
 docs/commands/gog-youtube-videos-list.md      |   1 +
 docs/commands/gog-youtube-videos.md           |   1 +
 docs/commands/gog-youtube.md                  |   1 +
 docs/commands/gog-zoom-auth-doctor.md         |   1 +
 docs/commands/gog-zoom-auth-setup.md          |   1 +
 docs/commands/gog-zoom-auth.md                |   1 +
 docs/commands/gog-zoom.md                     |   1 +
 docs/commands/gog.md                          |   1 +
 internal/cmd/auth_add.go                      |  20 +--
 internal/cmd/exit_codes.go                    |   3 +
 internal/cmd/exit_codes_test.go               |   7 ++
 internal/cmd/gmail_watch_pull.go              |   6 +
 internal/cmd/gmail_watch_pull_test.go         |  10 ++
 internal/cmd/mcp.go                           |   3 +
 internal/cmd/mcp_test.go                      |   3 +-
 internal/cmd/root.go                          |   3 +
 internal/cmd/runtime_services.go              |   4 +
 internal/cmd/schema.go                        |   2 +
 internal/cmd/schema_test.go                   |   3 +-
 internal/googleapi/client.go                  |  16 +--
 internal/googleapi/keep.go                    |   3 +-
 internal/googleapi/read_only.go               | 111 ++++++++++++++++
 internal/googleapi/read_only_test.go          | 119 ++++++++++++++++++
 712 files changed, 1005 insertions(+), 22 deletions(-)
 create mode 100644 internal/googleapi/read_only.go
 create mode 100644 internal/googleapi/read_only_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4d11762d4..b68c81f81 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@
 - CLI: add `GOG_HELP=agent` compact root help with common read-only recipes and targeted schema guidance so agents can execute Gmail, Calendar, and Drive tasks without traversing multiple help levels.
 - Auth: add `auth setup` for guided Google Cloud project/API preparation, OAuth client installation, and optional browser authorization.
 - API: add Discovery-backed `api list`, `api describe`, and scoped `api call` access for Google methods outside the first-class command surface, with dry-run plans and explicit write opt-in.
+- Safety: add global `--readonly` / `GOG_READONLY=1` runtime enforcement that blocks mutating Google and Zoom API requests before dispatch while preserving read-only query POSTs and least-privilege OAuth setup.
 
 ## 0.30.0 - 2026-06-21
 
diff --git a/README.md b/README.md
index 6a2eca328..e85a1e201 100644
--- a/README.md
+++ b/README.md
@@ -556,6 +556,7 @@ Useful global flags:
 - `--wrap-untrusted`: in JSON/raw output, wrap fetched free-text fields with
   external untrusted-content markers for LLM/agent consumption
 - `--dry-run`: print intended actions where a command supports planning
+- `--readonly`: block mutating API requests before network dispatch; still allow known POST-based query APIs
 - `--no-input`: fail instead of prompting
 - `--force`: confirm destructive operations
 - `--enable-commands <csv>`: allow selected command prefixes. Parent paths allow children, so `gmail` allows the Gmail command family.
@@ -569,6 +570,7 @@ For coding agents or CI, prefer:
 gog --account you@gmail.com \
   --enable-commands-exact gmail.search,gmail.get,drive.ls,docs.cat \
   --gmail-no-send \
+  --readonly \
   --wrap-untrusted \
   --json \
   gmail search 'newer_than:7d'
diff --git a/docs/automation.md b/docs/automation.md
index 408c12f4a..1c79fcd31 100644
--- a/docs/automation.md
+++ b/docs/automation.md
@@ -53,6 +53,18 @@ Use `--no-input` in CI and unattended processes. Use `--wrap-untrusted` when
 Google-hosted free text will be consumed by an LLM or another instruction-aware
 system.
 
+Use `--readonly` (or `GOG_READONLY=1`) as a runtime backstop. It permits GET,
+HEAD, OPTIONS, and the small allowlist of Google APIs whose query operations use
+POST, while rejecting mutating API requests before network dispatch. This guard
+is independent of OAuth scopes and command names, propagates into MCP child
+processes, and also blocks Zoom meeting mutations. `gog auth add --readonly`
+continues to request read-only OAuth scopes where Google provides them.
+
+```bash
+gog --readonly --account you@example.com gmail search 'newer_than:7d'
+gog --readonly --account you@example.com calendar freebusy you@example.com
+```
+
 Interactive browser commands fail fast under `--no-input`. Preview
 `gog auth manage` with `--dry-run`; use `gog auth import` for unattended token
 installation.
@@ -73,6 +85,7 @@ Example:
 gog \
   --enable-commands-exact schema,gmail.search \
   --gmail-no-send \
+  --readonly \
   --no-input \
   --wrap-untrusted \
   schema --json |
@@ -87,6 +100,7 @@ common_flags=(
   --account you@example.com
   --enable-commands-exact schema,gmail.search
   --gmail-no-send
+  --readonly
   --no-input
   --wrap-untrusted
 )
@@ -97,6 +111,7 @@ gog "${common_flags[@]}" schema --json |
     .automation.safety.no_input and
     .automation.safety.wrap_untrusted and
     .automation.safety.gmail_no_send and
+    .automation.safety.readonly and
     (.automation.safety.command_rules.enabled_exact | index("gmail.search"))
   '
 
diff --git a/docs/commands/gog-admin-groups-list.md b/docs/commands/gog-admin-groups-list.md
index 983864dba..4aaf6f58b 100644
--- a/docs/commands/gog-admin-groups-list.md
+++ b/docs/commands/gog-admin-groups-list.md
@@ -38,6 +38,7 @@ gog admin groups list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-groups-members-add.md b/docs/commands/gog-admin-groups-members-add.md
index cb18ce7fe..dc61461a3 100644
--- a/docs/commands/gog-admin-groups-members-add.md
+++ b/docs/commands/gog-admin-groups-members-add.md
@@ -33,6 +33,7 @@ gog admin groups members add (invite) <groupEmail> <memberEmail> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--role` | `string` | MEMBER | Member role (MEMBER, MANAGER, OWNER) |
 | `--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. |
diff --git a/docs/commands/gog-admin-groups-members-list.md b/docs/commands/gog-admin-groups-members-list.md
index ec6f4003f..f72a10b4e 100644
--- a/docs/commands/gog-admin-groups-members-list.md
+++ b/docs/commands/gog-admin-groups-members-list.md
@@ -37,6 +37,7 @@ gog admin groups members list (ls) <groupEmail> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-groups-members-remove.md b/docs/commands/gog-admin-groups-members-remove.md
index d7f70e561..a10d71e7d 100644
--- a/docs/commands/gog-admin-groups-members-remove.md
+++ b/docs/commands/gog-admin-groups-members-remove.md
@@ -33,6 +33,7 @@ gog admin groups members remove (rm,del,delete) <groupEmail> <memberEmail>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-groups-members.md b/docs/commands/gog-admin-groups-members.md
index 133073537..bd00fb075 100644
--- a/docs/commands/gog-admin-groups-members.md
+++ b/docs/commands/gog-admin-groups-members.md
@@ -39,6 +39,7 @@ gog admin groups members <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-groups.md b/docs/commands/gog-admin-groups.md
index 07c95af54..99b31b2a6 100644
--- a/docs/commands/gog-admin-groups.md
+++ b/docs/commands/gog-admin-groups.md
@@ -38,6 +38,7 @@ gog admin groups <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-orgunits-create.md b/docs/commands/gog-admin-orgunits-create.md
index 53c321b63..5a4698412 100644
--- a/docs/commands/gog-admin-orgunits-create.md
+++ b/docs/commands/gog-admin-orgunits-create.md
@@ -35,6 +35,7 @@ gog admin orgunits (org-units,ou) create (add,new) <name> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` | / | Parent org unit path |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-orgunits-delete.md b/docs/commands/gog-admin-orgunits-delete.md
index ed4135995..ff5f44d4f 100644
--- a/docs/commands/gog-admin-orgunits-delete.md
+++ b/docs/commands/gog-admin-orgunits-delete.md
@@ -33,6 +33,7 @@ gog admin orgunits (org-units,ou) delete (rm,del,remove) <path>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-orgunits-get.md b/docs/commands/gog-admin-orgunits-get.md
index 4bff0f21e..d4403b2cc 100644
--- a/docs/commands/gog-admin-orgunits-get.md
+++ b/docs/commands/gog-admin-orgunits-get.md
@@ -33,6 +33,7 @@ gog admin orgunits (org-units,ou) get (info,show) <path>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-orgunits-list.md b/docs/commands/gog-admin-orgunits-list.md
index c11a2650d..022d5a130 100644
--- a/docs/commands/gog-admin-orgunits-list.md
+++ b/docs/commands/gog-admin-orgunits-list.md
@@ -34,6 +34,7 @@ gog admin orgunits (org-units,ou) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` | / | Parent org unit path or ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--type` | `string` | children | Return all descendants, children, or all including parent |
diff --git a/docs/commands/gog-admin-orgunits-update.md b/docs/commands/gog-admin-orgunits-update.md
index baf8c32b2..c8a43a029 100644
--- a/docs/commands/gog-admin-orgunits-update.md
+++ b/docs/commands/gog-admin-orgunits-update.md
@@ -36,6 +36,7 @@ gog admin orgunits (org-units,ou) update (edit,set) <path> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `*string` |  | New parent org unit path |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-orgunits.md b/docs/commands/gog-admin-orgunits.md
index e5f95b2cb..bc117217c 100644
--- a/docs/commands/gog-admin-orgunits.md
+++ b/docs/commands/gog-admin-orgunits.md
@@ -41,6 +41,7 @@ gog admin orgunits (org-units,ou) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-users-create.md b/docs/commands/gog-admin-users-create.md
index eef2baced..aa8a64774 100644
--- a/docs/commands/gog-admin-users-create.md
+++ b/docs/commands/gog-admin-users-create.md
@@ -41,6 +41,7 @@ gog admin users create (add,new) <email> [flags]
 | `--org-unit`<br>`--ou` | `string` |  | Organization unit path |
 | `--password`<br>`--pass` | `string` |  | Initial password (generated if omitted) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--recovery-email` | `string` |  | Recovery email address |
 | `--recovery-phone` | `string` |  | Recovery phone number in E.164 format |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
diff --git a/docs/commands/gog-admin-users-delete.md b/docs/commands/gog-admin-users-delete.md
index 4fcaf82ac..dc6177992 100644
--- a/docs/commands/gog-admin-users-delete.md
+++ b/docs/commands/gog-admin-users-delete.md
@@ -33,6 +33,7 @@ gog admin users delete (rm,del,remove) <userEmail>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-users-get.md b/docs/commands/gog-admin-users-get.md
index 964b422f2..260a08650 100644
--- a/docs/commands/gog-admin-users-get.md
+++ b/docs/commands/gog-admin-users-get.md
@@ -33,6 +33,7 @@ gog admin users get (info,show) <userEmail>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-users-list.md b/docs/commands/gog-admin-users-list.md
index c13ab67e7..67c3fc827 100644
--- a/docs/commands/gog-admin-users-list.md
+++ b/docs/commands/gog-admin-users-list.md
@@ -38,6 +38,7 @@ gog admin users list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-users-suspend.md b/docs/commands/gog-admin-users-suspend.md
index a036c6c41..63ebca82d 100644
--- a/docs/commands/gog-admin-users-suspend.md
+++ b/docs/commands/gog-admin-users-suspend.md
@@ -33,6 +33,7 @@ gog admin users suspend <userEmail>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin-users.md b/docs/commands/gog-admin-users.md
index f89b39b11..90f90ffe3 100644
--- a/docs/commands/gog-admin-users.md
+++ b/docs/commands/gog-admin-users.md
@@ -41,6 +41,7 @@ gog admin users <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-admin.md b/docs/commands/gog-admin.md
index 006e6a104..3ec58728e 100644
--- a/docs/commands/gog-admin.md
+++ b/docs/commands/gog-admin.md
@@ -39,6 +39,7 @@ gog admin <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-analytics-accounts.md b/docs/commands/gog-analytics-accounts.md
index 309fe0982..da70cf8ad 100644
--- a/docs/commands/gog-analytics-accounts.md
+++ b/docs/commands/gog-analytics-accounts.md
@@ -37,6 +37,7 @@ gog analytics (ga) accounts (list,ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-analytics-report.md b/docs/commands/gog-analytics-report.md
index f34f3a714..9a7c0dab4 100644
--- a/docs/commands/gog-analytics-report.md
+++ b/docs/commands/gog-analytics-report.md
@@ -39,6 +39,7 @@ gog analytics (ga) report <property> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--offset` | `int64` | 0 | Row offset for pagination |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--to` | `string` | today | End date (YYYY-MM-DD or GA relative date like today) |
diff --git a/docs/commands/gog-analytics.md b/docs/commands/gog-analytics.md
index 641558f90..3ea37339f 100644
--- a/docs/commands/gog-analytics.md
+++ b/docs/commands/gog-analytics.md
@@ -38,6 +38,7 @@ gog analytics (ga) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-appscript-content.md b/docs/commands/gog-appscript-content.md
index 1e0df325c..086c7581c 100644
--- a/docs/commands/gog-appscript-content.md
+++ b/docs/commands/gog-appscript-content.md
@@ -33,6 +33,7 @@ gog appscript (script,apps-script) content (cat) <scriptId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-appscript-create.md b/docs/commands/gog-appscript-create.md
index bfb605fb8..1b27c6b00 100644
--- a/docs/commands/gog-appscript-create.md
+++ b/docs/commands/gog-appscript-create.md
@@ -34,6 +34,7 @@ gog appscript (script,apps-script) create (new) --title=STRING [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent-id` | `string` |  | Optional Drive file ID to bind to |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--title` | `string` |  | Project title |
diff --git a/docs/commands/gog-appscript-get.md b/docs/commands/gog-appscript-get.md
index a6bfa0be5..78ffd66ad 100644
--- a/docs/commands/gog-appscript-get.md
+++ b/docs/commands/gog-appscript-get.md
@@ -33,6 +33,7 @@ gog appscript (script,apps-script) get (info,show) <scriptId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-appscript-run.md b/docs/commands/gog-appscript-run.md
index 59cf1e634..41075923d 100644
--- a/docs/commands/gog-appscript-run.md
+++ b/docs/commands/gog-appscript-run.md
@@ -35,6 +35,7 @@ gog appscript (script,apps-script) run <scriptId> <function> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--params` | `string` | [] | JSON array of function parameters |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-appscript.md b/docs/commands/gog-appscript.md
index 18379c5a5..8ebd9c17d 100644
--- a/docs/commands/gog-appscript.md
+++ b/docs/commands/gog-appscript.md
@@ -40,6 +40,7 @@ gog appscript (script,apps-script) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-add.md b/docs/commands/gog-auth-add.md
index aeff5664a..d6f6f3c6e 100644
--- a/docs/commands/gog-auth-add.md
+++ b/docs/commands/gog-auth-add.md
@@ -40,7 +40,7 @@ gog auth add <email> [flags]
 | `--manual` | `bool` |  | Browserless auth flow (paste redirect URL) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
-| `--readonly` | `bool` |  | Use read-only scopes where available (still includes OIDC identity scopes) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--redirect-host` | `string` |  | Hostname for OAuth callback in browser flows; builds https://{host}/oauth2/callback |
 | `--redirect-uri` | `string` |  | Override OAuth redirect URI for manual/remote flows (for example https://host.example/oauth2/callback) |
 | `--remote` | `bool` |  | Remote/server-friendly manual flow (print URL, then exchange code) |
diff --git a/docs/commands/gog-auth-alias-list.md b/docs/commands/gog-auth-alias-list.md
index e858d9872..12b246136 100644
--- a/docs/commands/gog-auth-alias-list.md
+++ b/docs/commands/gog-auth-alias-list.md
@@ -33,6 +33,7 @@ gog auth alias list
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-alias-set.md b/docs/commands/gog-auth-alias-set.md
index 361d8ce95..cb4fd48a6 100644
--- a/docs/commands/gog-auth-alias-set.md
+++ b/docs/commands/gog-auth-alias-set.md
@@ -33,6 +33,7 @@ gog auth alias set <alias> <email>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-alias-unset.md b/docs/commands/gog-auth-alias-unset.md
index 9d5542239..0be27ac5c 100644
--- a/docs/commands/gog-auth-alias-unset.md
+++ b/docs/commands/gog-auth-alias-unset.md
@@ -33,6 +33,7 @@ gog auth alias unset <alias>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-alias.md b/docs/commands/gog-auth-alias.md
index bd5068dbb..3e8515f24 100644
--- a/docs/commands/gog-auth-alias.md
+++ b/docs/commands/gog-auth-alias.md
@@ -39,6 +39,7 @@ gog auth alias <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-credentials-list.md b/docs/commands/gog-auth-credentials-list.md
index 74c7585ae..680db3f65 100644
--- a/docs/commands/gog-auth-credentials-list.md
+++ b/docs/commands/gog-auth-credentials-list.md
@@ -33,6 +33,7 @@ gog auth credentials list
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-credentials-remove.md b/docs/commands/gog-auth-credentials-remove.md
index 3a5542abb..03171d43c 100644
--- a/docs/commands/gog-auth-credentials-remove.md
+++ b/docs/commands/gog-auth-credentials-remove.md
@@ -33,6 +33,7 @@ gog auth credentials remove [<client>]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-credentials-set.md b/docs/commands/gog-auth-credentials-set.md
index e1c690ccd..db49ce4d5 100644
--- a/docs/commands/gog-auth-credentials-set.md
+++ b/docs/commands/gog-auth-credentials-set.md
@@ -36,6 +36,7 @@ gog auth credentials set <credentials> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-credentials.md b/docs/commands/gog-auth-credentials.md
index 39d2d79eb..8d2b4c3e3 100644
--- a/docs/commands/gog-auth-credentials.md
+++ b/docs/commands/gog-auth-credentials.md
@@ -39,6 +39,7 @@ gog auth credentials <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-doctor.md b/docs/commands/gog-auth-doctor.md
index 2f99c62fa..92e820b8d 100644
--- a/docs/commands/gog-auth-doctor.md
+++ b/docs/commands/gog-auth-doctor.md
@@ -34,6 +34,7 @@ gog auth doctor [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--timeout` | `time.Duration` | 15s | Per-token check timeout |
diff --git a/docs/commands/gog-auth-import.md b/docs/commands/gog-auth-import.md
index a3e0f334d..8578ae9bc 100644
--- a/docs/commands/gog-auth-import.md
+++ b/docs/commands/gog-auth-import.md
@@ -38,6 +38,7 @@ gog auth import --email=STRING [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--refresh-token-env` | `string` |  | Read OAuth refresh token from the named environment variable |
 | `--refresh-token-file` | `string` |  | Read OAuth refresh token from file |
 | `--refresh-token-stdin` | `bool` |  | Read OAuth refresh token from stdin |
diff --git a/docs/commands/gog-auth-keep.md b/docs/commands/gog-auth-keep.md
index 43753fe23..0a2939930 100644
--- a/docs/commands/gog-auth-keep.md
+++ b/docs/commands/gog-auth-keep.md
@@ -34,6 +34,7 @@ gog auth keep --key=STRING <email>
 | `--key` | `string` |  | Path to service account JSON key file |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-keyring.md b/docs/commands/gog-auth-keyring.md
index 345eab49d..3307c7493 100644
--- a/docs/commands/gog-auth-keyring.md
+++ b/docs/commands/gog-auth-keyring.md
@@ -33,6 +33,7 @@ gog auth keyring [<backend> [<backend2>]]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-list.md b/docs/commands/gog-auth-list.md
index 256742671..b871ee4f6 100644
--- a/docs/commands/gog-auth-list.md
+++ b/docs/commands/gog-auth-list.md
@@ -34,6 +34,7 @@ gog auth list [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--timeout` | `time.Duration` | 15s | Per-token check timeout |
diff --git a/docs/commands/gog-auth-manage.md b/docs/commands/gog-auth-manage.md
index 165c281bd..e316bcc3e 100644
--- a/docs/commands/gog-auth-manage.md
+++ b/docs/commands/gog-auth-manage.md
@@ -35,6 +35,7 @@ gog auth manage (login) [flags]
 | `--listen-addr` | `string` |  | Loopback address to listen on for the accounts manager (for example 127.0.0.1:8080 or [::1]:8080) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--redirect-host` | `string` |  | Hostname for OAuth callback; builds https://{host}/oauth2/callback |
 | `--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. |
diff --git a/docs/commands/gog-auth-remove.md b/docs/commands/gog-auth-remove.md
index afeb006c7..89107ab51 100644
--- a/docs/commands/gog-auth-remove.md
+++ b/docs/commands/gog-auth-remove.md
@@ -33,6 +33,7 @@ gog auth remove <email>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-service-account-set.md b/docs/commands/gog-auth-service-account-set.md
index ff9e1b1b1..c2c528c72 100644
--- a/docs/commands/gog-auth-service-account-set.md
+++ b/docs/commands/gog-auth-service-account-set.md
@@ -36,6 +36,7 @@ gog auth service-account set <email> [flags]
 | `--key-stdin` | `bool` |  | Read service account JSON key from stdin |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-service-account-status.md b/docs/commands/gog-auth-service-account-status.md
index 8e5dabed2..ede31661b 100644
--- a/docs/commands/gog-auth-service-account-status.md
+++ b/docs/commands/gog-auth-service-account-status.md
@@ -33,6 +33,7 @@ gog auth service-account status <email>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-service-account-unset.md b/docs/commands/gog-auth-service-account-unset.md
index 747fbddad..d476a8037 100644
--- a/docs/commands/gog-auth-service-account-unset.md
+++ b/docs/commands/gog-auth-service-account-unset.md
@@ -33,6 +33,7 @@ gog auth service-account unset <email>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-service-account.md b/docs/commands/gog-auth-service-account.md
index d66b608de..91cd38f71 100644
--- a/docs/commands/gog-auth-service-account.md
+++ b/docs/commands/gog-auth-service-account.md
@@ -39,6 +39,7 @@ gog auth service-account <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-services.md b/docs/commands/gog-auth-services.md
index 5e900c70b..5f5e476a3 100644
--- a/docs/commands/gog-auth-services.md
+++ b/docs/commands/gog-auth-services.md
@@ -34,6 +34,7 @@ gog auth services [flags]
 | `--markdown` | `bool` |  | Output Markdown table |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-status.md b/docs/commands/gog-auth-status.md
index ee08255af..798ece929 100644
--- a/docs/commands/gog-auth-status.md
+++ b/docs/commands/gog-auth-status.md
@@ -33,6 +33,7 @@ gog auth status
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-tokens-delete.md b/docs/commands/gog-auth-tokens-delete.md
index 4b1426290..5477adac7 100644
--- a/docs/commands/gog-auth-tokens-delete.md
+++ b/docs/commands/gog-auth-tokens-delete.md
@@ -33,6 +33,7 @@ gog auth tokens delete <email>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-tokens-export.md b/docs/commands/gog-auth-tokens-export.md
index 62521a76c..f730dc8e5 100644
--- a/docs/commands/gog-auth-tokens-export.md
+++ b/docs/commands/gog-auth-tokens-export.md
@@ -35,6 +35,7 @@ gog auth tokens export <email> [flags]
 | `--out`<br>`--output` | `string` |  | Output file path (required) |
 | `--overwrite` | `bool` |  | Overwrite output file if it exists |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-tokens-import.md b/docs/commands/gog-auth-tokens-import.md
index d987b7092..49ba1d69b 100644
--- a/docs/commands/gog-auth-tokens-import.md
+++ b/docs/commands/gog-auth-tokens-import.md
@@ -33,6 +33,7 @@ gog auth tokens import <inPath>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-tokens-list.md b/docs/commands/gog-auth-tokens-list.md
index 8971c9df3..6302a9031 100644
--- a/docs/commands/gog-auth-tokens-list.md
+++ b/docs/commands/gog-auth-tokens-list.md
@@ -33,6 +33,7 @@ gog auth tokens list
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-tokens.md b/docs/commands/gog-auth-tokens.md
index 91ec41930..9624d6afd 100644
--- a/docs/commands/gog-auth-tokens.md
+++ b/docs/commands/gog-auth-tokens.md
@@ -40,6 +40,7 @@ gog auth tokens <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth.md b/docs/commands/gog-auth.md
index d38fe257e..0a991d6bb 100644
--- a/docs/commands/gog-auth.md
+++ b/docs/commands/gog-auth.md
@@ -51,6 +51,7 @@ gog auth <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-backup-cat.md b/docs/commands/gog-backup-cat.md
index 658b7ea4e..4eb7fde8d 100644
--- a/docs/commands/gog-backup-cat.md
+++ b/docs/commands/gog-backup-cat.md
@@ -38,6 +38,7 @@ gog backup cat <shard> [flags]
 | `--out` | `string` |  | Write decrypted JSONL to this file instead of stdout |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print each JSONL row |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remote` | `string` |  | Backup Git remote URL |
 | `--repo` | `string` |  | Local backup repository path |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
diff --git a/docs/commands/gog-backup-export.md b/docs/commands/gog-backup-export.md
index 53cf54123..327c2d3e7 100644
--- a/docs/commands/gog-backup-export.md
+++ b/docs/commands/gog-backup-export.md
@@ -39,6 +39,7 @@ gog backup export [flags]
 | `--no-pull` | `bool` |  | Use local backup repository state without pulling first |
 | `--out` | `string` | ~/Documents/gog-backup-export | Plaintext export directory |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remote` | `string` |  | Backup Git remote URL |
 | `--repo` | `string` |  | Local backup repository path |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
diff --git a/docs/commands/gog-backup-gmail-push.md b/docs/commands/gog-backup-gmail-push.md
index 97bf52369..e7ef3941a 100644
--- a/docs/commands/gog-backup-gmail-push.md
+++ b/docs/commands/gog-backup-gmail-push.md
@@ -44,6 +44,7 @@ gog backup gmail push [flags]
 | `--no-push` | `bool` |  | Commit locally but do not push to the remote |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--query` | `string` |  | Gmail query for bounded/test backups |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--recipient` | `[]string` |  | Public age recipient (repeatable) |
 | `--remote` | `string` |  | Backup Git remote URL |
 | `--repo` | `string` |  | Local backup repository path |
diff --git a/docs/commands/gog-backup-gmail.md b/docs/commands/gog-backup-gmail.md
index 8773e48fd..200bc9d64 100644
--- a/docs/commands/gog-backup-gmail.md
+++ b/docs/commands/gog-backup-gmail.md
@@ -37,6 +37,7 @@ gog backup gmail <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-backup-init.md b/docs/commands/gog-backup-init.md
index 8574b53b7..2871c2efc 100644
--- a/docs/commands/gog-backup-init.md
+++ b/docs/commands/gog-backup-init.md
@@ -36,6 +36,7 @@ gog backup init [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--no-push` | `bool` |  | Commit locally but do not push to the remote |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--recipient` | `[]string` |  | Public age recipient (repeatable) |
 | `--remote` | `string` |  | Backup Git remote URL |
 | `--repo` | `string` |  | Local backup repository path |
diff --git a/docs/commands/gog-backup-push.md b/docs/commands/gog-backup-push.md
index 1b216b65b..231538663 100644
--- a/docs/commands/gog-backup-push.md
+++ b/docs/commands/gog-backup-push.md
@@ -50,6 +50,7 @@ gog backup push [flags]
 | `--no-push` | `bool` |  | Commit locally but do not push to the remote |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--query` | `string` |  | Gmail query for bounded/test backups |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--recipient` | `[]string` |  | Public age recipient (repeatable) |
 | `--remote` | `string` |  | Backup Git remote URL |
 | `--repo` | `string` |  | Local backup repository path |
diff --git a/docs/commands/gog-backup-status.md b/docs/commands/gog-backup-status.md
index 2f19bedbd..8cd3f7fab 100644
--- a/docs/commands/gog-backup-status.md
+++ b/docs/commands/gog-backup-status.md
@@ -36,6 +36,7 @@ gog backup status [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--no-pull` | `bool` |  | Use local backup repository state without pulling first |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remote` | `string` |  | Backup Git remote URL |
 | `--repo` | `string` |  | Local backup repository path |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
diff --git a/docs/commands/gog-backup-verify.md b/docs/commands/gog-backup-verify.md
index f5c0b2e52..cb95d620b 100644
--- a/docs/commands/gog-backup-verify.md
+++ b/docs/commands/gog-backup-verify.md
@@ -36,6 +36,7 @@ gog backup verify [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--no-pull` | `bool` |  | Use local backup repository state without pulling first |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remote` | `string` |  | Backup Git remote URL |
 | `--repo` | `string` |  | Local backup repository path |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
diff --git a/docs/commands/gog-backup.md b/docs/commands/gog-backup.md
index 71bb7d8fe..cff5dd5c4 100644
--- a/docs/commands/gog-backup.md
+++ b/docs/commands/gog-backup.md
@@ -43,6 +43,7 @@ gog backup <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-batch-abort.md b/docs/commands/gog-batch-abort.md
index 5453a4cd6..2a83fbae0 100644
--- a/docs/commands/gog-batch-abort.md
+++ b/docs/commands/gog-batch-abort.md
@@ -33,6 +33,7 @@ gog batch abort (rm,delete) <batchId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-batch-begin.md b/docs/commands/gog-batch-begin.md
index 01f6b6855..aff0f2376 100644
--- a/docs/commands/gog-batch-begin.md
+++ b/docs/commands/gog-batch-begin.md
@@ -35,6 +35,7 @@ gog batch begin --doc=STRING [flags]
 | `--name` | `string` |  | Optional batch label |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--service` | `string` | docs | Google API service |
diff --git a/docs/commands/gog-batch-end.md b/docs/commands/gog-batch-end.md
index 70949bcd3..d5bfa0362 100644
--- a/docs/commands/gog-batch-end.md
+++ b/docs/commands/gog-batch-end.md
@@ -35,6 +35,7 @@ gog batch end (submit) <batchId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-batch-list.md b/docs/commands/gog-batch-list.md
index 235fba96d..0334a32a9 100644
--- a/docs/commands/gog-batch-list.md
+++ b/docs/commands/gog-batch-list.md
@@ -33,6 +33,7 @@ gog batch list (ls)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-batch-prune.md b/docs/commands/gog-batch-prune.md
index 09efeed85..3694b97f9 100644
--- a/docs/commands/gog-batch-prune.md
+++ b/docs/commands/gog-batch-prune.md
@@ -34,6 +34,7 @@ gog batch prune [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--older-than` | `time.Duration` | 72h | Delete batches not updated within this duration |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-batch-show.md b/docs/commands/gog-batch-show.md
index 52f0e9725..2bf9be72b 100644
--- a/docs/commands/gog-batch-show.md
+++ b/docs/commands/gog-batch-show.md
@@ -33,6 +33,7 @@ gog batch show <batchId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-batch.md b/docs/commands/gog-batch.md
index d65acd58f..e6808c683 100644
--- a/docs/commands/gog-batch.md
+++ b/docs/commands/gog-batch.md
@@ -42,6 +42,7 @@ gog batch <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-acl.md b/docs/commands/gog-calendar-acl.md
index bed1cbf96..64b05bb05 100644
--- a/docs/commands/gog-calendar-acl.md
+++ b/docs/commands/gog-calendar-acl.md
@@ -37,6 +37,7 @@ gog calendar (cal) acl (permissions,perms) <calendarId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-alias-list.md b/docs/commands/gog-calendar-alias-list.md
index 844bdb092..179ce244e 100644
--- a/docs/commands/gog-calendar-alias-list.md
+++ b/docs/commands/gog-calendar-alias-list.md
@@ -33,6 +33,7 @@ gog calendar (cal) alias list
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-alias-set.md b/docs/commands/gog-calendar-alias-set.md
index b91b4c9eb..3600d2acd 100644
--- a/docs/commands/gog-calendar-alias-set.md
+++ b/docs/commands/gog-calendar-alias-set.md
@@ -33,6 +33,7 @@ gog calendar (cal) alias set <alias> <calendarId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-alias-unset.md b/docs/commands/gog-calendar-alias-unset.md
index d0e41ff4a..53f38a132 100644
--- a/docs/commands/gog-calendar-alias-unset.md
+++ b/docs/commands/gog-calendar-alias-unset.md
@@ -33,6 +33,7 @@ gog calendar (cal) alias unset <alias>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-alias.md b/docs/commands/gog-calendar-alias.md
index ebf248494..28cbc59b2 100644
--- a/docs/commands/gog-calendar-alias.md
+++ b/docs/commands/gog-calendar-alias.md
@@ -39,6 +39,7 @@ gog calendar (cal) alias <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-calendars.md b/docs/commands/gog-calendar-calendars.md
index c48c38817..2ff5d1843 100644
--- a/docs/commands/gog-calendar-calendars.md
+++ b/docs/commands/gog-calendar-calendars.md
@@ -37,6 +37,7 @@ gog calendar (cal) calendars [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-colors.md b/docs/commands/gog-calendar-colors.md
index 0ca0ac2da..6b97ba726 100644
--- a/docs/commands/gog-calendar-colors.md
+++ b/docs/commands/gog-calendar-colors.md
@@ -33,6 +33,7 @@ gog calendar (cal) colors
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-conflicts.md b/docs/commands/gog-calendar-conflicts.md
index 726f524ee..e4614dc8e 100644
--- a/docs/commands/gog-calendar-conflicts.md
+++ b/docs/commands/gog-calendar-conflicts.md
@@ -38,6 +38,7 @@ gog calendar (cal) conflicts [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--to` | `string` |  | End time (RFC3339, date, or relative) |
diff --git a/docs/commands/gog-calendar-create-calendar.md b/docs/commands/gog-calendar-create-calendar.md
index 007bd869b..07d52f73c 100644
--- a/docs/commands/gog-calendar-create-calendar.md
+++ b/docs/commands/gog-calendar-create-calendar.md
@@ -35,6 +35,7 @@ gog calendar (cal) create-calendar (new-calendar) <summary> [flags]
 | `--location` | `string` |  | Calendar location |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--timezone`<br>`--tz` | `string` |  | IANA timezone (e.g., America/New_York) |
diff --git a/docs/commands/gog-calendar-create.md b/docs/commands/gog-calendar-create.md
index 9ca32d7bd..e8b280e24 100644
--- a/docs/commands/gog-calendar-create.md
+++ b/docs/commands/gog-calendar-create.md
@@ -56,6 +56,7 @@ gog calendar (cal) create (add,new) <calendarId> [flags]
 | `--place-region` | `string` |  | Places API region code for location lookup |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--private-prop` | `[]string` |  | Private extended property (key=value, can be repeated) |
+| `--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). |
 | `--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. |
diff --git a/docs/commands/gog-calendar-delete-calendar.md b/docs/commands/gog-calendar-delete-calendar.md
index 86addfc51..e93da6e77 100644
--- a/docs/commands/gog-calendar-delete-calendar.md
+++ b/docs/commands/gog-calendar-delete-calendar.md
@@ -33,6 +33,7 @@ gog calendar (cal) delete-calendar <calendarId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-delete.md b/docs/commands/gog-calendar-delete.md
index 38cc81ce2..d045ebaec 100644
--- a/docs/commands/gog-calendar-delete.md
+++ b/docs/commands/gog-calendar-delete.md
@@ -34,6 +34,7 @@ gog calendar (cal) delete (rm,del,remove) <calendarId> <eventId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--original-start` | `string` |  | Original start time of instance (required for scope=single,future) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--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. |
diff --git a/docs/commands/gog-calendar-event.md b/docs/commands/gog-calendar-event.md
index 58f6bda82..f65bc9570 100644
--- a/docs/commands/gog-calendar-event.md
+++ b/docs/commands/gog-calendar-event.md
@@ -33,6 +33,7 @@ gog calendar (cal) event (get,info,show) <calendarId> <eventId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-events.md b/docs/commands/gog-calendar-events.md
index 746de1e8d..def997c5b 100644
--- a/docs/commands/gog-calendar-events.md
+++ b/docs/commands/gog-calendar-events.md
@@ -47,6 +47,7 @@ gog calendar (cal) events (list,ls) [<calendarId> ...] [flags]
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--private-prop-filter` | `string` |  | Filter by private extended property (key=value) |
 | `--query` | `string` |  | Free text search |
+| `--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. |
 | `--shared-prop-filter` | `string` |  | Filter by shared extended property (key=value) |
diff --git a/docs/commands/gog-calendar-focus-time.md b/docs/commands/gog-calendar-focus-time.md
index 256caa94d..ef2a5c134 100644
--- a/docs/commands/gog-calendar-focus-time.md
+++ b/docs/commands/gog-calendar-focus-time.md
@@ -37,6 +37,7 @@ gog calendar (cal) focus-time (focus) --from=STRING --to=STRING [<calendarId>] [
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--rrule` | `[]string` |  | Recurrence rules. 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. |
diff --git a/docs/commands/gog-calendar-freebusy.md b/docs/commands/gog-calendar-freebusy.md
index 7c4cc7bbf..7634a2d77 100644
--- a/docs/commands/gog-calendar-freebusy.md
+++ b/docs/commands/gog-calendar-freebusy.md
@@ -36,6 +36,7 @@ gog calendar (cal) freebusy [<calendarIds>] [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--to` | `string` |  | End time (RFC3339 with timezone, date, or relative: now, today, tomorrow, monday) |
diff --git a/docs/commands/gog-calendar-move.md b/docs/commands/gog-calendar-move.md
index e0e7c4d66..22aa14678 100644
--- a/docs/commands/gog-calendar-move.md
+++ b/docs/commands/gog-calendar-move.md
@@ -33,6 +33,7 @@ gog calendar (cal) move (transfer) <calendarId> <eventId> <destinationCalendarId
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 (default: none) |
diff --git a/docs/commands/gog-calendar-out-of-office.md b/docs/commands/gog-calendar-out-of-office.md
index 3caeaa37a..d4e2c10e2 100644
--- a/docs/commands/gog-calendar-out-of-office.md
+++ b/docs/commands/gog-calendar-out-of-office.md
@@ -37,6 +37,7 @@ gog calendar (cal) out-of-office (ooo) --from=STRING --to=STRING [<calendarId>]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--summary` | `string` | Out of office | Out of office title |
diff --git a/docs/commands/gog-calendar-propose-time.md b/docs/commands/gog-calendar-propose-time.md
index 3c73298a8..91fafa5e8 100644
--- a/docs/commands/gog-calendar-propose-time.md
+++ b/docs/commands/gog-calendar-propose-time.md
@@ -36,6 +36,7 @@ gog calendar (cal) propose-time <calendarId> <eventId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--open` | `bool` |  | Open the URL in browser automatically |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-raw.md b/docs/commands/gog-calendar-raw.md
index 8ebfbfbc1..31c6809c6 100644
--- a/docs/commands/gog-calendar-raw.md
+++ b/docs/commands/gog-calendar-raw.md
@@ -34,6 +34,7 @@ gog calendar (cal) raw <calendarId> <eventId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-respond.md b/docs/commands/gog-calendar-respond.md
index 9b82cbf52..f2fd6708f 100644
--- a/docs/commands/gog-calendar-respond.md
+++ b/docs/commands/gog-calendar-respond.md
@@ -34,6 +34,7 @@ gog calendar (cal) respond (rsvp,reply) <calendarId> <eventId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--status` | `string` |  | Response status (accepted, declined, tentative, needsAction) |
diff --git a/docs/commands/gog-calendar-search.md b/docs/commands/gog-calendar-search.md
index 8c28b1cea..9c1b3ea2e 100644
--- a/docs/commands/gog-calendar-search.md
+++ b/docs/commands/gog-calendar-search.md
@@ -37,6 +37,7 @@ gog calendar (cal) search (find,query) <query> [flags]
 | `--max`<br>`--limit` | `int64` | 25 | Max results |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--to` | `string` |  | End time (RFC3339, date, or relative: now, today, tomorrow, monday) |
diff --git a/docs/commands/gog-calendar-subscribe.md b/docs/commands/gog-calendar-subscribe.md
index bae3b998e..e749a13f9 100644
--- a/docs/commands/gog-calendar-subscribe.md
+++ b/docs/commands/gog-calendar-subscribe.md
@@ -35,6 +35,7 @@ gog calendar (cal) subscribe (sub,add-calendar) <calendarId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--selected` | `bool` | true | Show events in the calendar UI |
diff --git a/docs/commands/gog-calendar-team.md b/docs/commands/gog-calendar-team.md
index a5f788f29..f73802e00 100644
--- a/docs/commands/gog-calendar-team.md
+++ b/docs/commands/gog-calendar-team.md
@@ -39,6 +39,7 @@ gog calendar (cal) team <group-email> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `-q`<br>`--query` | `string` |  | Filter events by title (case-insensitive) |
+| `--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. |
 | `--to` | `string` |  | End time (RFC3339, date, or relative: now, today, tomorrow, monday) |
diff --git a/docs/commands/gog-calendar-time.md b/docs/commands/gog-calendar-time.md
index ab0bc9504..9df7348bd 100644
--- a/docs/commands/gog-calendar-time.md
+++ b/docs/commands/gog-calendar-time.md
@@ -34,6 +34,7 @@ gog calendar (cal) time [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--timezone` | `string` |  | Override timezone (e.g., America/New_York, UTC) |
diff --git a/docs/commands/gog-calendar-unsubscribe.md b/docs/commands/gog-calendar-unsubscribe.md
index d71f7a047..073c51591 100644
--- a/docs/commands/gog-calendar-unsubscribe.md
+++ b/docs/commands/gog-calendar-unsubscribe.md
@@ -33,6 +33,7 @@ gog calendar (cal) unsubscribe (unsub) <calendarId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-update.md b/docs/commands/gog-calendar-update.md
index e7f62e345..f07d2924c 100644
--- a/docs/commands/gog-calendar-update.md
+++ b/docs/commands/gog-calendar-update.md
@@ -58,6 +58,7 @@ gog calendar (cal) update (edit,set) <calendarId> <eventId> [flags]
 | `--place-region` | `string` |  | Places API region code for location lookup |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--private-prop` | `[]string` |  | Private extended property (key=value, can be repeated) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--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 clear. |
diff --git a/docs/commands/gog-calendar-users.md b/docs/commands/gog-calendar-users.md
index 035505743..f8a5ebdca 100644
--- a/docs/commands/gog-calendar-users.md
+++ b/docs/commands/gog-calendar-users.md
@@ -37,6 +37,7 @@ gog calendar (cal) users [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-calendar-working-location.md b/docs/commands/gog-calendar-working-location.md
index 80054e0da..892128920 100644
--- a/docs/commands/gog-calendar-working-location.md
+++ b/docs/commands/gog-calendar-working-location.md
@@ -39,6 +39,7 @@ gog calendar (cal) working-location (wl) --from=STRING --to=STRING --type=STRING
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--office-label` | `string` |  | Office name/label |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--to` | `string` |  | End date (YYYY-MM-DD) |
diff --git a/docs/commands/gog-calendar.md b/docs/commands/gog-calendar.md
index d8f41499e..a49a36644 100644
--- a/docs/commands/gog-calendar.md
+++ b/docs/commands/gog-calendar.md
@@ -62,6 +62,7 @@ gog calendar (cal) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-dm-send.md b/docs/commands/gog-chat-dm-send.md
index 50823b0dd..2f775509e 100644
--- a/docs/commands/gog-chat-dm-send.md
+++ b/docs/commands/gog-chat-dm-send.md
@@ -33,6 +33,7 @@ gog chat dm send (create,post) <email> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--text` | `string` |  | Message text (required) |
diff --git a/docs/commands/gog-chat-dm-space.md b/docs/commands/gog-chat-dm-space.md
index 20479c102..04a1b61a9 100644
--- a/docs/commands/gog-chat-dm-space.md
+++ b/docs/commands/gog-chat-dm-space.md
@@ -33,6 +33,7 @@ gog chat dm space (find,setup) <email>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-dm.md b/docs/commands/gog-chat-dm.md
index 956255b28..d07d05f0b 100644
--- a/docs/commands/gog-chat-dm.md
+++ b/docs/commands/gog-chat-dm.md
@@ -38,6 +38,7 @@ gog chat dm <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-messages-list.md b/docs/commands/gog-chat-messages-list.md
index b6e3c9b7a..879bebbe9 100644
--- a/docs/commands/gog-chat-messages-list.md
+++ b/docs/commands/gog-chat-messages-list.md
@@ -38,6 +38,7 @@ gog chat messages list (ls) <space> [flags]
 | `--order` | `string` |  | Order by (e.g. createTime desc) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--thread` | `string` |  | Filter by thread (spaces/.../threads/...) |
diff --git a/docs/commands/gog-chat-messages-react.md b/docs/commands/gog-chat-messages-react.md
index da86b5cd5..405e3f336 100644
--- a/docs/commands/gog-chat-messages-react.md
+++ b/docs/commands/gog-chat-messages-react.md
@@ -33,6 +33,7 @@ gog chat messages react <message> <emoji> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--space` | `string` |  | Space name (required when message is a bare ID) |
diff --git a/docs/commands/gog-chat-messages-reactions-create.md b/docs/commands/gog-chat-messages-reactions-create.md
index 3d0f9b924..d26a83dfb 100644
--- a/docs/commands/gog-chat-messages-reactions-create.md
+++ b/docs/commands/gog-chat-messages-reactions-create.md
@@ -33,6 +33,7 @@ gog chat messages reactions (reaction) create (add) <message> <emoji> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--space` | `string` |  | Space name (required when message is a bare ID) |
diff --git a/docs/commands/gog-chat-messages-reactions-delete.md b/docs/commands/gog-chat-messages-reactions-delete.md
index 36f90963f..6b9999d86 100644
--- a/docs/commands/gog-chat-messages-reactions-delete.md
+++ b/docs/commands/gog-chat-messages-reactions-delete.md
@@ -33,6 +33,7 @@ gog chat messages reactions (reaction) delete (remove,rm) <reaction>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-messages-reactions-list.md b/docs/commands/gog-chat-messages-reactions-list.md
index 4cc8bcd33..9a4cd9354 100644
--- a/docs/commands/gog-chat-messages-reactions-list.md
+++ b/docs/commands/gog-chat-messages-reactions-list.md
@@ -36,6 +36,7 @@ gog chat messages reactions (reaction) list (ls) <message> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--space` | `string` |  | Space name (required when message is a bare ID) |
diff --git a/docs/commands/gog-chat-messages-reactions.md b/docs/commands/gog-chat-messages-reactions.md
index c5db613b2..b86c54f07 100644
--- a/docs/commands/gog-chat-messages-reactions.md
+++ b/docs/commands/gog-chat-messages-reactions.md
@@ -39,6 +39,7 @@ gog chat messages reactions (reaction) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-messages-send.md b/docs/commands/gog-chat-messages-send.md
index a3e577d23..0759ec333 100644
--- a/docs/commands/gog-chat-messages-send.md
+++ b/docs/commands/gog-chat-messages-send.md
@@ -34,6 +34,7 @@ gog chat messages send (create,post) <space> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--text` | `string` |  | Message text (required unless --attach is provided) |
diff --git a/docs/commands/gog-chat-messages.md b/docs/commands/gog-chat-messages.md
index a365b5631..a8895db44 100644
--- a/docs/commands/gog-chat-messages.md
+++ b/docs/commands/gog-chat-messages.md
@@ -40,6 +40,7 @@ gog chat messages <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-spaces-create.md b/docs/commands/gog-chat-spaces-create.md
index efce2bd60..d3963bc70 100644
--- a/docs/commands/gog-chat-spaces-create.md
+++ b/docs/commands/gog-chat-spaces-create.md
@@ -34,6 +34,7 @@ gog chat spaces create (add,new) <displayName> [flags]
 | `--member` | `[]string` |  | Space members (email or users/...; repeatable or comma-separated) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-spaces-find.md b/docs/commands/gog-chat-spaces-find.md
index fbf0e5c41..d7918680b 100644
--- a/docs/commands/gog-chat-spaces-find.md
+++ b/docs/commands/gog-chat-spaces-find.md
@@ -35,6 +35,7 @@ gog chat spaces find (search,query) <displayName> [flags]
 | `--max`<br>`--limit` | `int64` | 100 | Max results per page |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-spaces-list.md b/docs/commands/gog-chat-spaces-list.md
index deacb4903..715358e89 100644
--- a/docs/commands/gog-chat-spaces-list.md
+++ b/docs/commands/gog-chat-spaces-list.md
@@ -37,6 +37,7 @@ gog chat spaces list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-spaces.md b/docs/commands/gog-chat-spaces.md
index 018c71be4..0595b3c62 100644
--- a/docs/commands/gog-chat-spaces.md
+++ b/docs/commands/gog-chat-spaces.md
@@ -39,6 +39,7 @@ gog chat spaces <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-threads-list.md b/docs/commands/gog-chat-threads-list.md
index 82ab0ba82..00312f19b 100644
--- a/docs/commands/gog-chat-threads-list.md
+++ b/docs/commands/gog-chat-threads-list.md
@@ -37,6 +37,7 @@ gog chat threads list <space> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat-threads.md b/docs/commands/gog-chat-threads.md
index 42033d6a9..8983a7dc5 100644
--- a/docs/commands/gog-chat-threads.md
+++ b/docs/commands/gog-chat-threads.md
@@ -37,6 +37,7 @@ gog chat threads <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-chat.md b/docs/commands/gog-chat.md
index 2d51c95d8..7b6c3ab4f 100644
--- a/docs/commands/gog-chat.md
+++ b/docs/commands/gog-chat.md
@@ -40,6 +40,7 @@ gog chat <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-announcements-assignees.md b/docs/commands/gog-classroom-announcements-assignees.md
index 288d940ba..363d72cf7 100644
--- a/docs/commands/gog-classroom-announcements-assignees.md
+++ b/docs/commands/gog-classroom-announcements-assignees.md
@@ -35,6 +35,7 @@ gog classroom (class) announcements (announcement,ann) assignees (assign) <cours
 | `--mode` | `string` |  | Assignee mode: ALL_STUDENTS, INDIVIDUAL_STUDENTS |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remove-student` | `[]string` |  | Student IDs to remove |
 | `--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. |
diff --git a/docs/commands/gog-classroom-announcements-create.md b/docs/commands/gog-classroom-announcements-create.md
index 7349c9594..9960a02f8 100644
--- a/docs/commands/gog-classroom-announcements-create.md
+++ b/docs/commands/gog-classroom-announcements-create.md
@@ -33,6 +33,7 @@ gog classroom (class) announcements (announcement,ann) create (add,new) --text=S
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--scheduled` | `string` |  | Scheduled publish time (RFC3339) |
 | `--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. |
diff --git a/docs/commands/gog-classroom-announcements-delete.md b/docs/commands/gog-classroom-announcements-delete.md
index 76e288aaa..a713b19c3 100644
--- a/docs/commands/gog-classroom-announcements-delete.md
+++ b/docs/commands/gog-classroom-announcements-delete.md
@@ -33,6 +33,7 @@ gog classroom (class) announcements (announcement,ann) delete (rm,del,remove) <c
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-announcements-get.md b/docs/commands/gog-classroom-announcements-get.md
index ad6600a7e..5125eb07b 100644
--- a/docs/commands/gog-classroom-announcements-get.md
+++ b/docs/commands/gog-classroom-announcements-get.md
@@ -33,6 +33,7 @@ gog classroom (class) announcements (announcement,ann) get (info,show) <courseId
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-announcements-list.md b/docs/commands/gog-classroom-announcements-list.md
index 270d9fcca..519dfe499 100644
--- a/docs/commands/gog-classroom-announcements-list.md
+++ b/docs/commands/gog-classroom-announcements-list.md
@@ -38,6 +38,7 @@ gog classroom (class) announcements (announcement,ann) list (ls) <courseId> [fla
 | `--order-by` | `string` |  | Order by (e.g., updateTime desc) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--state` | `string` |  | Announcement states filter (comma-separated: DRAFT,PUBLISHED,DELETED) |
diff --git a/docs/commands/gog-classroom-announcements-update.md b/docs/commands/gog-classroom-announcements-update.md
index 5210b8940..3644375cb 100644
--- a/docs/commands/gog-classroom-announcements-update.md
+++ b/docs/commands/gog-classroom-announcements-update.md
@@ -33,6 +33,7 @@ gog classroom (class) announcements (announcement,ann) update (edit,set) <course
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--scheduled` | `string` |  | Scheduled publish time (RFC3339) |
 | `--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. |
diff --git a/docs/commands/gog-classroom-announcements.md b/docs/commands/gog-classroom-announcements.md
index e85956c2f..8a66ee535 100644
--- a/docs/commands/gog-classroom-announcements.md
+++ b/docs/commands/gog-classroom-announcements.md
@@ -42,6 +42,7 @@ gog classroom (class) announcements (announcement,ann) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-courses-archive.md b/docs/commands/gog-classroom-courses-archive.md
index a9716b1e1..45431c343 100644
--- a/docs/commands/gog-classroom-courses-archive.md
+++ b/docs/commands/gog-classroom-courses-archive.md
@@ -33,6 +33,7 @@ gog classroom (class) courses (course) archive (arch) <courseId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-courses-create.md b/docs/commands/gog-classroom-courses-create.md
index ff7a382df..432dbdb04 100644
--- a/docs/commands/gog-classroom-courses-create.md
+++ b/docs/commands/gog-classroom-courses-create.md
@@ -37,6 +37,7 @@ gog classroom (class) courses (course) create (add,new) --name=STRING [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--owner` | `string` | me | Owner user ID or email |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--room` | `string` |  | Room |
 | `--section` | `string` |  | Section |
diff --git a/docs/commands/gog-classroom-courses-delete.md b/docs/commands/gog-classroom-courses-delete.md
index b712178ad..9710976ae 100644
--- a/docs/commands/gog-classroom-courses-delete.md
+++ b/docs/commands/gog-classroom-courses-delete.md
@@ -33,6 +33,7 @@ gog classroom (class) courses (course) delete (rm,del,remove) <courseId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-courses-get.md b/docs/commands/gog-classroom-courses-get.md
index 702b4a4af..7e8f0923b 100644
--- a/docs/commands/gog-classroom-courses-get.md
+++ b/docs/commands/gog-classroom-courses-get.md
@@ -33,6 +33,7 @@ gog classroom (class) courses (course) get (info,show) <courseId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-courses-join.md b/docs/commands/gog-classroom-courses-join.md
index 6d85e59fb..c04647f0d 100644
--- a/docs/commands/gog-classroom-courses-join.md
+++ b/docs/commands/gog-classroom-courses-join.md
@@ -34,6 +34,7 @@ gog classroom (class) courses (course) join (enroll) <courseId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--role` | `string` | student | Role to join as: student\|teacher |
 | `--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. |
diff --git a/docs/commands/gog-classroom-courses-leave.md b/docs/commands/gog-classroom-courses-leave.md
index d4d4fd427..a4544157e 100644
--- a/docs/commands/gog-classroom-courses-leave.md
+++ b/docs/commands/gog-classroom-courses-leave.md
@@ -33,6 +33,7 @@ gog classroom (class) courses (course) leave (unenroll) <courseId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--role` | `string` | student | Role to remove: student\|teacher |
 | `--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. |
diff --git a/docs/commands/gog-classroom-courses-list.md b/docs/commands/gog-classroom-courses-list.md
index f7a7e8f44..fa9606534 100644
--- a/docs/commands/gog-classroom-courses-list.md
+++ b/docs/commands/gog-classroom-courses-list.md
@@ -37,6 +37,7 @@ gog classroom (class) courses (course) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--state` | `string` |  | Course states filter (comma-separated: ACTIVE,ARCHIVED,PROVISIONED,DECLINED) |
diff --git a/docs/commands/gog-classroom-courses-unarchive.md b/docs/commands/gog-classroom-courses-unarchive.md
index fb57d646f..5372d4a2a 100644
--- a/docs/commands/gog-classroom-courses-unarchive.md
+++ b/docs/commands/gog-classroom-courses-unarchive.md
@@ -33,6 +33,7 @@ gog classroom (class) courses (course) unarchive (unarch,restore) <courseId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-courses-update.md b/docs/commands/gog-classroom-courses-update.md
index 2e0bb12f1..588bfebb6 100644
--- a/docs/commands/gog-classroom-courses-update.md
+++ b/docs/commands/gog-classroom-courses-update.md
@@ -37,6 +37,7 @@ gog classroom (class) courses (course) update (edit,set) <courseId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--owner` | `string` |  | Owner user ID or email |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--room` | `string` |  | Room |
 | `--section` | `string` |  | Section |
diff --git a/docs/commands/gog-classroom-courses-url.md b/docs/commands/gog-classroom-courses-url.md
index 5b6607b98..620fb6eb2 100644
--- a/docs/commands/gog-classroom-courses-url.md
+++ b/docs/commands/gog-classroom-courses-url.md
@@ -33,6 +33,7 @@ gog classroom (class) courses (course) url (link) <courseId> ...
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-courses.md b/docs/commands/gog-classroom-courses.md
index dc2d7a806..c8f428202 100644
--- a/docs/commands/gog-classroom-courses.md
+++ b/docs/commands/gog-classroom-courses.md
@@ -46,6 +46,7 @@ gog classroom (class) courses (course) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-coursework-assignees.md b/docs/commands/gog-classroom-coursework-assignees.md
index 451a0f5cb..938462c0e 100644
--- a/docs/commands/gog-classroom-coursework-assignees.md
+++ b/docs/commands/gog-classroom-coursework-assignees.md
@@ -35,6 +35,7 @@ gog classroom (class) coursework (work) assignees (assign) <courseId> <coursewor
 | `--mode` | `string` |  | Assignee mode: ALL_STUDENTS, INDIVIDUAL_STUDENTS |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remove-student` | `[]string` |  | Student IDs to remove |
 | `--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. |
diff --git a/docs/commands/gog-classroom-coursework-create.md b/docs/commands/gog-classroom-coursework-create.md
index c5578067e..bcb8dfe01 100644
--- a/docs/commands/gog-classroom-coursework-create.md
+++ b/docs/commands/gog-classroom-coursework-create.md
@@ -38,6 +38,7 @@ gog classroom (class) coursework (work) create (add,new) --title=STRING <courseI
 | `--max-points` | `float64` |  | Max points |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--scheduled` | `string` |  | Scheduled publish time (RFC3339) |
 | `--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. |
diff --git a/docs/commands/gog-classroom-coursework-delete.md b/docs/commands/gog-classroom-coursework-delete.md
index 938cf7387..c7348feb3 100644
--- a/docs/commands/gog-classroom-coursework-delete.md
+++ b/docs/commands/gog-classroom-coursework-delete.md
@@ -33,6 +33,7 @@ gog classroom (class) coursework (work) delete (rm,del,remove) <courseId> <cours
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-coursework-get.md b/docs/commands/gog-classroom-coursework-get.md
index 6ee004f7d..3b53b22ae 100644
--- a/docs/commands/gog-classroom-coursework-get.md
+++ b/docs/commands/gog-classroom-coursework-get.md
@@ -33,6 +33,7 @@ gog classroom (class) coursework (work) get (info,show) <courseId> <courseworkId
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-coursework-list.md b/docs/commands/gog-classroom-coursework-list.md
index 0a7c9b19b..8522ea810 100644
--- a/docs/commands/gog-classroom-coursework-list.md
+++ b/docs/commands/gog-classroom-coursework-list.md
@@ -38,6 +38,7 @@ gog classroom (class) coursework (work) list (ls) <courseId> [flags]
 | `--order-by` | `string` |  | Order by (e.g., updateTime desc, dueDate desc) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--scan-pages` | `int` | 3 | Pages to scan when filtering by topic |
 | `--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. |
diff --git a/docs/commands/gog-classroom-coursework-update.md b/docs/commands/gog-classroom-coursework-update.md
index 2e643d5e0..7c0ca459d 100644
--- a/docs/commands/gog-classroom-coursework-update.md
+++ b/docs/commands/gog-classroom-coursework-update.md
@@ -38,6 +38,7 @@ gog classroom (class) coursework (work) update (edit,set) <courseId> <coursework
 | `--max-points` | `float64` |  | Max points |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--scheduled` | `string` |  | Scheduled publish time (RFC3339) |
 | `--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. |
diff --git a/docs/commands/gog-classroom-coursework.md b/docs/commands/gog-classroom-coursework.md
index a63550129..cf0def5cd 100644
--- a/docs/commands/gog-classroom-coursework.md
+++ b/docs/commands/gog-classroom-coursework.md
@@ -42,6 +42,7 @@ gog classroom (class) coursework (work) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-guardian-invitations-create.md b/docs/commands/gog-classroom-guardian-invitations-create.md
index 3f9af50f0..06644de88 100644
--- a/docs/commands/gog-classroom-guardian-invitations-create.md
+++ b/docs/commands/gog-classroom-guardian-invitations-create.md
@@ -34,6 +34,7 @@ gog classroom (class) guardian-invitations (guardian-invites) create (add,new) -
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-guardian-invitations-get.md b/docs/commands/gog-classroom-guardian-invitations-get.md
index 63de664d3..1533c55e4 100644
--- a/docs/commands/gog-classroom-guardian-invitations-get.md
+++ b/docs/commands/gog-classroom-guardian-invitations-get.md
@@ -33,6 +33,7 @@ gog classroom (class) guardian-invitations (guardian-invites) get (info,show) <s
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-guardian-invitations-list.md b/docs/commands/gog-classroom-guardian-invitations-list.md
index 3a3958026..eea9b62a3 100644
--- a/docs/commands/gog-classroom-guardian-invitations-list.md
+++ b/docs/commands/gog-classroom-guardian-invitations-list.md
@@ -38,6 +38,7 @@ gog classroom (class) guardian-invitations (guardian-invites) list (ls) <student
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--state` | `string` |  | Invitation states filter (comma-separated: PENDING,COMPLETE) |
diff --git a/docs/commands/gog-classroom-guardian-invitations.md b/docs/commands/gog-classroom-guardian-invitations.md
index 07ca69f9d..5212e0bae 100644
--- a/docs/commands/gog-classroom-guardian-invitations.md
+++ b/docs/commands/gog-classroom-guardian-invitations.md
@@ -39,6 +39,7 @@ gog classroom (class) guardian-invitations (guardian-invites) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-guardians-delete.md b/docs/commands/gog-classroom-guardians-delete.md
index 942d8d7fd..f59d5a854 100644
--- a/docs/commands/gog-classroom-guardians-delete.md
+++ b/docs/commands/gog-classroom-guardians-delete.md
@@ -33,6 +33,7 @@ gog classroom (class) guardians (guardian) delete (rm,del,remove) <studentId> <g
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-guardians-get.md b/docs/commands/gog-classroom-guardians-get.md
index 949e49528..1b7961f56 100644
--- a/docs/commands/gog-classroom-guardians-get.md
+++ b/docs/commands/gog-classroom-guardians-get.md
@@ -33,6 +33,7 @@ gog classroom (class) guardians (guardian) get (info,show) <studentId> <guardian
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-guardians-list.md b/docs/commands/gog-classroom-guardians-list.md
index f3a7dd32d..c6ab0623b 100644
--- a/docs/commands/gog-classroom-guardians-list.md
+++ b/docs/commands/gog-classroom-guardians-list.md
@@ -38,6 +38,7 @@ gog classroom (class) guardians (guardian) list (ls) <studentId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-guardians.md b/docs/commands/gog-classroom-guardians.md
index d6d003c7a..a559ac1ef 100644
--- a/docs/commands/gog-classroom-guardians.md
+++ b/docs/commands/gog-classroom-guardians.md
@@ -39,6 +39,7 @@ gog classroom (class) guardians (guardian) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-invitations-accept.md b/docs/commands/gog-classroom-invitations-accept.md
index 814074221..f398364c3 100644
--- a/docs/commands/gog-classroom-invitations-accept.md
+++ b/docs/commands/gog-classroom-invitations-accept.md
@@ -33,6 +33,7 @@ gog classroom (class) invitations (invitation,invites) accept (join) <invitation
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-invitations-create.md b/docs/commands/gog-classroom-invitations-create.md
index 0ddb8a2e2..d1329289c 100644
--- a/docs/commands/gog-classroom-invitations-create.md
+++ b/docs/commands/gog-classroom-invitations-create.md
@@ -33,6 +33,7 @@ gog classroom (class) invitations (invitation,invites) create (add,new) --role=S
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--role` | `string` |  | Role: STUDENT, TEACHER, OWNER |
 | `--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. |
diff --git a/docs/commands/gog-classroom-invitations-delete.md b/docs/commands/gog-classroom-invitations-delete.md
index 77849a86e..a94b7ea18 100644
--- a/docs/commands/gog-classroom-invitations-delete.md
+++ b/docs/commands/gog-classroom-invitations-delete.md
@@ -33,6 +33,7 @@ gog classroom (class) invitations (invitation,invites) delete (rm,del,remove) <i
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-invitations-get.md b/docs/commands/gog-classroom-invitations-get.md
index cdd15e611..1fe4a0825 100644
--- a/docs/commands/gog-classroom-invitations-get.md
+++ b/docs/commands/gog-classroom-invitations-get.md
@@ -33,6 +33,7 @@ gog classroom (class) invitations (invitation,invites) get (info,show) <invitati
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-invitations-list.md b/docs/commands/gog-classroom-invitations-list.md
index c0066a42f..43dd37ba7 100644
--- a/docs/commands/gog-classroom-invitations-list.md
+++ b/docs/commands/gog-classroom-invitations-list.md
@@ -38,6 +38,7 @@ gog classroom (class) invitations (invitation,invites) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--user` | `string` |  | Filter by user ID or email (required when --course is omitted) |
diff --git a/docs/commands/gog-classroom-invitations.md b/docs/commands/gog-classroom-invitations.md
index ed8cd91a7..4a0a11398 100644
--- a/docs/commands/gog-classroom-invitations.md
+++ b/docs/commands/gog-classroom-invitations.md
@@ -41,6 +41,7 @@ gog classroom (class) invitations (invitation,invites) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-materials-create.md b/docs/commands/gog-classroom-materials-create.md
index 2b7b7a0c3..fe1c983ba 100644
--- a/docs/commands/gog-classroom-materials-create.md
+++ b/docs/commands/gog-classroom-materials-create.md
@@ -34,6 +34,7 @@ gog classroom (class) materials (material) create (add,new) --title=STRING <cour
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--scheduled` | `string` |  | Scheduled publish time (RFC3339) |
 | `--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. |
diff --git a/docs/commands/gog-classroom-materials-delete.md b/docs/commands/gog-classroom-materials-delete.md
index 97daf13e0..ae6e33815 100644
--- a/docs/commands/gog-classroom-materials-delete.md
+++ b/docs/commands/gog-classroom-materials-delete.md
@@ -33,6 +33,7 @@ gog classroom (class) materials (material) delete (rm,del,remove) <courseId> <ma
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-materials-get.md b/docs/commands/gog-classroom-materials-get.md
index 46683051a..2d75d56a2 100644
--- a/docs/commands/gog-classroom-materials-get.md
+++ b/docs/commands/gog-classroom-materials-get.md
@@ -33,6 +33,7 @@ gog classroom (class) materials (material) get (info,show) <courseId> <materialI
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-materials-list.md b/docs/commands/gog-classroom-materials-list.md
index 3a1e14758..aa9696541 100644
--- a/docs/commands/gog-classroom-materials-list.md
+++ b/docs/commands/gog-classroom-materials-list.md
@@ -38,6 +38,7 @@ gog classroom (class) materials (material) list (ls) <courseId> [flags]
 | `--order-by` | `string` |  | Order by (e.g., updateTime desc) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--scan-pages` | `int` | 3 | Pages to scan when filtering by topic |
 | `--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. |
diff --git a/docs/commands/gog-classroom-materials-update.md b/docs/commands/gog-classroom-materials-update.md
index 1ce041360..685ddf8b4 100644
--- a/docs/commands/gog-classroom-materials-update.md
+++ b/docs/commands/gog-classroom-materials-update.md
@@ -34,6 +34,7 @@ gog classroom (class) materials (material) update (edit,set) <courseId> <materia
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--scheduled` | `string` |  | Scheduled publish time (RFC3339) |
 | `--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. |
diff --git a/docs/commands/gog-classroom-materials.md b/docs/commands/gog-classroom-materials.md
index 73153a499..8fd2ac269 100644
--- a/docs/commands/gog-classroom-materials.md
+++ b/docs/commands/gog-classroom-materials.md
@@ -41,6 +41,7 @@ gog classroom (class) materials (material) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-profile-get.md b/docs/commands/gog-classroom-profile-get.md
index 6cf74373b..5ac601acf 100644
--- a/docs/commands/gog-classroom-profile-get.md
+++ b/docs/commands/gog-classroom-profile-get.md
@@ -33,6 +33,7 @@ gog classroom (class) profile (me) get [<userId>]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-profile.md b/docs/commands/gog-classroom-profile.md
index a23849de2..b940534e5 100644
--- a/docs/commands/gog-classroom-profile.md
+++ b/docs/commands/gog-classroom-profile.md
@@ -37,6 +37,7 @@ gog classroom (class) profile (me) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-roster.md b/docs/commands/gog-classroom-roster.md
index 61d2f1878..86639656c 100644
--- a/docs/commands/gog-classroom-roster.md
+++ b/docs/commands/gog-classroom-roster.md
@@ -37,6 +37,7 @@ gog classroom (class) roster (members) <courseId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token (per role) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--students` | `bool` |  | Include students |
diff --git a/docs/commands/gog-classroom-students-add.md b/docs/commands/gog-classroom-students-add.md
index bf2e9194c..392dba8cd 100644
--- a/docs/commands/gog-classroom-students-add.md
+++ b/docs/commands/gog-classroom-students-add.md
@@ -34,6 +34,7 @@ gog classroom (class) students (student) add (create,new) <courseId> <userId> [f
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-students-get.md b/docs/commands/gog-classroom-students-get.md
index efbb5b734..f5501a575 100644
--- a/docs/commands/gog-classroom-students-get.md
+++ b/docs/commands/gog-classroom-students-get.md
@@ -33,6 +33,7 @@ gog classroom (class) students (student) get (info,show) <courseId> <userId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-students-list.md b/docs/commands/gog-classroom-students-list.md
index beac28edf..840b6a21a 100644
--- a/docs/commands/gog-classroom-students-list.md
+++ b/docs/commands/gog-classroom-students-list.md
@@ -37,6 +37,7 @@ gog classroom (class) students (student) list (ls) <courseId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-students-remove.md b/docs/commands/gog-classroom-students-remove.md
index 4a66d8b68..3f7f00d44 100644
--- a/docs/commands/gog-classroom-students-remove.md
+++ b/docs/commands/gog-classroom-students-remove.md
@@ -33,6 +33,7 @@ gog classroom (class) students (student) remove (delete,rm,del) <courseId> <user
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-students.md b/docs/commands/gog-classroom-students.md
index 4d3ccea59..c7b3654c1 100644
--- a/docs/commands/gog-classroom-students.md
+++ b/docs/commands/gog-classroom-students.md
@@ -40,6 +40,7 @@ gog classroom (class) students (student) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-submissions-get.md b/docs/commands/gog-classroom-submissions-get.md
index e703b122c..4547012ba 100644
--- a/docs/commands/gog-classroom-submissions-get.md
+++ b/docs/commands/gog-classroom-submissions-get.md
@@ -33,6 +33,7 @@ gog classroom (class) submissions (submission) get (info,show) <courseId> <cours
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-submissions-grade.md b/docs/commands/gog-classroom-submissions-grade.md
index c743246de..aa761b15f 100644
--- a/docs/commands/gog-classroom-submissions-grade.md
+++ b/docs/commands/gog-classroom-submissions-grade.md
@@ -35,6 +35,7 @@ gog classroom (class) submissions (submission) grade (set,edit) <courseId> <cour
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-submissions-list.md b/docs/commands/gog-classroom-submissions-list.md
index 6c486f21b..524c0f3ba 100644
--- a/docs/commands/gog-classroom-submissions-list.md
+++ b/docs/commands/gog-classroom-submissions-list.md
@@ -38,6 +38,7 @@ gog classroom (class) submissions (submission) list (ls) <courseId> <courseworkI
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--state` | `string` |  | Submission states filter (comma-separated: NEW,CREATED,TURNED_IN,RETURNED,RECLAIMED_BY_STUDENT) |
diff --git a/docs/commands/gog-classroom-submissions-reclaim.md b/docs/commands/gog-classroom-submissions-reclaim.md
index 03f27a82c..e5c5a7528 100644
--- a/docs/commands/gog-classroom-submissions-reclaim.md
+++ b/docs/commands/gog-classroom-submissions-reclaim.md
@@ -33,6 +33,7 @@ gog classroom (class) submissions (submission) reclaim (undo) <courseId> <course
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-submissions-return.md b/docs/commands/gog-classroom-submissions-return.md
index 8bfa4318b..518b8ea18 100644
--- a/docs/commands/gog-classroom-submissions-return.md
+++ b/docs/commands/gog-classroom-submissions-return.md
@@ -33,6 +33,7 @@ gog classroom (class) submissions (submission) return (send) <courseId> <coursew
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-submissions-turn-in.md b/docs/commands/gog-classroom-submissions-turn-in.md
index 88d01f2fb..d07be1f1e 100644
--- a/docs/commands/gog-classroom-submissions-turn-in.md
+++ b/docs/commands/gog-classroom-submissions-turn-in.md
@@ -33,6 +33,7 @@ gog classroom (class) submissions (submission) turn-in (turnin) <courseId> <cour
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-submissions.md b/docs/commands/gog-classroom-submissions.md
index 3d53531fc..a0d9b6c25 100644
--- a/docs/commands/gog-classroom-submissions.md
+++ b/docs/commands/gog-classroom-submissions.md
@@ -42,6 +42,7 @@ gog classroom (class) submissions (submission) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-teachers-add.md b/docs/commands/gog-classroom-teachers-add.md
index 30c70a472..1f28dc1d5 100644
--- a/docs/commands/gog-classroom-teachers-add.md
+++ b/docs/commands/gog-classroom-teachers-add.md
@@ -33,6 +33,7 @@ gog classroom (class) teachers (teacher) add (create,new) <courseId> <userId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-teachers-get.md b/docs/commands/gog-classroom-teachers-get.md
index a40106dfe..7baa7c921 100644
--- a/docs/commands/gog-classroom-teachers-get.md
+++ b/docs/commands/gog-classroom-teachers-get.md
@@ -33,6 +33,7 @@ gog classroom (class) teachers (teacher) get (info,show) <courseId> <userId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-teachers-list.md b/docs/commands/gog-classroom-teachers-list.md
index 7504112f0..30d81acd9 100644
--- a/docs/commands/gog-classroom-teachers-list.md
+++ b/docs/commands/gog-classroom-teachers-list.md
@@ -37,6 +37,7 @@ gog classroom (class) teachers (teacher) list (ls) <courseId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-teachers-remove.md b/docs/commands/gog-classroom-teachers-remove.md
index 0e3e91bcf..e45f4cfe4 100644
--- a/docs/commands/gog-classroom-teachers-remove.md
+++ b/docs/commands/gog-classroom-teachers-remove.md
@@ -33,6 +33,7 @@ gog classroom (class) teachers (teacher) remove (delete,rm,del) <courseId> <user
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-teachers.md b/docs/commands/gog-classroom-teachers.md
index 7bb9392b3..3d6514acc 100644
--- a/docs/commands/gog-classroom-teachers.md
+++ b/docs/commands/gog-classroom-teachers.md
@@ -40,6 +40,7 @@ gog classroom (class) teachers (teacher) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-topics-create.md b/docs/commands/gog-classroom-topics-create.md
index 0b94c262d..97bbc918b 100644
--- a/docs/commands/gog-classroom-topics-create.md
+++ b/docs/commands/gog-classroom-topics-create.md
@@ -34,6 +34,7 @@ gog classroom (class) topics (topic) create (add,new) --name=STRING <courseId>
 | `--name` | `string` |  | Topic name |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-topics-delete.md b/docs/commands/gog-classroom-topics-delete.md
index 703ad712e..effd68421 100644
--- a/docs/commands/gog-classroom-topics-delete.md
+++ b/docs/commands/gog-classroom-topics-delete.md
@@ -33,6 +33,7 @@ gog classroom (class) topics (topic) delete (rm,del,remove) <courseId> <topicId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-topics-get.md b/docs/commands/gog-classroom-topics-get.md
index b2445e8df..50c3d7340 100644
--- a/docs/commands/gog-classroom-topics-get.md
+++ b/docs/commands/gog-classroom-topics-get.md
@@ -33,6 +33,7 @@ gog classroom (class) topics (topic) get (info,show) <courseId> <topicId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-topics-list.md b/docs/commands/gog-classroom-topics-list.md
index fdb613feb..6123279cc 100644
--- a/docs/commands/gog-classroom-topics-list.md
+++ b/docs/commands/gog-classroom-topics-list.md
@@ -37,6 +37,7 @@ gog classroom (class) topics (topic) list (ls) <courseId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-topics-update.md b/docs/commands/gog-classroom-topics-update.md
index bc280c56d..0f3192578 100644
--- a/docs/commands/gog-classroom-topics-update.md
+++ b/docs/commands/gog-classroom-topics-update.md
@@ -34,6 +34,7 @@ gog classroom (class) topics (topic) update (edit,set) --name=STRING <courseId>
 | `--name` | `string` |  | Topic name |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom-topics.md b/docs/commands/gog-classroom-topics.md
index 071311e3c..609618897 100644
--- a/docs/commands/gog-classroom-topics.md
+++ b/docs/commands/gog-classroom-topics.md
@@ -41,6 +41,7 @@ gog classroom (class) topics (topic) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-classroom.md b/docs/commands/gog-classroom.md
index 4d1270b48..7d35315f4 100644
--- a/docs/commands/gog-classroom.md
+++ b/docs/commands/gog-classroom.md
@@ -49,6 +49,7 @@ gog classroom (class) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-completion.md b/docs/commands/gog-completion.md
index 1751842a6..813d9aafb 100644
--- a/docs/commands/gog-completion.md
+++ b/docs/commands/gog-completion.md
@@ -33,6 +33,7 @@ gog completion <shell> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config-get.md b/docs/commands/gog-config-get.md
index 8bfd54e12..f621bd64c 100644
--- a/docs/commands/gog-config-get.md
+++ b/docs/commands/gog-config-get.md
@@ -33,6 +33,7 @@ gog config get (show) <key>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config-keys.md b/docs/commands/gog-config-keys.md
index 764631339..bd71bd30d 100644
--- a/docs/commands/gog-config-keys.md
+++ b/docs/commands/gog-config-keys.md
@@ -33,6 +33,7 @@ gog config keys (list-keys,names)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config-list.md b/docs/commands/gog-config-list.md
index 9ba10c2d6..d2f666c63 100644
--- a/docs/commands/gog-config-list.md
+++ b/docs/commands/gog-config-list.md
@@ -33,6 +33,7 @@ gog config list (ls,all)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config-no-send-list.md b/docs/commands/gog-config-no-send-list.md
index aa64f683b..3718e3fc3 100644
--- a/docs/commands/gog-config-no-send-list.md
+++ b/docs/commands/gog-config-no-send-list.md
@@ -33,6 +33,7 @@ gog config no-send (nosend) list (ls)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config-no-send-remove.md b/docs/commands/gog-config-no-send-remove.md
index 7662c1145..06e43d889 100644
--- a/docs/commands/gog-config-no-send-remove.md
+++ b/docs/commands/gog-config-no-send-remove.md
@@ -33,6 +33,7 @@ gog config no-send (nosend) remove (rm,del,delete,unset,disable) <account>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config-no-send-set.md b/docs/commands/gog-config-no-send-set.md
index 283f653ac..2dbadfd96 100644
--- a/docs/commands/gog-config-no-send-set.md
+++ b/docs/commands/gog-config-no-send-set.md
@@ -33,6 +33,7 @@ gog config no-send (nosend) set (add,enable) <account>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config-no-send.md b/docs/commands/gog-config-no-send.md
index 433ce7293..54772c9af 100644
--- a/docs/commands/gog-config-no-send.md
+++ b/docs/commands/gog-config-no-send.md
@@ -39,6 +39,7 @@ gog config no-send (nosend) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config-path.md b/docs/commands/gog-config-path.md
index ec949ece7..be8a377ff 100644
--- a/docs/commands/gog-config-path.md
+++ b/docs/commands/gog-config-path.md
@@ -33,6 +33,7 @@ gog config path (where)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config-set.md b/docs/commands/gog-config-set.md
index 0520fe540..e0042127d 100644
--- a/docs/commands/gog-config-set.md
+++ b/docs/commands/gog-config-set.md
@@ -33,6 +33,7 @@ gog config set (add,update) <key> <value>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config-unset.md b/docs/commands/gog-config-unset.md
index f0c090239..d6c578e06 100644
--- a/docs/commands/gog-config-unset.md
+++ b/docs/commands/gog-config-unset.md
@@ -33,6 +33,7 @@ gog config unset (rm,del,remove) <key>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-config.md b/docs/commands/gog-config.md
index b82b3aeb2..ba2e5a0fe 100644
--- a/docs/commands/gog-config.md
+++ b/docs/commands/gog-config.md
@@ -43,6 +43,7 @@ gog config <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-create.md b/docs/commands/gog-contacts-create.md
index 713803066..7ba8b8e2a 100644
--- a/docs/commands/gog-contacts-create.md
+++ b/docs/commands/gog-contacts-create.md
@@ -42,6 +42,7 @@ gog contacts (contact) create (add,new) [flags]
 | `--org` | `string` |  | Organization/company name |
 | `--phone` | `string` |  | Phone number |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--relation` | `[]string` |  | Relation as type=person (can be repeated) |
 | `--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. |
diff --git a/docs/commands/gog-contacts-dedupe.md b/docs/commands/gog-contacts-dedupe.md
index 6454a8b44..a5a92459a 100644
--- a/docs/commands/gog-contacts-dedupe.md
+++ b/docs/commands/gog-contacts-dedupe.md
@@ -37,6 +37,7 @@ gog contacts (contact) dedupe [flags]
 | `--max`<br>`--limit` | `int64` | 0 | Max contacts to scan (0 = all) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--resource` | `[]string` |  | Limit dedupe to exact contact resource names (people/...); repeatable |
 | `--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. |
diff --git a/docs/commands/gog-contacts-delete.md b/docs/commands/gog-contacts-delete.md
index 4d3cdb27b..8dffc1897 100644
--- a/docs/commands/gog-contacts-delete.md
+++ b/docs/commands/gog-contacts-delete.md
@@ -33,6 +33,7 @@ gog contacts (contact) delete (rm,del,remove) <resourceName>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-directory-list.md b/docs/commands/gog-contacts-directory-list.md
index 626b8b94e..59ddcad6a 100644
--- a/docs/commands/gog-contacts-directory-list.md
+++ b/docs/commands/gog-contacts-directory-list.md
@@ -37,6 +37,7 @@ gog contacts (contact) directory list [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-directory-search.md b/docs/commands/gog-contacts-directory-search.md
index 02d1ac0e4..e8649cfcd 100644
--- a/docs/commands/gog-contacts-directory-search.md
+++ b/docs/commands/gog-contacts-directory-search.md
@@ -37,6 +37,7 @@ gog contacts (contact) directory search <query> ... [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-directory.md b/docs/commands/gog-contacts-directory.md
index eeb768b74..8c7f7384c 100644
--- a/docs/commands/gog-contacts-directory.md
+++ b/docs/commands/gog-contacts-directory.md
@@ -38,6 +38,7 @@ gog contacts (contact) directory <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-export.md b/docs/commands/gog-contacts-export.md
index 24db92dab..af02d3edc 100644
--- a/docs/commands/gog-contacts-export.md
+++ b/docs/commands/gog-contacts-export.md
@@ -39,6 +39,7 @@ gog contacts (contact) export [<selector>] [flags]
 | `--page-size` | `int64` | 1000 | Page size for --all (1-1000) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--query` | `string` |  | Search query to export (max 30 results) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-get.md b/docs/commands/gog-contacts-get.md
index f4c68194a..c7ae4ca83 100644
--- a/docs/commands/gog-contacts-get.md
+++ b/docs/commands/gog-contacts-get.md
@@ -33,6 +33,7 @@ gog contacts (contact) get (info,show) <resourceName>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-list.md b/docs/commands/gog-contacts-list.md
index cf538c043..5af221314 100644
--- a/docs/commands/gog-contacts-list.md
+++ b/docs/commands/gog-contacts-list.md
@@ -35,6 +35,7 @@ gog contacts (contact) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-other-list.md b/docs/commands/gog-contacts-other-list.md
index 03439159c..223474fdd 100644
--- a/docs/commands/gog-contacts-other-list.md
+++ b/docs/commands/gog-contacts-other-list.md
@@ -37,6 +37,7 @@ gog contacts (contact) other list [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-other-search.md b/docs/commands/gog-contacts-other-search.md
index a40b73437..93df116f1 100644
--- a/docs/commands/gog-contacts-other-search.md
+++ b/docs/commands/gog-contacts-other-search.md
@@ -34,6 +34,7 @@ gog contacts (contact) other search <query> ... [flags]
 | `--max`<br>`--limit` | `int64` | 50 | Max results |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-other.md b/docs/commands/gog-contacts-other.md
index 17453e4f4..3ae0204c8 100644
--- a/docs/commands/gog-contacts-other.md
+++ b/docs/commands/gog-contacts-other.md
@@ -38,6 +38,7 @@ gog contacts (contact) other <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-raw.md b/docs/commands/gog-contacts-raw.md
index 99002064b..d483c1c6e 100644
--- a/docs/commands/gog-contacts-raw.md
+++ b/docs/commands/gog-contacts-raw.md
@@ -35,6 +35,7 @@ gog contacts (contact) raw <identifier> [flags]
 | `--person-fields` | `string` |  | People API personFields mask (default: broad set) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-search.md b/docs/commands/gog-contacts-search.md
index 8018d98fd..decb2f9ab 100644
--- a/docs/commands/gog-contacts-search.md
+++ b/docs/commands/gog-contacts-search.md
@@ -34,6 +34,7 @@ gog contacts (contact) search <query> ... [flags]
 | `--max`<br>`--limit` | `int64` | 50 | Max results |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-contacts-update.md b/docs/commands/gog-contacts-update.md
index 4e6e4d56e..29ba02ade 100644
--- a/docs/commands/gog-contacts-update.md
+++ b/docs/commands/gog-contacts-update.md
@@ -46,6 +46,7 @@ gog contacts (contact) update (edit,set) <resourceName> [flags]
 | `--org` | `string` |  | Organization/company name (empty clears) |
 | `--phone` | `string` |  | Phone number (empty clears) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--relation` | `[]string` |  | Relation as type=person (can be repeated; empty clears all) |
 | `--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. |
diff --git a/docs/commands/gog-contacts.md b/docs/commands/gog-contacts.md
index 0bcfda9f0..ddc7379f9 100644
--- a/docs/commands/gog-contacts.md
+++ b/docs/commands/gog-contacts.md
@@ -47,6 +47,7 @@ gog contacts (contact) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-add-tab.md b/docs/commands/gog-docs-add-tab.md
index 50613c9eb..613d5ff78 100644
--- a/docs/commands/gog-docs-add-tab.md
+++ b/docs/commands/gog-docs-add-tab.md
@@ -36,6 +36,7 @@ gog docs (doc) add-tab <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent-tab` | `string` |  | Optional parent tab title or ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--title` | `string` |  | User-visible tab title |
diff --git a/docs/commands/gog-docs-cat.md b/docs/commands/gog-docs-cat.md
index 0494e57f5..ba186ba9e 100644
--- a/docs/commands/gog-docs-cat.md
+++ b/docs/commands/gog-docs-cat.md
@@ -37,6 +37,7 @@ gog docs (doc) cat (text,read) <docId> [flags]
 | `-N`<br>`--numbered` | `bool` |  | Prefix each paragraph with its number |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--raw` | `bool` |  | Output the raw Google Docs API JSON response without modifications |
+| `--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. |
 | `--tab` | `string` |  | Tab title or ID to read (omit for default behavior) |
diff --git a/docs/commands/gog-docs-cell-style.md b/docs/commands/gog-docs-cell-style.md
index d87e0eff0..8ed254746 100644
--- a/docs/commands/gog-docs-cell-style.md
+++ b/docs/commands/gog-docs-cell-style.md
@@ -50,6 +50,7 @@ gog docs (doc) cell-style --row=INT --col=INT <docId> [flags]
 | `--padding-right` | `string` |  | Right cell padding; overrides --padding-all |
 | `--padding-top` | `string` |  | Top cell padding; overrides --padding-all |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--row` | `int` |  | 1-based row number |
 | `--row-span` | `int64` | 1 | Number of rows to style |
diff --git a/docs/commands/gog-docs-cell-update.md b/docs/commands/gog-docs-cell-update.md
index de7801a06..19c7e22cf 100644
--- a/docs/commands/gog-docs-cell-update.md
+++ b/docs/commands/gog-docs-cell-update.md
@@ -38,6 +38,7 @@ gog docs (doc) cell-update (update-cell) --row=INT --col=INT <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--row` | `int` |  | 1-based row number |
 | `--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. |
diff --git a/docs/commands/gog-docs-clear.md b/docs/commands/gog-docs-clear.md
index 577f495bb..9f29b771c 100644
--- a/docs/commands/gog-docs-clear.md
+++ b/docs/commands/gog-docs-clear.md
@@ -33,6 +33,7 @@ gog docs (doc) clear <docId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-comments-add.md b/docs/commands/gog-docs-comments-add.md
index f71cfdc5b..cb0655f52 100644
--- a/docs/commands/gog-docs-comments-add.md
+++ b/docs/commands/gog-docs-comments-add.md
@@ -35,6 +35,7 @@ gog docs (doc) comments add (create,new) <docId> <content> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--quoted` | `string` |  | Quoted text to attach to the comment (shown in UIs when available) |
+| `--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 |
diff --git a/docs/commands/gog-docs-comments-delete.md b/docs/commands/gog-docs-comments-delete.md
index f9660e0a3..9bbe4560b 100644
--- a/docs/commands/gog-docs-comments-delete.md
+++ b/docs/commands/gog-docs-comments-delete.md
@@ -33,6 +33,7 @@ gog docs (doc) comments delete (rm,del,remove) <docId> <commentId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-comments-get.md b/docs/commands/gog-docs-comments-get.md
index 1e48d5110..fb98951e9 100644
--- a/docs/commands/gog-docs-comments-get.md
+++ b/docs/commands/gog-docs-comments-get.md
@@ -33,6 +33,7 @@ gog docs (doc) comments get (info,show) <docId> <commentId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-comments-list.md b/docs/commands/gog-docs-comments-list.md
index a3c64d81c..060615a05 100644
--- a/docs/commands/gog-docs-comments-list.md
+++ b/docs/commands/gog-docs-comments-list.md
@@ -38,6 +38,7 @@ gog docs (doc) comments list (ls) <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token for pagination |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--since` | `string` |  | Only return comments modified at or after this RFC3339 timestamp |
diff --git a/docs/commands/gog-docs-comments-locate.md b/docs/commands/gog-docs-comments-locate.md
index 18c837e82..415ebd7a6 100644
--- a/docs/commands/gog-docs-comments-locate.md
+++ b/docs/commands/gog-docs-comments-locate.md
@@ -35,6 +35,7 @@ gog docs (doc) comments locate <docId> <commentId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--normalize-whitespace` | `bool` | true | Collapse whitespace while matching |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-comments-poll.md b/docs/commands/gog-docs-comments-poll.md
index 6dab96967..33bf49eaa 100644
--- a/docs/commands/gog-docs-comments-poll.md
+++ b/docs/commands/gog-docs-comments-poll.md
@@ -38,6 +38,7 @@ gog docs (doc) comments poll --state-file=STRING <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--on-new` | `string` |  | Trusted local shell command run for each comment; comment event JSON is provided on stdin |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--state-file` | `string` |  | JSON file that stores the comment time watermark |
diff --git a/docs/commands/gog-docs-comments-reopen.md b/docs/commands/gog-docs-comments-reopen.md
index 8fd32882d..aec15f1b4 100644
--- a/docs/commands/gog-docs-comments-reopen.md
+++ b/docs/commands/gog-docs-comments-reopen.md
@@ -34,6 +34,7 @@ gog docs (doc) comments reopen <docId> <commentId> [flags]
 | `-m`<br>`--message` | `string` |  | Optional message to include when reopening |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-comments-reply.md b/docs/commands/gog-docs-comments-reply.md
index 587b699ed..f7ba49ee5 100644
--- a/docs/commands/gog-docs-comments-reply.md
+++ b/docs/commands/gog-docs-comments-reply.md
@@ -34,6 +34,7 @@ gog docs (doc) comments reply (respond) <docId> <commentId> <content> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-comments-resolve.md b/docs/commands/gog-docs-comments-resolve.md
index 3d6dabe6e..221924d57 100644
--- a/docs/commands/gog-docs-comments-resolve.md
+++ b/docs/commands/gog-docs-comments-resolve.md
@@ -34,6 +34,7 @@ gog docs (doc) comments resolve <docId> <commentId> [flags]
 | `-m`<br>`--message` | `string` |  | Optional message to include when resolving |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-comments.md b/docs/commands/gog-docs-comments.md
index 0902cf7cb..968c81386 100644
--- a/docs/commands/gog-docs-comments.md
+++ b/docs/commands/gog-docs-comments.md
@@ -45,6 +45,7 @@ gog docs (doc) comments <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-copy.md b/docs/commands/gog-docs-copy.md
index dc6cf90f2..97dade55a 100644
--- a/docs/commands/gog-docs-copy.md
+++ b/docs/commands/gog-docs-copy.md
@@ -34,6 +34,7 @@ gog docs (doc) copy (cp,duplicate) <docId> <title> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Destination folder ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-create.md b/docs/commands/gog-docs-create.md
index f98aeeb06..0a7e60b55 100644
--- a/docs/commands/gog-docs-create.md
+++ b/docs/commands/gog-docs-create.md
@@ -36,6 +36,7 @@ gog docs (doc) create (add,new) <title> [flags]
 | `--pageless` | `bool` |  | Set document to pageless mode |
 | `--parent` | `string` |  | Destination folder ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-delete-tab.md b/docs/commands/gog-docs-delete-tab.md
index 1015176a6..b81b69864 100644
--- a/docs/commands/gog-docs-delete-tab.md
+++ b/docs/commands/gog-docs-delete-tab.md
@@ -33,6 +33,7 @@ gog docs (doc) delete-tab <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Existing tab title or ID |
diff --git a/docs/commands/gog-docs-delete.md b/docs/commands/gog-docs-delete.md
index 4e936189f..16023f80f 100644
--- a/docs/commands/gog-docs-delete.md
+++ b/docs/commands/gog-docs-delete.md
@@ -38,6 +38,7 @@ gog docs (doc) delete <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--segment` | `string` |  | Target an exact header, footer, or footnote segment ID |
 | `--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. |
diff --git a/docs/commands/gog-docs-edit.md b/docs/commands/gog-docs-edit.md
index 4ce0d2497..20f15b780 100644
--- a/docs/commands/gog-docs-edit.md
+++ b/docs/commands/gog-docs-edit.md
@@ -34,6 +34,7 @@ gog docs (doc) edit <docId> <find> <replace> [flags]
 | `--match-case` | `bool` |  | Case-sensitive matching |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-export.md b/docs/commands/gog-docs-export.md
index c139e8859..cdd3d73ed 100644
--- a/docs/commands/gog-docs-export.md
+++ b/docs/commands/gog-docs-export.md
@@ -36,6 +36,7 @@ gog docs (doc) export (download,dl) <docId> [flags]
 | `--out`<br>`--output` | `string` |  | Output file path (default: gogcli config dir) |
 | `--overwrite` | `bool` |  | Overwrite an existing output file |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | (experimental) Export a specific tab by title or ID (see 'gog docs list-tabs') |
diff --git a/docs/commands/gog-docs-find-range.md b/docs/commands/gog-docs-find-range.md
index 3c1df15b7..83c33a04c 100644
--- a/docs/commands/gog-docs-find-range.md
+++ b/docs/commands/gog-docs-find-range.md
@@ -38,6 +38,7 @@ gog docs (doc) find-range <docId> <text> [flags]
 | `--normalize-whitespace` | `bool` | true | Collapse whitespace while matching |
 | `--occurrence` | `*int` |  | Return the Nth occurrence (1-based; default first) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--segment` | `string` |  | Target an exact header, footer, or footnote segment ID |
 | `--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. |
diff --git a/docs/commands/gog-docs-find-replace.md b/docs/commands/gog-docs-find-replace.md
index 5866a345f..24b0d9301 100644
--- a/docs/commands/gog-docs-find-replace.md
+++ b/docs/commands/gog-docs-find-replace.md
@@ -37,6 +37,7 @@ gog docs (doc) find-replace <docId> <find> [<replace>] [flags]
 | `--match-case` | `bool` |  | Case-sensitive matching |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-footer-create.md b/docs/commands/gog-docs-footer-create.md
index 79f699cc9..1db33c37b 100644
--- a/docs/commands/gog-docs-footer-create.md
+++ b/docs/commands/gog-docs-footer-create.md
@@ -39,6 +39,7 @@ gog docs (doc) footer (footers) create (add,new) <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-footer-delete.md b/docs/commands/gog-docs-footer-delete.md
index 1b6d49f56..edb284d72 100644
--- a/docs/commands/gog-docs-footer-delete.md
+++ b/docs/commands/gog-docs-footer-delete.md
@@ -33,6 +33,7 @@ gog docs (doc) footer (footers) delete (rm,remove,del) <docId> <footerId> [flags
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Tab title or ID containing the footer |
diff --git a/docs/commands/gog-docs-footer-list.md b/docs/commands/gog-docs-footer-list.md
index 471cc765e..560f5c180 100644
--- a/docs/commands/gog-docs-footer-list.md
+++ b/docs/commands/gog-docs-footer-list.md
@@ -33,6 +33,7 @@ gog docs (doc) footer (footers) list (ls) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Limit results to a tab title or ID |
diff --git a/docs/commands/gog-docs-footer.md b/docs/commands/gog-docs-footer.md
index 4e15b7da8..74712f8cc 100644
--- a/docs/commands/gog-docs-footer.md
+++ b/docs/commands/gog-docs-footer.md
@@ -39,6 +39,7 @@ gog docs (doc) footer (footers) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-format.md b/docs/commands/gog-docs-format.md
index 549edec7f..2131727ca 100644
--- a/docs/commands/gog-docs-format.md
+++ b/docs/commands/gog-docs-format.md
@@ -62,6 +62,7 @@ gog docs (doc) format <docId> [flags]
 | `--no-underline` | `bool` |  | Clear underline |
 | `--ordered` | `bool` |  | Create a numbered list with the default decimal preset |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--segment` | `string` |  | Target an exact header, footer, or footnote segment ID |
 | `--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. |
diff --git a/docs/commands/gog-docs-header-create.md b/docs/commands/gog-docs-header-create.md
index 4c7aed7db..496d4c51e 100644
--- a/docs/commands/gog-docs-header-create.md
+++ b/docs/commands/gog-docs-header-create.md
@@ -39,6 +39,7 @@ gog docs (doc) header (headers) create (add,new) <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-header-delete.md b/docs/commands/gog-docs-header-delete.md
index 0bd2646e4..22318b6a4 100644
--- a/docs/commands/gog-docs-header-delete.md
+++ b/docs/commands/gog-docs-header-delete.md
@@ -33,6 +33,7 @@ gog docs (doc) header (headers) delete (rm,remove,del) <docId> <headerId> [flags
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Tab title or ID containing the header |
diff --git a/docs/commands/gog-docs-header-list.md b/docs/commands/gog-docs-header-list.md
index 2b24b5ef1..7f2fe5293 100644
--- a/docs/commands/gog-docs-header-list.md
+++ b/docs/commands/gog-docs-header-list.md
@@ -33,6 +33,7 @@ gog docs (doc) header (headers) list (ls) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Limit results to a tab title or ID |
diff --git a/docs/commands/gog-docs-header.md b/docs/commands/gog-docs-header.md
index 584f53341..7f6ed4827 100644
--- a/docs/commands/gog-docs-header.md
+++ b/docs/commands/gog-docs-header.md
@@ -39,6 +39,7 @@ gog docs (doc) header (headers) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-headings-list.md b/docs/commands/gog-docs-headings-list.md
index e51f3b32f..fb56d6bfb 100644
--- a/docs/commands/gog-docs-headings-list.md
+++ b/docs/commands/gog-docs-headings-list.md
@@ -34,6 +34,7 @@ gog docs (doc) headings list (ls) <docId> [flags]
 | `--level` | `int` |  | Only return this heading level (1-6) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Tab title or ID (omit for default) |
diff --git a/docs/commands/gog-docs-headings.md b/docs/commands/gog-docs-headings.md
index a7a9e0f39..0e91303d6 100644
--- a/docs/commands/gog-docs-headings.md
+++ b/docs/commands/gog-docs-headings.md
@@ -37,6 +37,7 @@ gog docs (doc) headings <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-images-list.md b/docs/commands/gog-docs-images-list.md
index 734ca8d33..36206ef98 100644
--- a/docs/commands/gog-docs-images-list.md
+++ b/docs/commands/gog-docs-images-list.md
@@ -33,6 +33,7 @@ gog docs (doc) images list (ls) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Tab title or ID (omit for default) |
diff --git a/docs/commands/gog-docs-images.md b/docs/commands/gog-docs-images.md
index 30bd822e1..b742b833d 100644
--- a/docs/commands/gog-docs-images.md
+++ b/docs/commands/gog-docs-images.md
@@ -37,6 +37,7 @@ gog docs (doc) images <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-info.md b/docs/commands/gog-docs-info.md
index f518e0893..d862fa523 100644
--- a/docs/commands/gog-docs-info.md
+++ b/docs/commands/gog-docs-info.md
@@ -33,6 +33,7 @@ gog docs (doc) info (get,show) <docId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-insert-date-chip.md b/docs/commands/gog-docs-insert-date-chip.md
index c5dd3c467..a5f6decbc 100644
--- a/docs/commands/gog-docs-insert-date-chip.md
+++ b/docs/commands/gog-docs-insert-date-chip.md
@@ -38,6 +38,7 @@ gog docs (doc) insert-date-chip --date=STRING <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-insert-file-chip.md b/docs/commands/gog-docs-insert-file-chip.md
index d937db56f..eba397bc0 100644
--- a/docs/commands/gog-docs-insert-file-chip.md
+++ b/docs/commands/gog-docs-insert-file-chip.md
@@ -37,6 +37,7 @@ gog docs (doc) insert-file-chip (insert-rich-link) --file-id=STRING <docId> [fla
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-insert-footnote.md b/docs/commands/gog-docs-insert-footnote.md
index 55a8ab4cd..e450c226d 100644
--- a/docs/commands/gog-docs-insert-footnote.md
+++ b/docs/commands/gog-docs-insert-footnote.md
@@ -39,6 +39,7 @@ gog docs (doc) insert-footnote <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-insert-horizontal-rule.md b/docs/commands/gog-docs-insert-horizontal-rule.md
index 6ba488078..e457f2ed4 100644
--- a/docs/commands/gog-docs-insert-horizontal-rule.md
+++ b/docs/commands/gog-docs-insert-horizontal-rule.md
@@ -39,6 +39,7 @@ gog docs (doc) insert-horizontal-rule (insert-hr,hr) <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-insert-image.md b/docs/commands/gog-docs-insert-image.md
index b7f9a02f7..4f86859d5 100644
--- a/docs/commands/gog-docs-insert-image.md
+++ b/docs/commands/gog-docs-insert-image.md
@@ -41,6 +41,7 @@ gog docs (doc) insert-image <docId> [flags]
 | `--on-restricted` | `string` | error | If public sharing is blocked: error\|link |
 | `--parent` | `string` |  | Drive folder ID for the uploaded image |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-insert-page-break.md b/docs/commands/gog-docs-insert-page-break.md
index 8feddae28..e96362c39 100644
--- a/docs/commands/gog-docs-insert-page-break.md
+++ b/docs/commands/gog-docs-insert-page-break.md
@@ -39,6 +39,7 @@ gog docs (doc) insert-page-break (page-break,pb) <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-insert-person.md b/docs/commands/gog-docs-insert-person.md
index 27585cb41..14a6574e9 100644
--- a/docs/commands/gog-docs-insert-person.md
+++ b/docs/commands/gog-docs-insert-person.md
@@ -40,6 +40,7 @@ gog docs (doc) insert-person --email=STRING <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-insert-section-break.md b/docs/commands/gog-docs-insert-section-break.md
index 55696ab55..b32b485cd 100644
--- a/docs/commands/gog-docs-insert-section-break.md
+++ b/docs/commands/gog-docs-insert-section-break.md
@@ -39,6 +39,7 @@ gog docs (doc) insert-section-break <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-insert-table.md b/docs/commands/gog-docs-insert-table.md
index 39435b342..ad9068c77 100644
--- a/docs/commands/gog-docs-insert-table.md
+++ b/docs/commands/gog-docs-insert-table.md
@@ -36,6 +36,7 @@ gog docs (doc) insert-table --rows=INT --cols=INT <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--rows` | `int` |  | Number of rows (>=1) |
 | `--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. |
diff --git a/docs/commands/gog-docs-insert.md b/docs/commands/gog-docs-insert.md
index c5c84fc87..a46244112 100644
--- a/docs/commands/gog-docs-insert.md
+++ b/docs/commands/gog-docs-insert.md
@@ -40,6 +40,7 @@ gog docs (doc) insert <docId> [<content>] [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--segment` | `string` |  | Target an exact header, footer, or footnote segment ID |
 | `--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. |
diff --git a/docs/commands/gog-docs-list-tabs.md b/docs/commands/gog-docs-list-tabs.md
index 1d3111ba3..febea22cc 100644
--- a/docs/commands/gog-docs-list-tabs.md
+++ b/docs/commands/gog-docs-list-tabs.md
@@ -33,6 +33,7 @@ gog docs (doc) list-tabs <docId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-named-range-create.md b/docs/commands/gog-docs-named-range-create.md
index 7d0599b86..6b80aea64 100644
--- a/docs/commands/gog-docs-named-range-create.md
+++ b/docs/commands/gog-docs-named-range-create.md
@@ -38,6 +38,7 @@ gog docs (doc) named-range (named-ranges,namedranges,nr) create (add,new) <docId
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--start` | `*int64` |  | Range start UTF-16 index (inclusive) |
diff --git a/docs/commands/gog-docs-named-range-delete.md b/docs/commands/gog-docs-named-range-delete.md
index 7d38bc122..5295c2a48 100644
--- a/docs/commands/gog-docs-named-range-delete.md
+++ b/docs/commands/gog-docs-named-range-delete.md
@@ -33,6 +33,7 @@ gog docs (doc) named-range (named-ranges,namedranges,nr) delete (rm,remove,del)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-named-range-list.md b/docs/commands/gog-docs-named-range-list.md
index 07d3f109d..2ea51d2cb 100644
--- a/docs/commands/gog-docs-named-range-list.md
+++ b/docs/commands/gog-docs-named-range-list.md
@@ -34,6 +34,7 @@ gog docs (doc) named-range (named-ranges,namedranges,nr) list <docId> [flags]
 | `--name` | `string` |  | Filter by exact named range name |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-named-range-replace.md b/docs/commands/gog-docs-named-range-replace.md
index ba4e3eebc..c8194f18b 100644
--- a/docs/commands/gog-docs-named-range-replace.md
+++ b/docs/commands/gog-docs-named-range-replace.md
@@ -34,6 +34,7 @@ gog docs (doc) named-range (named-ranges,namedranges,nr) replace (set,update) <d
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-named-range.md b/docs/commands/gog-docs-named-range.md
index da6c85fa5..3b107cf86 100644
--- a/docs/commands/gog-docs-named-range.md
+++ b/docs/commands/gog-docs-named-range.md
@@ -40,6 +40,7 @@ gog docs (doc) named-range (named-ranges,namedranges,nr) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-page-layout.md b/docs/commands/gog-docs-page-layout.md
index fad2e2668..2f661866e 100644
--- a/docs/commands/gog-docs-page-layout.md
+++ b/docs/commands/gog-docs-page-layout.md
@@ -41,6 +41,7 @@ gog docs (doc) page-layout (set-page-layout,page-setup) <docId> [flags]
 | `--page-size` | `string` |  | Named page size: A4, A5, Letter, Legal, Tabloid |
 | `--page-width` | `string` |  | Set page width (points by default; supports pt, in, cm, mm) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-paragraphs-list.md b/docs/commands/gog-docs-paragraphs-list.md
index 4d0b3e233..a8cf11891 100644
--- a/docs/commands/gog-docs-paragraphs-list.md
+++ b/docs/commands/gog-docs-paragraphs-list.md
@@ -33,6 +33,7 @@ gog docs (doc) paragraphs list (ls) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--style` | `string` |  | Only return this named style (for example NORMAL_TEXT or HEADING_2) |
diff --git a/docs/commands/gog-docs-paragraphs.md b/docs/commands/gog-docs-paragraphs.md
index 9be35e5ae..8438da178 100644
--- a/docs/commands/gog-docs-paragraphs.md
+++ b/docs/commands/gog-docs-paragraphs.md
@@ -37,6 +37,7 @@ gog docs (doc) paragraphs <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-raw.md b/docs/commands/gog-docs-raw.md
index 22e0118cf..25812c896 100644
--- a/docs/commands/gog-docs-raw.md
+++ b/docs/commands/gog-docs-raw.md
@@ -35,6 +35,7 @@ gog docs (doc) raw <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
+| `--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. |
 | `--tab` | `string` |  | Return one tab by title or ID in the legacy top-level Document shape |
diff --git a/docs/commands/gog-docs-rename-tab.md b/docs/commands/gog-docs-rename-tab.md
index e73fb9ca5..144a95a83 100644
--- a/docs/commands/gog-docs-rename-tab.md
+++ b/docs/commands/gog-docs-rename-tab.md
@@ -33,6 +33,7 @@ gog docs (doc) rename-tab <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Existing tab title or ID |
diff --git a/docs/commands/gog-docs-replace-image.md b/docs/commands/gog-docs-replace-image.md
index 30d93ebed..83ed09b3c 100644
--- a/docs/commands/gog-docs-replace-image.md
+++ b/docs/commands/gog-docs-replace-image.md
@@ -38,6 +38,7 @@ gog docs (doc) replace-image <docId> [flags]
 | `--object-id` | `string` |  | Exact image object ID from docs images list |
 | `--parent` | `string` |  | Drive folder ID for an uploaded local image |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-section-columns.md b/docs/commands/gog-docs-section-columns.md
index e5611e963..9cb68be5d 100644
--- a/docs/commands/gog-docs-section-columns.md
+++ b/docs/commands/gog-docs-section-columns.md
@@ -40,6 +40,7 @@ gog docs (doc) section-columns --count=INT <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--separator` | `string` | none | Column separator: none or between |
diff --git a/docs/commands/gog-docs-sed.md b/docs/commands/gog-docs-sed.md
index 9601c1821..2bbd3f4f9 100644
--- a/docs/commands/gog-docs-sed.md
+++ b/docs/commands/gog-docs-sed.md
@@ -35,6 +35,7 @@ gog docs (doc) sed <docId> [<expression>] [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Tab title or ID for paragraph addressing |
diff --git a/docs/commands/gog-docs-structure.md b/docs/commands/gog-docs-structure.md
index e3973c9b1..2a6633226 100644
--- a/docs/commands/gog-docs-structure.md
+++ b/docs/commands/gog-docs-structure.md
@@ -33,6 +33,7 @@ gog docs (doc) structure (struct) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Tab title or ID (omit for default) |
diff --git a/docs/commands/gog-docs-table-column-delete.md b/docs/commands/gog-docs-table-column-delete.md
index 4c623ebd1..a505fc505 100644
--- a/docs/commands/gog-docs-table-column-delete.md
+++ b/docs/commands/gog-docs-table-column-delete.md
@@ -34,6 +34,7 @@ gog docs (doc) table-column delete (rm,remove,del) --col=INT <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-table-column-insert.md b/docs/commands/gog-docs-table-column-insert.md
index 503990146..be602e896 100644
--- a/docs/commands/gog-docs-table-column-insert.md
+++ b/docs/commands/gog-docs-table-column-insert.md
@@ -34,6 +34,7 @@ gog docs (doc) table-column insert (add,append) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-table-column-width.md b/docs/commands/gog-docs-table-column-width.md
index 7073b5a3a..3428b9e85 100644
--- a/docs/commands/gog-docs-table-column-width.md
+++ b/docs/commands/gog-docs-table-column-width.md
@@ -36,6 +36,7 @@ gog docs (doc) table-column-width (table-width,column-width) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-table-column.md b/docs/commands/gog-docs-table-column.md
index de0f1124a..327ab3996 100644
--- a/docs/commands/gog-docs-table-column.md
+++ b/docs/commands/gog-docs-table-column.md
@@ -38,6 +38,7 @@ gog docs (doc) table-column <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-table-merge.md b/docs/commands/gog-docs-table-merge.md
index 7e299f7b0..ed41840ef 100644
--- a/docs/commands/gog-docs-table-merge.md
+++ b/docs/commands/gog-docs-table-merge.md
@@ -34,6 +34,7 @@ gog docs (doc) table-merge --range=STRING <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--range` | `string` |  | 1-based cell range r1,c1:r2,c2 |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-table-row-delete.md b/docs/commands/gog-docs-table-row-delete.md
index 0cd5c6051..71bf581fb 100644
--- a/docs/commands/gog-docs-table-row-delete.md
+++ b/docs/commands/gog-docs-table-row-delete.md
@@ -33,6 +33,7 @@ gog docs (doc) table-row delete (rm,remove,del) --row=INT <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--row` | `int` |  | 1-based row number; negative indexes count from the end |
 | `--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. |
diff --git a/docs/commands/gog-docs-table-row-insert.md b/docs/commands/gog-docs-table-row-insert.md
index 2f8fa53f7..0eaa6e15c 100644
--- a/docs/commands/gog-docs-table-row-insert.md
+++ b/docs/commands/gog-docs-table-row-insert.md
@@ -34,6 +34,7 @@ gog docs (doc) table-row insert (add,append) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-table-row-pin-header.md b/docs/commands/gog-docs-table-row-pin-header.md
index 5d8f34f3c..d9e658b31 100644
--- a/docs/commands/gog-docs-table-row-pin-header.md
+++ b/docs/commands/gog-docs-table-row-pin-header.md
@@ -33,6 +33,7 @@ gog docs (doc) table-row pin-header --rows=INT-64 <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--rows` | `int64` |  | Number of leading rows to pin; 0 unpins all header rows |
 | `--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. |
diff --git a/docs/commands/gog-docs-table-row-style.md b/docs/commands/gog-docs-table-row-style.md
index 66ff72547..0f9288fdc 100644
--- a/docs/commands/gog-docs-table-row-style.md
+++ b/docs/commands/gog-docs-table-row-style.md
@@ -35,6 +35,7 @@ gog docs (doc) table-row style <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--prevent-overflow` | `*bool` |  | Keep the row within one page or column; use --no-prevent-overflow to clear |
+| `--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) |
 | `--row` | `*int` |  | 1-based row number; negative indexes count from the end; omit to style all rows |
 | `--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. |
diff --git a/docs/commands/gog-docs-table-row.md b/docs/commands/gog-docs-table-row.md
index a776d201f..9b2823f2b 100644
--- a/docs/commands/gog-docs-table-row.md
+++ b/docs/commands/gog-docs-table-row.md
@@ -40,6 +40,7 @@ gog docs (doc) table-row <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-table-unmerge.md b/docs/commands/gog-docs-table-unmerge.md
index 291fc9113..0cc2f5215 100644
--- a/docs/commands/gog-docs-table-unmerge.md
+++ b/docs/commands/gog-docs-table-unmerge.md
@@ -34,6 +34,7 @@ gog docs (doc) table-unmerge (table-split) --cell=STRING <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
diff --git a/docs/commands/gog-docs-tables-list.md b/docs/commands/gog-docs-tables-list.md
index e69730108..c0929f05b 100644
--- a/docs/commands/gog-docs-tables-list.md
+++ b/docs/commands/gog-docs-tables-list.md
@@ -33,6 +33,7 @@ gog docs (doc) tables list (ls) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Tab title or ID (omit for default) |
diff --git a/docs/commands/gog-docs-tables.md b/docs/commands/gog-docs-tables.md
index e4ab6dd8a..4300f0cb6 100644
--- a/docs/commands/gog-docs-tables.md
+++ b/docs/commands/gog-docs-tables.md
@@ -37,6 +37,7 @@ gog docs (doc) tables <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-tabs-add.md b/docs/commands/gog-docs-tabs-add.md
index 446715fc0..b44d6b4e6 100644
--- a/docs/commands/gog-docs-tabs-add.md
+++ b/docs/commands/gog-docs-tabs-add.md
@@ -36,6 +36,7 @@ gog docs (doc) tabs add (create,new) <docId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent-tab` | `string` |  | Optional parent tab title or ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--title` | `string` |  | User-visible tab title |
diff --git a/docs/commands/gog-docs-tabs-delete.md b/docs/commands/gog-docs-tabs-delete.md
index af179c737..3033938e2 100644
--- a/docs/commands/gog-docs-tabs-delete.md
+++ b/docs/commands/gog-docs-tabs-delete.md
@@ -33,6 +33,7 @@ gog docs (doc) tabs delete (rm,remove,del) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Existing tab title or ID |
diff --git a/docs/commands/gog-docs-tabs-list.md b/docs/commands/gog-docs-tabs-list.md
index 7bd87f5e3..fca2c31b3 100644
--- a/docs/commands/gog-docs-tabs-list.md
+++ b/docs/commands/gog-docs-tabs-list.md
@@ -33,6 +33,7 @@ gog docs (doc) tabs list (ls) <docId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-tabs-rename.md b/docs/commands/gog-docs-tabs-rename.md
index 6a6a5510b..78b40534b 100644
--- a/docs/commands/gog-docs-tabs-rename.md
+++ b/docs/commands/gog-docs-tabs-rename.md
@@ -33,6 +33,7 @@ gog docs (doc) tabs rename (move) <docId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Existing tab title or ID |
diff --git a/docs/commands/gog-docs-tabs.md b/docs/commands/gog-docs-tabs.md
index 5047f4540..460e2c664 100644
--- a/docs/commands/gog-docs-tabs.md
+++ b/docs/commands/gog-docs-tabs.md
@@ -40,6 +40,7 @@ gog docs (doc) tabs <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-docs-update.md b/docs/commands/gog-docs-update.md
index 528bd873a..34003cfa6 100644
--- a/docs/commands/gog-docs-update.md
+++ b/docs/commands/gog-docs-update.md
@@ -41,6 +41,7 @@ gog docs (doc) update <docId> [flags]
 | `--occurrence` | `*int` |  | Use the Nth --at match (1-based; required when --at is ambiguous) |
 | `--pageless` | `bool` |  | Set document to pageless mode |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--replace-range` | `string` |  | Replace UTF-16 Docs API range START:END instead of inserting |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
 | `--segment` | `string` |  | Target an exact header, footer, or footnote segment ID |
diff --git a/docs/commands/gog-docs-write.md b/docs/commands/gog-docs-write.md
index 3bc9239b0..8dd542a96 100644
--- a/docs/commands/gog-docs-write.md
+++ b/docs/commands/gog-docs-write.md
@@ -69,6 +69,7 @@ gog docs (doc) write <docId> [flags]
 | `--page-width` | `string` |  | Set page width (points by default; supports pt, in, cm, mm) |
 | `--pageless` | `bool` |  | Set document to pageless mode |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--replace` | `bool` |  | Replace all content explicitly (required with --markdown unless --append is set) |
 | `--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. |
diff --git a/docs/commands/gog-docs.md b/docs/commands/gog-docs.md
index 43c274f19..72f4889ec 100644
--- a/docs/commands/gog-docs.md
+++ b/docs/commands/gog-docs.md
@@ -85,6 +85,7 @@ gog docs (doc) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-download.md b/docs/commands/gog-download.md
index e601e2b6f..650423341 100644
--- a/docs/commands/gog-download.md
+++ b/docs/commands/gog-download.md
@@ -36,6 +36,7 @@ gog download (dl) <fileId> [flags]
 | `--out`<br>`--output` | `string` |  | Output file path (default: gogcli config dir) |
 | `--overwrite` | `bool` |  | Overwrite an existing output file |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | (experimental) Export a specific tab by title or ID (Google Docs only; see 'gog docs list-tabs') |
diff --git a/docs/commands/gog-drive-activity-query.md b/docs/commands/gog-drive-activity-query.md
index 8e54bb12d..2e03ffff3 100644
--- a/docs/commands/gog-drive-activity-query.md
+++ b/docs/commands/gog-drive-activity-query.md
@@ -43,6 +43,7 @@ gog drive (drv) activity query (list,ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--to` | `string` |  | Upper activity time bound (RFC3339) |
diff --git a/docs/commands/gog-drive-activity.md b/docs/commands/gog-drive-activity.md
index edc160d7d..fb94cb17d 100644
--- a/docs/commands/gog-drive-activity.md
+++ b/docs/commands/gog-drive-activity.md
@@ -37,6 +37,7 @@ gog drive (drv) activity <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-audit-sharing.md b/docs/commands/gog-drive-audit-sharing.md
index 21e65b27a..09b93a63a 100644
--- a/docs/commands/gog-drive-audit-sharing.md
+++ b/docs/commands/gog-drive-audit-sharing.md
@@ -42,6 +42,7 @@ gog drive (drv) audit sharing (permissions,perms,public,external) [flags]
 | `--parent` | `string` |  | Folder ID to scan (default: root) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--public-only` | `bool` |  | Only report anyone-with-link/public permissions |
+| `--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 |
diff --git a/docs/commands/gog-drive-audit-user.md b/docs/commands/gog-drive-audit-user.md
index 4a7b659a7..9acb3d89e 100644
--- a/docs/commands/gog-drive-audit-user.md
+++ b/docs/commands/gog-drive-audit-user.md
@@ -39,6 +39,7 @@ gog drive (drv) audit user <user> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Folder ID to scan (default: root) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-audit.md b/docs/commands/gog-drive-audit.md
index 711016a6a..bfd7925c6 100644
--- a/docs/commands/gog-drive-audit.md
+++ b/docs/commands/gog-drive-audit.md
@@ -38,6 +38,7 @@ gog drive (drv) audit <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-bulk-remove-public.md b/docs/commands/gog-drive-bulk-remove-public.md
index 875b726a9..e677b7925 100644
--- a/docs/commands/gog-drive-bulk-remove-public.md
+++ b/docs/commands/gog-drive-bulk-remove-public.md
@@ -38,6 +38,7 @@ gog drive (drv) bulk remove-public [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Folder ID to scan (default: root) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-bulk-update-role.md b/docs/commands/gog-drive-bulk-update-role.md
index e8b509518..62425dc04 100644
--- a/docs/commands/gog-drive-bulk-update-role.md
+++ b/docs/commands/gog-drive-bulk-update-role.md
@@ -39,6 +39,7 @@ gog drive (drv) bulk update-role [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Folder ID to scan (default: root) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--target` | `string` |  | Optional target email/domain filter |
diff --git a/docs/commands/gog-drive-bulk.md b/docs/commands/gog-drive-bulk.md
index 081cab2e2..82249323c 100644
--- a/docs/commands/gog-drive-bulk.md
+++ b/docs/commands/gog-drive-bulk.md
@@ -38,6 +38,7 @@ gog drive (drv) bulk <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-changes-list.md b/docs/commands/gog-drive-changes-list.md
index 7d78cd63a..9155d4d39 100644
--- a/docs/commands/gog-drive-changes-list.md
+++ b/docs/commands/gog-drive-changes-list.md
@@ -39,6 +39,7 @@ gog drive (drv) changes list (ls) --token=STRING [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Alias for --token when continuing a page |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--token` | `string` |  | Start page token or next page token |
diff --git a/docs/commands/gog-drive-changes-poll.md b/docs/commands/gog-drive-changes-poll.md
index 11693dd95..06b5be258 100644
--- a/docs/commands/gog-drive-changes-poll.md
+++ b/docs/commands/gog-drive-changes-poll.md
@@ -40,6 +40,7 @@ gog drive (drv) changes poll --state-file=STRING [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--on-change` | `string` |  | Trusted local shell command run for each non-empty batch; batch JSON is provided on stdin |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--state-file` | `string` |  | JSON file that stores the current Drive page token |
diff --git a/docs/commands/gog-drive-changes-serve.md b/docs/commands/gog-drive-changes-serve.md
index b43d8f3d2..acab3ac8d 100644
--- a/docs/commands/gog-drive-changes-serve.md
+++ b/docs/commands/gog-drive-changes-serve.md
@@ -47,6 +47,7 @@ gog drive (drv) changes serve --state-file=STRING [flags]
 | `--on-change` | `string` |  | Trusted local shell command run for each non-empty change batch; event JSON is provided on stdin |
 | `--path` | `string` | /drive-changes | Notification handler path |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--renew-before` | `time.Duration` | 10m | Renew this long before channel expiration |
 | `--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. |
diff --git a/docs/commands/gog-drive-changes-start-token.md b/docs/commands/gog-drive-changes-start-token.md
index 4dfb7156f..346c67600 100644
--- a/docs/commands/gog-drive-changes-start-token.md
+++ b/docs/commands/gog-drive-changes-start-token.md
@@ -34,6 +34,7 @@ gog drive (drv) changes start-token (token) [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-changes-stop.md b/docs/commands/gog-drive-changes-stop.md
index 17129d8de..c677cb80d 100644
--- a/docs/commands/gog-drive-changes-stop.md
+++ b/docs/commands/gog-drive-changes-stop.md
@@ -33,6 +33,7 @@ gog drive (drv) changes stop <channelId> <resourceId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-changes-watch.md b/docs/commands/gog-drive-changes-watch.md
index 95e8849cd..c4606385b 100644
--- a/docs/commands/gog-drive-changes-watch.md
+++ b/docs/commands/gog-drive-changes-watch.md
@@ -37,6 +37,7 @@ gog drive (drv) changes watch --token=STRING --webhook-url=STRING [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--token` | `string` |  | Start page token or next page token to watch from |
diff --git a/docs/commands/gog-drive-changes.md b/docs/commands/gog-drive-changes.md
index a52fa4cdc..f1d44f0f7 100644
--- a/docs/commands/gog-drive-changes.md
+++ b/docs/commands/gog-drive-changes.md
@@ -42,6 +42,7 @@ gog drive (drv) changes <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-comments-create.md b/docs/commands/gog-drive-comments-create.md
index 73d378a50..b044930df 100644
--- a/docs/commands/gog-drive-comments-create.md
+++ b/docs/commands/gog-drive-comments-create.md
@@ -34,6 +34,7 @@ gog drive (drv) comments create (add,new) <fileId> <content> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--quoted` | `string` |  | Text to anchor the comment to (for Google Docs) |
+| `--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 |
diff --git a/docs/commands/gog-drive-comments-delete.md b/docs/commands/gog-drive-comments-delete.md
index 7111a87b1..d5ac786d5 100644
--- a/docs/commands/gog-drive-comments-delete.md
+++ b/docs/commands/gog-drive-comments-delete.md
@@ -33,6 +33,7 @@ gog drive (drv) comments delete (rm,del,remove) <fileId> <commentId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-comments-get.md b/docs/commands/gog-drive-comments-get.md
index 4c74310af..5e922247f 100644
--- a/docs/commands/gog-drive-comments-get.md
+++ b/docs/commands/gog-drive-comments-get.md
@@ -33,6 +33,7 @@ gog drive (drv) comments get (info,show) <fileId> <commentId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-comments-list.md b/docs/commands/gog-drive-comments-list.md
index d5988745e..00eca485a 100644
--- a/docs/commands/gog-drive-comments-list.md
+++ b/docs/commands/gog-drive-comments-list.md
@@ -38,6 +38,7 @@ gog drive (drv) comments list (ls) <fileId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--since` | `string` |  | Only return comments modified at or after this RFC3339 timestamp |
diff --git a/docs/commands/gog-drive-comments-reopen.md b/docs/commands/gog-drive-comments-reopen.md
index a9db4d973..85ff6ef91 100644
--- a/docs/commands/gog-drive-comments-reopen.md
+++ b/docs/commands/gog-drive-comments-reopen.md
@@ -34,6 +34,7 @@ gog drive (drv) comments reopen <fileId> <commentId> [flags]
 | `-m`<br>`--message` | `string` |  | Optional message to include when reopening |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-comments-reply.md b/docs/commands/gog-drive-comments-reply.md
index 32028d378..45237ce29 100644
--- a/docs/commands/gog-drive-comments-reply.md
+++ b/docs/commands/gog-drive-comments-reply.md
@@ -34,6 +34,7 @@ gog drive (drv) comments reply (respond) <fileId> <commentId> <content> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-comments-resolve.md b/docs/commands/gog-drive-comments-resolve.md
index e01706f9a..2b7b78000 100644
--- a/docs/commands/gog-drive-comments-resolve.md
+++ b/docs/commands/gog-drive-comments-resolve.md
@@ -34,6 +34,7 @@ gog drive (drv) comments resolve <fileId> <commentId> [flags]
 | `-m`<br>`--message` | `string` |  | Optional message to include when resolving |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-comments-update.md b/docs/commands/gog-drive-comments-update.md
index 03bcdf9c5..08e20fece 100644
--- a/docs/commands/gog-drive-comments-update.md
+++ b/docs/commands/gog-drive-comments-update.md
@@ -33,6 +33,7 @@ gog drive (drv) comments update (edit,set) <fileId> <commentId> <content>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-comments.md b/docs/commands/gog-drive-comments.md
index 5ad9cf645..df7db66bf 100644
--- a/docs/commands/gog-drive-comments.md
+++ b/docs/commands/gog-drive-comments.md
@@ -44,6 +44,7 @@ gog drive (drv) comments <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-copy.md b/docs/commands/gog-drive-copy.md
index 90494345b..7a305abda 100644
--- a/docs/commands/gog-drive-copy.md
+++ b/docs/commands/gog-drive-copy.md
@@ -34,6 +34,7 @@ gog drive (drv) copy <fileId> <name> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Destination folder ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-delete.md b/docs/commands/gog-drive-delete.md
index cbda19907..32bbc171e 100644
--- a/docs/commands/gog-drive-delete.md
+++ b/docs/commands/gog-drive-delete.md
@@ -34,6 +34,7 @@ gog drive (drv) delete (rm,del) <fileId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--permanent` | `bool` | false | Permanently delete instead of moving to trash |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-download.md b/docs/commands/gog-drive-download.md
index aed8a9551..0536c9d09 100644
--- a/docs/commands/gog-drive-download.md
+++ b/docs/commands/gog-drive-download.md
@@ -36,6 +36,7 @@ gog drive (drv) download <fileId> [flags]
 | `--out`<br>`--output` | `string` |  | Output file path (default: gogcli config dir) |
 | `--overwrite` | `bool` |  | Overwrite an existing output file |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | (experimental) Export a specific tab by title or ID (Google Docs only; see 'gog docs list-tabs') |
diff --git a/docs/commands/gog-drive-drives.md b/docs/commands/gog-drive-drives.md
index 4a4f57b29..e6f90c396 100644
--- a/docs/commands/gog-drive-drives.md
+++ b/docs/commands/gog-drive-drives.md
@@ -38,6 +38,7 @@ gog drive (drv) drives [flags]
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `-q`<br>`--query` | `string` |  | Search query for filtering shared drives |
+| `--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 |
diff --git a/docs/commands/gog-drive-du.md b/docs/commands/gog-drive-du.md
index a18e1d737..251ec1131 100644
--- a/docs/commands/gog-drive-du.md
+++ b/docs/commands/gog-drive-du.md
@@ -38,6 +38,7 @@ gog drive (drv) du [flags]
 | `--order` | `string` | desc | Sort order |
 | `--parent` | `string` |  | Folder ID to start from (default: root) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--sort` | `string` | size | Sort by size\|path\|files |
diff --git a/docs/commands/gog-drive-get.md b/docs/commands/gog-drive-get.md
index 64423f1e5..5d36edf53 100644
--- a/docs/commands/gog-drive-get.md
+++ b/docs/commands/gog-drive-get.md
@@ -34,6 +34,7 @@ gog drive (drv) get <fileId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-inventory.md b/docs/commands/gog-drive-inventory.md
index 395825dba..32e013804 100644
--- a/docs/commands/gog-drive-inventory.md
+++ b/docs/commands/gog-drive-inventory.md
@@ -38,6 +38,7 @@ gog drive (drv) inventory [flags]
 | `--order` | `string` | asc | Sort order |
 | `--parent` | `string` |  | Folder ID to start from (default: root) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--sort` | `string` | path | Sort by path\|size\|modified |
diff --git a/docs/commands/gog-drive-labels-file-apply.md b/docs/commands/gog-drive-labels-file-apply.md
index 1b019dcaa..e2966a1b4 100644
--- a/docs/commands/gog-drive-labels-file-apply.md
+++ b/docs/commands/gog-drive-labels-file-apply.md
@@ -36,6 +36,7 @@ gog drive (drv) labels (label) file apply <fileId> <labelId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--selection` | `[]string` |  | Set selection field as field=choiceId[,choiceId] (repeatable) |
diff --git a/docs/commands/gog-drive-labels-file-list.md b/docs/commands/gog-drive-labels-file-list.md
index 509fba1bf..1e8bb01e9 100644
--- a/docs/commands/gog-drive-labels-file-list.md
+++ b/docs/commands/gog-drive-labels-file-list.md
@@ -36,6 +36,7 @@ gog drive (drv) labels (label) file list (ls) <fileId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-labels-file-remove.md b/docs/commands/gog-drive-labels-file-remove.md
index 12ec454e0..630a66c89 100644
--- a/docs/commands/gog-drive-labels-file-remove.md
+++ b/docs/commands/gog-drive-labels-file-remove.md
@@ -33,6 +33,7 @@ gog drive (drv) labels (label) file remove (rm) <fileId> <labelId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-labels-file.md b/docs/commands/gog-drive-labels-file.md
index c29c96533..3c0dcb21c 100644
--- a/docs/commands/gog-drive-labels-file.md
+++ b/docs/commands/gog-drive-labels-file.md
@@ -39,6 +39,7 @@ gog drive (drv) labels (label) file <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-labels-get.md b/docs/commands/gog-drive-labels-get.md
index 034de8921..f28b642a0 100644
--- a/docs/commands/gog-drive-labels-get.md
+++ b/docs/commands/gog-drive-labels-get.md
@@ -36,6 +36,7 @@ gog drive (drv) labels (label) get (info,show) <name> [flags]
 | `--language` | `string` |  | BCP-47 language code |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-labels-list.md b/docs/commands/gog-drive-labels-list.md
index 7920f61e9..390c38c75 100644
--- a/docs/commands/gog-drive-labels-list.md
+++ b/docs/commands/gog-drive-labels-list.md
@@ -41,6 +41,7 @@ gog drive (drv) labels (label) list (ls) [flags]
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--published-only` | `bool` | true | Only list published labels |
+| `--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 |
diff --git a/docs/commands/gog-drive-labels.md b/docs/commands/gog-drive-labels.md
index 3ba3d29b3..08d1807f8 100644
--- a/docs/commands/gog-drive-labels.md
+++ b/docs/commands/gog-drive-labels.md
@@ -39,6 +39,7 @@ gog drive (drv) labels (label) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-ls.md b/docs/commands/gog-drive-ls.md
index a3b2ca3bf..54500bb46 100644
--- a/docs/commands/gog-drive-ls.md
+++ b/docs/commands/gog-drive-ls.md
@@ -40,6 +40,7 @@ gog drive (drv) ls [flags]
 | `--parent` | `string` |  | Folder ID to list (default: root) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--query` | `string` |  | Drive query filter |
+| `--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 |
diff --git a/docs/commands/gog-drive-mkdir.md b/docs/commands/gog-drive-mkdir.md
index 8bb1d81f0..a0d0ba80b 100644
--- a/docs/commands/gog-drive-mkdir.md
+++ b/docs/commands/gog-drive-mkdir.md
@@ -34,6 +34,7 @@ gog drive (drv) mkdir <name> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Parent folder ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-move.md b/docs/commands/gog-drive-move.md
index bd4afe787..31a314e3f 100644
--- a/docs/commands/gog-drive-move.md
+++ b/docs/commands/gog-drive-move.md
@@ -34,6 +34,7 @@ gog drive (drv) move <fileId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | New parent folder ID (required) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-permissions.md b/docs/commands/gog-drive-permissions.md
index 2d6d6d318..155a81fb0 100644
--- a/docs/commands/gog-drive-permissions.md
+++ b/docs/commands/gog-drive-permissions.md
@@ -35,6 +35,7 @@ gog drive (drv) permissions <fileId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-raw.md b/docs/commands/gog-drive-raw.md
index 6e28c387f..cc8ef087f 100644
--- a/docs/commands/gog-drive-raw.md
+++ b/docs/commands/gog-drive-raw.md
@@ -35,6 +35,7 @@ gog drive (drv) raw <fileId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
+| `--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 |
diff --git a/docs/commands/gog-drive-rename.md b/docs/commands/gog-drive-rename.md
index c505b6f38..d5b73bd98 100644
--- a/docs/commands/gog-drive-rename.md
+++ b/docs/commands/gog-drive-rename.md
@@ -33,6 +33,7 @@ gog drive (drv) rename <fileId> <newName>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-revisions-get.md b/docs/commands/gog-drive-revisions-get.md
index 8d3a03adf..3b64e3044 100644
--- a/docs/commands/gog-drive-revisions-get.md
+++ b/docs/commands/gog-drive-revisions-get.md
@@ -33,6 +33,7 @@ gog drive (drv) revisions (revision) get <fileId> <revisionId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-revisions-list.md b/docs/commands/gog-drive-revisions-list.md
index b02658b9c..4704b7547 100644
--- a/docs/commands/gog-drive-revisions-list.md
+++ b/docs/commands/gog-drive-revisions-list.md
@@ -37,6 +37,7 @@ gog drive (drv) revisions (revision) list (ls) <fileId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-revisions.md b/docs/commands/gog-drive-revisions.md
index 7464f4750..7e2f9b841 100644
--- a/docs/commands/gog-drive-revisions.md
+++ b/docs/commands/gog-drive-revisions.md
@@ -38,6 +38,7 @@ gog drive (drv) revisions (revision) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-search.md b/docs/commands/gog-drive-search.md
index af99638b9..1dc726dfc 100644
--- a/docs/commands/gog-drive-search.md
+++ b/docs/commands/gog-drive-search.md
@@ -39,6 +39,7 @@ gog drive (drv) search <query> ... [flags]
 | `--parent` | `string` |  | Scope search to direct children of a specific folder or shared drive. Wraps the query with "'<parentId>' in parents". |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--raw-query`<br>`--raw` | `bool` |  | Treat query as Drive query language (pass through; may error if invalid) |
+| `--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 |
diff --git a/docs/commands/gog-drive-share.md b/docs/commands/gog-drive-share.md
index ebf92083b..6115794cc 100644
--- a/docs/commands/gog-drive-share.md
+++ b/docs/commands/gog-drive-share.md
@@ -37,6 +37,7 @@ gog drive (drv) share <fileId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--notify` | `bool` |  | Send Drive invitation email for user/domain shares |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--role` | `string` | reader | Permission: reader\|writer\|commenter |
 | `--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. |
diff --git a/docs/commands/gog-drive-shortcut-create.md b/docs/commands/gog-drive-shortcut-create.md
index c38c94ce9..a90eee10f 100644
--- a/docs/commands/gog-drive-shortcut-create.md
+++ b/docs/commands/gog-drive-shortcut-create.md
@@ -35,6 +35,7 @@ gog drive (drv) shortcut (shortcuts) create (add,new) <targetId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Destination folder ID (required) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-shortcut.md b/docs/commands/gog-drive-shortcut.md
index cc5ac6992..0e8525dc0 100644
--- a/docs/commands/gog-drive-shortcut.md
+++ b/docs/commands/gog-drive-shortcut.md
@@ -37,6 +37,7 @@ gog drive (drv) shortcut (shortcuts) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-tree.md b/docs/commands/gog-drive-tree.md
index 7daa79b33..d4b7c3db8 100644
--- a/docs/commands/gog-drive-tree.md
+++ b/docs/commands/gog-drive-tree.md
@@ -37,6 +37,7 @@ gog drive (drv) tree [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Folder ID to start from (default: root) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-unshare.md b/docs/commands/gog-drive-unshare.md
index 503a46676..138f200bb 100644
--- a/docs/commands/gog-drive-unshare.md
+++ b/docs/commands/gog-drive-unshare.md
@@ -33,6 +33,7 @@ gog drive (drv) unshare <fileId> <permissionId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive-upload.md b/docs/commands/gog-drive-upload.md
index 56077b536..a23322926 100644
--- a/docs/commands/gog-drive-upload.md
+++ b/docs/commands/gog-drive-upload.md
@@ -40,6 +40,7 @@ gog drive (drv) upload <localPath> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Destination folder ID (create only) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--replace` | `string` |  | Replace the content of an existing Drive file ID (preserves shared link/permissions) |
 | `--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. |
diff --git a/docs/commands/gog-drive-url.md b/docs/commands/gog-drive-url.md
index 9796eb115..3bdf3c8e6 100644
--- a/docs/commands/gog-drive-url.md
+++ b/docs/commands/gog-drive-url.md
@@ -33,6 +33,7 @@ gog drive (drv) url <fileId> ...
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-drive.md b/docs/commands/gog-drive.md
index 3f2656933..bb67a89a5 100644
--- a/docs/commands/gog-drive.md
+++ b/docs/commands/gog-drive.md
@@ -63,6 +63,7 @@ gog drive (drv) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-add-question.md b/docs/commands/gog-forms-add-question.md
index ddf914184..3446f74f5 100644
--- a/docs/commands/gog-forms-add-question.md
+++ b/docs/commands/gog-forms-add-question.md
@@ -41,6 +41,7 @@ gog forms (form) add-question (add-q,aq) --title=STRING <formId> [flags]
 | `-o`<br>`--option` | `[]string` |  | Choice options (for radio/checkbox/dropdown, repeat for each) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--points` | `int` |  | Positive quiz points for the question when --correct is set |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--required` | `bool` |  | Whether an answer is required |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
 | `--scale-high` | `int` | 5 | Scale maximum value: 2 through 10 |
diff --git a/docs/commands/gog-forms-create.md b/docs/commands/gog-forms-create.md
index a75bce0f9..0b7fa4da2 100644
--- a/docs/commands/gog-forms-create.md
+++ b/docs/commands/gog-forms-create.md
@@ -34,6 +34,7 @@ gog forms (form) create (new) --title=STRING [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--title` | `string` |  | Form title |
diff --git a/docs/commands/gog-forms-delete-question.md b/docs/commands/gog-forms-delete-question.md
index 9fa7aded1..dbf6df868 100644
--- a/docs/commands/gog-forms-delete-question.md
+++ b/docs/commands/gog-forms-delete-question.md
@@ -33,6 +33,7 @@ gog forms (form) delete-question (delete-q,dq,rm-q) <formId> <index>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-get.md b/docs/commands/gog-forms-get.md
index 546c33e11..a24661e7b 100644
--- a/docs/commands/gog-forms-get.md
+++ b/docs/commands/gog-forms-get.md
@@ -33,6 +33,7 @@ gog forms (form) get (info,show) <formId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-move-question.md b/docs/commands/gog-forms-move-question.md
index e11ead110..4b990340b 100644
--- a/docs/commands/gog-forms-move-question.md
+++ b/docs/commands/gog-forms-move-question.md
@@ -33,6 +33,7 @@ gog forms (form) move-question (move-q,mq) <formId> <oldIndex> <newIndex>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-publish.md b/docs/commands/gog-forms-publish.md
index c6ef2b6a3..d1ad16174 100644
--- a/docs/commands/gog-forms-publish.md
+++ b/docs/commands/gog-forms-publish.md
@@ -34,6 +34,7 @@ gog forms (form) publish <formId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--unpublish` | `bool` |  | Unpublish the form instead of publishing it |
diff --git a/docs/commands/gog-forms-questions-add.md b/docs/commands/gog-forms-questions-add.md
index 19392d4f6..1cd0f54d6 100644
--- a/docs/commands/gog-forms-questions-add.md
+++ b/docs/commands/gog-forms-questions-add.md
@@ -41,6 +41,7 @@ gog forms (form) questions add (create,new) --title=STRING <formId> [flags]
 | `-o`<br>`--option` | `[]string` |  | Choice options (for radio/checkbox/dropdown, repeat for each) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--points` | `int` |  | Positive quiz points for the question when --correct is set |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--required` | `bool` |  | Whether an answer is required |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
 | `--scale-high` | `int` | 5 | Scale maximum value: 2 through 10 |
diff --git a/docs/commands/gog-forms-questions-delete.md b/docs/commands/gog-forms-questions-delete.md
index a906f7e99..793ea0b5c 100644
--- a/docs/commands/gog-forms-questions-delete.md
+++ b/docs/commands/gog-forms-questions-delete.md
@@ -33,6 +33,7 @@ gog forms (form) questions delete (rm,remove,del) <formId> <index>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-questions-move.md b/docs/commands/gog-forms-questions-move.md
index 0c7ff7990..16aea1ec6 100644
--- a/docs/commands/gog-forms-questions-move.md
+++ b/docs/commands/gog-forms-questions-move.md
@@ -33,6 +33,7 @@ gog forms (form) questions move <formId> <oldIndex> <newIndex>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-questions.md b/docs/commands/gog-forms-questions.md
index 693afcee5..e2a06976a 100644
--- a/docs/commands/gog-forms-questions.md
+++ b/docs/commands/gog-forms-questions.md
@@ -39,6 +39,7 @@ gog forms (form) questions <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-raw.md b/docs/commands/gog-forms-raw.md
index 096558b46..631ba492f 100644
--- a/docs/commands/gog-forms-raw.md
+++ b/docs/commands/gog-forms-raw.md
@@ -34,6 +34,7 @@ gog forms (form) raw <formId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
+| `--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 |
diff --git a/docs/commands/gog-forms-responses-get.md b/docs/commands/gog-forms-responses-get.md
index 55b960a9e..bbe0c06a8 100644
--- a/docs/commands/gog-forms-responses-get.md
+++ b/docs/commands/gog-forms-responses-get.md
@@ -33,6 +33,7 @@ gog forms (form) responses get (info,show) <formId> <responseId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-responses-list.md b/docs/commands/gog-forms-responses-list.md
index a582ee93d..fc97d6bfa 100644
--- a/docs/commands/gog-forms-responses-list.md
+++ b/docs/commands/gog-forms-responses-list.md
@@ -36,6 +36,7 @@ gog forms (form) responses list (ls) <formId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-responses.md b/docs/commands/gog-forms-responses.md
index c8cda2aa3..50fb433dd 100644
--- a/docs/commands/gog-forms-responses.md
+++ b/docs/commands/gog-forms-responses.md
@@ -38,6 +38,7 @@ gog forms (form) responses <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-update.md b/docs/commands/gog-forms-update.md
index ae0e432fd..b982b824d 100644
--- a/docs/commands/gog-forms-update.md
+++ b/docs/commands/gog-forms-update.md
@@ -35,6 +35,7 @@ gog forms (form) update (edit) <formId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--quiz` | `string` |  | Enable quiz mode (true/false) |
+| `--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. |
 | `--title` | `string` |  | New form title |
diff --git a/docs/commands/gog-forms-watch-create.md b/docs/commands/gog-forms-watch-create.md
index 80c01c37c..25f7076c4 100644
--- a/docs/commands/gog-forms-watch-create.md
+++ b/docs/commands/gog-forms-watch-create.md
@@ -34,6 +34,7 @@ gog forms (form) watch (watches) create (new,add) --topic=STRING <formId> [flags
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--topic` | `string` |  | Cloud Pub/Sub topic name (projects/{project}/topics/{topic}) |
diff --git a/docs/commands/gog-forms-watch-delete.md b/docs/commands/gog-forms-watch-delete.md
index f55da294e..e22f1c6cc 100644
--- a/docs/commands/gog-forms-watch-delete.md
+++ b/docs/commands/gog-forms-watch-delete.md
@@ -33,6 +33,7 @@ gog forms (form) watch (watches) delete (rm,remove) <formId> <watchId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-watch-list.md b/docs/commands/gog-forms-watch-list.md
index 118942b37..e04b45054 100644
--- a/docs/commands/gog-forms-watch-list.md
+++ b/docs/commands/gog-forms-watch-list.md
@@ -33,6 +33,7 @@ gog forms (form) watch (watches) list (ls) <formId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-watch-renew.md b/docs/commands/gog-forms-watch-renew.md
index c20c45c79..77bde2795 100644
--- a/docs/commands/gog-forms-watch-renew.md
+++ b/docs/commands/gog-forms-watch-renew.md
@@ -33,6 +33,7 @@ gog forms (form) watch (watches) renew (refresh) <formId> <watchId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms-watch.md b/docs/commands/gog-forms-watch.md
index 78b17e040..85a74de48 100644
--- a/docs/commands/gog-forms-watch.md
+++ b/docs/commands/gog-forms-watch.md
@@ -40,6 +40,7 @@ gog forms (form) watch (watches) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-forms.md b/docs/commands/gog-forms.md
index 7ffecc6d9..5ec1fb89d 100644
--- a/docs/commands/gog-forms.md
+++ b/docs/commands/gog-forms.md
@@ -47,6 +47,7 @@ gog forms (form) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-archive.md b/docs/commands/gog-gmail-archive.md
index 85f89d078..d6faa2f77 100644
--- a/docs/commands/gog-gmail-archive.md
+++ b/docs/commands/gog-gmail-archive.md
@@ -35,6 +35,7 @@ gog gmail (mail,email) archive [<messageId> ...] [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `-q`<br>`--query` | `string` |  | Archive all messages matching this Gmail search query |
+| `--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. |
 | `--thread` | `bool` |  | Treat positional IDs as thread IDs and archive every message in each thread |
diff --git a/docs/commands/gog-gmail-attachment.md b/docs/commands/gog-gmail-attachment.md
index 2cb795550..0accf0e6d 100644
--- a/docs/commands/gog-gmail-attachment.md
+++ b/docs/commands/gog-gmail-attachment.md
@@ -35,6 +35,7 @@ gog gmail (mail,email) attachment <messageId> <attachmentId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--out`<br>`--output` | `string` |  | Output file path (default: gogcli config dir) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-autoreply.md b/docs/commands/gog-gmail-autoreply.md
index 3f608b51e..14f5da028 100644
--- a/docs/commands/gog-gmail-autoreply.md
+++ b/docs/commands/gog-gmail-autoreply.md
@@ -42,6 +42,7 @@ gog gmail (mail,email) autoreply <query> ... [flags]
 | `--max`<br>`--limit` | `int64` | 20 | Max matching messages to inspect |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--reply-to` | `string` |  | Reply-To header address |
 | `--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. |
diff --git a/docs/commands/gog-gmail-batch-delete.md b/docs/commands/gog-gmail-batch-delete.md
index 68e58bd85..65bfb6c30 100644
--- a/docs/commands/gog-gmail-batch-delete.md
+++ b/docs/commands/gog-gmail-batch-delete.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) batch delete (rm,del,remove) <messageId> ...
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-batch-modify.md b/docs/commands/gog-gmail-batch-modify.md
index ad88a4fe8..50167c927 100644
--- a/docs/commands/gog-gmail-batch-modify.md
+++ b/docs/commands/gog-gmail-batch-modify.md
@@ -34,6 +34,7 @@ gog gmail (mail,email) batch modify (update,edit,set) <messageId> ... [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remove` | `string` |  | Labels to remove (comma-separated, name or ID) |
 | `--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. |
diff --git a/docs/commands/gog-gmail-batch.md b/docs/commands/gog-gmail-batch.md
index e391bda6e..8a5b8315a 100644
--- a/docs/commands/gog-gmail-batch.md
+++ b/docs/commands/gog-gmail-batch.md
@@ -38,6 +38,7 @@ gog gmail (mail,email) batch <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-drafts-create.md b/docs/commands/gog-gmail-drafts-create.md
index 148f0695a..13982e795 100644
--- a/docs/commands/gog-gmail-drafts-create.md
+++ b/docs/commands/gog-gmail-drafts-create.md
@@ -42,6 +42,7 @@ gog gmail (mail,email) drafts (draft) create (add,new) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--quote` | `bool` |  | Include quoted original message in reply (requires --reply-to-message-id or --thread-id) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--reply-all` | `bool` |  | Auto-populate recipients from original message (requires --reply-to-message-id or --thread-id) |
 | `--reply-to` | `string` |  | Reply-To header address |
 | `--reply-to-message-id` | `string` |  | Reply to Gmail message ID (sets In-Reply-To/References and thread) |
diff --git a/docs/commands/gog-gmail-drafts-delete.md b/docs/commands/gog-gmail-drafts-delete.md
index 236abafaf..643223568 100644
--- a/docs/commands/gog-gmail-drafts-delete.md
+++ b/docs/commands/gog-gmail-drafts-delete.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) drafts (draft) delete (rm,del,remove) <draftId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-drafts-get.md b/docs/commands/gog-gmail-drafts-get.md
index 31d809772..bb0a60913 100644
--- a/docs/commands/gog-gmail-drafts-get.md
+++ b/docs/commands/gog-gmail-drafts-get.md
@@ -34,6 +34,7 @@ gog gmail (mail,email) drafts (draft) get (info,show) <draftId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-drafts-list.md b/docs/commands/gog-gmail-drafts-list.md
index b184d4e96..712653290 100644
--- a/docs/commands/gog-gmail-drafts-list.md
+++ b/docs/commands/gog-gmail-drafts-list.md
@@ -37,6 +37,7 @@ gog gmail (mail,email) drafts (draft) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-drafts-send.md b/docs/commands/gog-gmail-drafts-send.md
index c4559f2b9..bb8257c48 100644
--- a/docs/commands/gog-gmail-drafts-send.md
+++ b/docs/commands/gog-gmail-drafts-send.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) drafts (draft) send (post) <draftId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-drafts-update.md b/docs/commands/gog-gmail-drafts-update.md
index b77719f18..efa03c398 100644
--- a/docs/commands/gog-gmail-drafts-update.md
+++ b/docs/commands/gog-gmail-drafts-update.md
@@ -43,6 +43,7 @@ gog gmail (mail,email) drafts (draft) update (edit,set) <draftId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--quote` | `bool` |  | Include quoted original message in reply |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--reply-all` | `bool` |  | Auto-populate recipients from original message (requires --reply-to-message-id or --thread-id) |
 | `--reply-to` | `string` |  | Reply-To header address |
 | `--reply-to-message-id` | `string` |  | Reply to Gmail message ID (sets In-Reply-To/References and thread) |
diff --git a/docs/commands/gog-gmail-drafts.md b/docs/commands/gog-gmail-drafts.md
index 848a5c2e2..c3db990c8 100644
--- a/docs/commands/gog-gmail-drafts.md
+++ b/docs/commands/gog-gmail-drafts.md
@@ -42,6 +42,7 @@ gog gmail (mail,email) drafts (draft) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-forward.md b/docs/commands/gog-gmail-forward.md
index f7f4fdc66..ac4a445df 100644
--- a/docs/commands/gog-gmail-forward.md
+++ b/docs/commands/gog-gmail-forward.md
@@ -38,6 +38,7 @@ gog gmail (mail,email) forward (fwd) --to=STRING <messageId> [flags]
 | `--note`<br>`--intro` | `string` |  | Introductory text above the forwarded message |
 | `--note-file` | `string` |  | Note file path (plain text; '-' for stdin) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--skip-attachments` | `bool` |  | Do not include original attachments |
diff --git a/docs/commands/gog-gmail-get.md b/docs/commands/gog-gmail-get.md
index 357b5cdfc..8e2773caf 100644
--- a/docs/commands/gog-gmail-get.md
+++ b/docs/commands/gog-gmail-get.md
@@ -35,6 +35,7 @@ gog gmail (mail,email) get (info,show) <messageId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--sanitize-content`<br>`--safe`<br>`--sanitize` | `bool` |  | Emit agent-oriented sanitized content: strip HTML, remove HTTP(S) URLs, and omit raw Gmail payloads from JSON |
 | `--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. |
diff --git a/docs/commands/gog-gmail-history.md b/docs/commands/gog-gmail-history.md
index 46a179d01..82909fa92 100644
--- a/docs/commands/gog-gmail-history.md
+++ b/docs/commands/gog-gmail-history.md
@@ -37,6 +37,7 @@ gog gmail (mail,email) history [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--since` | `string` |  | Start history ID |
diff --git a/docs/commands/gog-gmail-labels-create.md b/docs/commands/gog-gmail-labels-create.md
index 1ee10d9f0..70dae7191 100644
--- a/docs/commands/gog-gmail-labels-create.md
+++ b/docs/commands/gog-gmail-labels-create.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) labels (label) create (add,new) <name>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-labels-delete.md b/docs/commands/gog-gmail-labels-delete.md
index 2a2680667..66889c5f0 100644
--- a/docs/commands/gog-gmail-labels-delete.md
+++ b/docs/commands/gog-gmail-labels-delete.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) labels (label) delete (rm,del) <labelIdOrName>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-labels-get.md b/docs/commands/gog-gmail-labels-get.md
index 3767f4deb..c8828a2bb 100644
--- a/docs/commands/gog-gmail-labels-get.md
+++ b/docs/commands/gog-gmail-labels-get.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) labels (label) get (info,show) <labelIdOrName>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-labels-list.md b/docs/commands/gog-gmail-labels-list.md
index 47d2258c0..10fec688b 100644
--- a/docs/commands/gog-gmail-labels-list.md
+++ b/docs/commands/gog-gmail-labels-list.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) labels (label) list (ls)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-labels-modify.md b/docs/commands/gog-gmail-labels-modify.md
index adb2b4740..95a695e0c 100644
--- a/docs/commands/gog-gmail-labels-modify.md
+++ b/docs/commands/gog-gmail-labels-modify.md
@@ -34,6 +34,7 @@ gog gmail (mail,email) labels (label) modify (update,edit,set) <threadId> ... [f
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remove` | `string` |  | Labels to remove (comma-separated, name or ID) |
 | `--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. |
diff --git a/docs/commands/gog-gmail-labels-rename.md b/docs/commands/gog-gmail-labels-rename.md
index 55798a08f..6b90579c6 100644
--- a/docs/commands/gog-gmail-labels-rename.md
+++ b/docs/commands/gog-gmail-labels-rename.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) labels (label) rename (mv) <labelIdOrName> <newName>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-labels-style.md b/docs/commands/gog-gmail-labels-style.md
index 9837addaa..6a4263089 100644
--- a/docs/commands/gog-gmail-labels-style.md
+++ b/docs/commands/gog-gmail-labels-style.md
@@ -36,6 +36,7 @@ gog gmail (mail,email) labels (label) style (color,colour) <labelIdOrName> [flag
 | `--message-list-visibility` | `string` |  | Message-list visibility: show\|hide |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--text-color` | `string` |  | Text color from Gmail's label palette as #RRGGBB |
diff --git a/docs/commands/gog-gmail-labels.md b/docs/commands/gog-gmail-labels.md
index 7517b4735..1392899a2 100644
--- a/docs/commands/gog-gmail-labels.md
+++ b/docs/commands/gog-gmail-labels.md
@@ -43,6 +43,7 @@ gog gmail (mail,email) labels (label) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-mark-read.md b/docs/commands/gog-gmail-mark-read.md
index c739140e5..451215c64 100644
--- a/docs/commands/gog-gmail-mark-read.md
+++ b/docs/commands/gog-gmail-mark-read.md
@@ -35,6 +35,7 @@ gog gmail (mail,email) mark-read (read-messages) [<messageId> ...] [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `-q`<br>`--query` | `string` |  | Mark all messages matching this query as read |
+| `--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 |
diff --git a/docs/commands/gog-gmail-messages-modify.md b/docs/commands/gog-gmail-messages-modify.md
index a08d0a6ac..7b50131d7 100644
--- a/docs/commands/gog-gmail-messages-modify.md
+++ b/docs/commands/gog-gmail-messages-modify.md
@@ -34,6 +34,7 @@ gog gmail (mail,email) messages (message,msg,msgs) modify (update,edit,set) <mes
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remove` | `string` |  | Labels to remove (comma-separated, name or ID) |
 | `--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. |
diff --git a/docs/commands/gog-gmail-messages-search.md b/docs/commands/gog-gmail-messages-search.md
index d4c655277..7364cf42b 100644
--- a/docs/commands/gog-gmail-messages-search.md
+++ b/docs/commands/gog-gmail-messages-search.md
@@ -41,6 +41,7 @@ gog gmail (mail,email) messages (message,msg,msgs) search (find,query,ls,list) <
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `-z`<br>`--timezone` | `string` |  | Output timezone (IANA name, e.g. America/New_York, UTC). Default: GOG_TIMEZONE, config, then local |
diff --git a/docs/commands/gog-gmail-messages.md b/docs/commands/gog-gmail-messages.md
index 4c189270e..f4450ca9d 100644
--- a/docs/commands/gog-gmail-messages.md
+++ b/docs/commands/gog-gmail-messages.md
@@ -38,6 +38,7 @@ gog gmail (mail,email) messages (message,msg,msgs) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-raw.md b/docs/commands/gog-gmail-raw.md
index c6e76c4e4..ffe9bf153 100644
--- a/docs/commands/gog-gmail-raw.md
+++ b/docs/commands/gog-gmail-raw.md
@@ -35,6 +35,7 @@ gog gmail (mail,email) raw <messageId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-reply-all.md b/docs/commands/gog-gmail-reply-all.md
index 80dc83ee1..39fe7c4c1 100644
--- a/docs/commands/gog-gmail-reply-all.md
+++ b/docs/commands/gog-gmail-reply-all.md
@@ -42,6 +42,7 @@ gog gmail (mail,email) reply-all (replyall) <messageId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--no-quote` | `bool` |  | Do not include the original message below the reply |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remove` | `[]string` |  | Remove recipients from all fields (repeatable) |
 | `--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. |
diff --git a/docs/commands/gog-gmail-reply.md b/docs/commands/gog-gmail-reply.md
index 0968ecdf2..3f21a4b5a 100644
--- a/docs/commands/gog-gmail-reply.md
+++ b/docs/commands/gog-gmail-reply.md
@@ -42,6 +42,7 @@ gog gmail (mail,email) reply <messageId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--no-quote` | `bool` |  | Do not include the original message below the reply |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remove` | `[]string` |  | Remove recipients from all fields (repeatable) |
 | `--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. |
diff --git a/docs/commands/gog-gmail-search.md b/docs/commands/gog-gmail-search.md
index 550d007a8..9608ac800 100644
--- a/docs/commands/gog-gmail-search.md
+++ b/docs/commands/gog-gmail-search.md
@@ -40,6 +40,7 @@ gog gmail (mail,email) search (find,query,ls,list) <query> ... [flags]
 | `--oldest` | `bool` |  | Show first message date instead of last |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `-z`<br>`--timezone` | `string` |  | Output timezone (IANA name, e.g. America/New_York, UTC). Default: GOG_TIMEZONE, config, then local |
diff --git a/docs/commands/gog-gmail-send.md b/docs/commands/gog-gmail-send.md
index 02e98b303..7437a51a9 100644
--- a/docs/commands/gog-gmail-send.md
+++ b/docs/commands/gog-gmail-send.md
@@ -42,6 +42,7 @@ gog gmail (mail,email) send [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--quote` | `bool` |  | Include quoted original message in reply (requires --reply-to-message-id or --thread-id) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--reply-all` | `bool` |  | Auto-populate recipients from original message (requires --reply-to-message-id or --thread-id) |
 | `--reply-to` | `string` |  | Reply-To header address |
 | `--reply-to-message-id`<br>`--in-reply-to` | `string` |  | Reply to Gmail message ID (sets In-Reply-To/References and thread) |
diff --git a/docs/commands/gog-gmail-settings-autoforward-get.md b/docs/commands/gog-gmail-settings-autoforward-get.md
index 0b9247a28..dd5c838d8 100644
--- a/docs/commands/gog-gmail-settings-autoforward-get.md
+++ b/docs/commands/gog-gmail-settings-autoforward-get.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings autoforward get (info,show)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-autoforward-update.md b/docs/commands/gog-gmail-settings-autoforward-update.md
index 98832c7f5..bbc15187f 100644
--- a/docs/commands/gog-gmail-settings-autoforward-update.md
+++ b/docs/commands/gog-gmail-settings-autoforward-update.md
@@ -37,6 +37,7 @@ gog gmail (mail,email) settings autoforward update (edit,set) [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-autoforward.md b/docs/commands/gog-gmail-settings-autoforward.md
index 82ef4aceb..3392515a2 100644
--- a/docs/commands/gog-gmail-settings-autoforward.md
+++ b/docs/commands/gog-gmail-settings-autoforward.md
@@ -38,6 +38,7 @@ gog gmail (mail,email) settings autoforward <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-delegates-add.md b/docs/commands/gog-gmail-settings-delegates-add.md
index 6d445cb3b..3efee8e98 100644
--- a/docs/commands/gog-gmail-settings-delegates-add.md
+++ b/docs/commands/gog-gmail-settings-delegates-add.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings delegates add (create,new) <delegateEmail>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-delegates-get.md b/docs/commands/gog-gmail-settings-delegates-get.md
index b0bdfedf8..35724f098 100644
--- a/docs/commands/gog-gmail-settings-delegates-get.md
+++ b/docs/commands/gog-gmail-settings-delegates-get.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings delegates get (info,show) <delegateEmail>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-delegates-list.md b/docs/commands/gog-gmail-settings-delegates-list.md
index 36fcb8376..ac259b50c 100644
--- a/docs/commands/gog-gmail-settings-delegates-list.md
+++ b/docs/commands/gog-gmail-settings-delegates-list.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings delegates list (ls)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-delegates-remove.md b/docs/commands/gog-gmail-settings-delegates-remove.md
index e6da67ae4..f01f5aba9 100644
--- a/docs/commands/gog-gmail-settings-delegates-remove.md
+++ b/docs/commands/gog-gmail-settings-delegates-remove.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings delegates remove (delete,rm,del) <delegateEmail>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-delegates.md b/docs/commands/gog-gmail-settings-delegates.md
index 0fa16d396..9ac913e5e 100644
--- a/docs/commands/gog-gmail-settings-delegates.md
+++ b/docs/commands/gog-gmail-settings-delegates.md
@@ -40,6 +40,7 @@ gog gmail (mail,email) settings delegates <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-filters-create.md b/docs/commands/gog-gmail-settings-filters-create.md
index d3de8d7f5..1530406de 100644
--- a/docs/commands/gog-gmail-settings-filters-create.md
+++ b/docs/commands/gog-gmail-settings-filters-create.md
@@ -42,6 +42,7 @@ gog gmail (mail,email) settings filters create (add,new) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--query` | `string` |  | Advanced Gmail search query for matching |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remove-label` | `string` |  | Label(s) to remove from matching messages (comma-separated, name or ID) |
 | `--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. |
diff --git a/docs/commands/gog-gmail-settings-filters-delete.md b/docs/commands/gog-gmail-settings-filters-delete.md
index 0f3fbb151..cdfbc1a29 100644
--- a/docs/commands/gog-gmail-settings-filters-delete.md
+++ b/docs/commands/gog-gmail-settings-filters-delete.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings filters delete (rm,del,remove) <filterId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-filters-export.md b/docs/commands/gog-gmail-settings-filters-export.md
index b39e5b564..02573a345 100644
--- a/docs/commands/gog-gmail-settings-filters-export.md
+++ b/docs/commands/gog-gmail-settings-filters-export.md
@@ -35,6 +35,7 @@ gog gmail (mail,email) settings filters export [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-o`<br>`--out` | `string` |  | Write export to this file (defaults to stdout) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-filters-get.md b/docs/commands/gog-gmail-settings-filters-get.md
index 91a75d29f..042ac0592 100644
--- a/docs/commands/gog-gmail-settings-filters-get.md
+++ b/docs/commands/gog-gmail-settings-filters-get.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings filters get (info,show) <filterId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-filters-list.md b/docs/commands/gog-gmail-settings-filters-list.md
index be20966d4..5f6c36757 100644
--- a/docs/commands/gog-gmail-settings-filters-list.md
+++ b/docs/commands/gog-gmail-settings-filters-list.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings filters list (ls)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-filters.md b/docs/commands/gog-gmail-settings-filters.md
index 65fa10a13..764e42293 100644
--- a/docs/commands/gog-gmail-settings-filters.md
+++ b/docs/commands/gog-gmail-settings-filters.md
@@ -41,6 +41,7 @@ gog gmail (mail,email) settings filters <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-forwarding-create.md b/docs/commands/gog-gmail-settings-forwarding-create.md
index 5ac7a58f3..46e1c851c 100644
--- a/docs/commands/gog-gmail-settings-forwarding-create.md
+++ b/docs/commands/gog-gmail-settings-forwarding-create.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings forwarding create (add,new) <forwardingEmail>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-forwarding-delete.md b/docs/commands/gog-gmail-settings-forwarding-delete.md
index 58a6ccbf2..645f6660c 100644
--- a/docs/commands/gog-gmail-settings-forwarding-delete.md
+++ b/docs/commands/gog-gmail-settings-forwarding-delete.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings forwarding delete (rm,del,remove) <forwardingEma
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-forwarding-get.md b/docs/commands/gog-gmail-settings-forwarding-get.md
index dc2a4055c..000a20633 100644
--- a/docs/commands/gog-gmail-settings-forwarding-get.md
+++ b/docs/commands/gog-gmail-settings-forwarding-get.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings forwarding get (info,show) <forwardingEmail>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-forwarding-list.md b/docs/commands/gog-gmail-settings-forwarding-list.md
index 227f7c8b2..1cfdcb6ea 100644
--- a/docs/commands/gog-gmail-settings-forwarding-list.md
+++ b/docs/commands/gog-gmail-settings-forwarding-list.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings forwarding list (ls)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-forwarding.md b/docs/commands/gog-gmail-settings-forwarding.md
index 6bfbf5ff5..97135877f 100644
--- a/docs/commands/gog-gmail-settings-forwarding.md
+++ b/docs/commands/gog-gmail-settings-forwarding.md
@@ -40,6 +40,7 @@ gog gmail (mail,email) settings forwarding <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-sendas-create.md b/docs/commands/gog-gmail-settings-sendas-create.md
index 17fd2a889..a3d24b6db 100644
--- a/docs/commands/gog-gmail-settings-sendas-create.md
+++ b/docs/commands/gog-gmail-settings-sendas-create.md
@@ -34,6 +34,7 @@ gog gmail (mail,email) settings sendas create (add,new) <email> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--reply-to` | `string` |  | Reply-to address (optional) |
 | `--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. |
diff --git a/docs/commands/gog-gmail-settings-sendas-delete.md b/docs/commands/gog-gmail-settings-sendas-delete.md
index 687677079..5defefd67 100644
--- a/docs/commands/gog-gmail-settings-sendas-delete.md
+++ b/docs/commands/gog-gmail-settings-sendas-delete.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings sendas delete (rm,del,remove) <email>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-sendas-get.md b/docs/commands/gog-gmail-settings-sendas-get.md
index 04a404e17..9158cb247 100644
--- a/docs/commands/gog-gmail-settings-sendas-get.md
+++ b/docs/commands/gog-gmail-settings-sendas-get.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings sendas get (info,show) <email>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-sendas-list.md b/docs/commands/gog-gmail-settings-sendas-list.md
index 486256237..23be3449f 100644
--- a/docs/commands/gog-gmail-settings-sendas-list.md
+++ b/docs/commands/gog-gmail-settings-sendas-list.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings sendas list (ls)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-sendas-update.md b/docs/commands/gog-gmail-settings-sendas-update.md
index f8d9e617b..d5b9d4a63 100644
--- a/docs/commands/gog-gmail-settings-sendas-update.md
+++ b/docs/commands/gog-gmail-settings-sendas-update.md
@@ -35,6 +35,7 @@ gog gmail (mail,email) settings sendas update (edit,set) <email> [flags]
 | `--make-default` | `bool` |  | Make this the default send-as address |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--reply-to` | `string` |  | Reply-to address |
 | `--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. |
diff --git a/docs/commands/gog-gmail-settings-sendas-verify.md b/docs/commands/gog-gmail-settings-sendas-verify.md
index b931beec2..9bdfbcc1f 100644
--- a/docs/commands/gog-gmail-settings-sendas-verify.md
+++ b/docs/commands/gog-gmail-settings-sendas-verify.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings sendas verify (resend) <email>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-sendas.md b/docs/commands/gog-gmail-settings-sendas.md
index 6d2b9349f..1f469876b 100644
--- a/docs/commands/gog-gmail-settings-sendas.md
+++ b/docs/commands/gog-gmail-settings-sendas.md
@@ -42,6 +42,7 @@ gog gmail (mail,email) settings sendas <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-vacation-get.md b/docs/commands/gog-gmail-settings-vacation-get.md
index 5bda95b59..6f9876fc6 100644
--- a/docs/commands/gog-gmail-settings-vacation-get.md
+++ b/docs/commands/gog-gmail-settings-vacation-get.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings vacation get (info,show)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-vacation-update.md b/docs/commands/gog-gmail-settings-vacation-update.md
index ac3a1e15e..500a98766 100644
--- a/docs/commands/gog-gmail-settings-vacation-update.md
+++ b/docs/commands/gog-gmail-settings-vacation-update.md
@@ -39,6 +39,7 @@ gog gmail (mail,email) settings vacation update (edit,set) [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--start` | `string` |  | Start time in RFC3339 format (e.g., 2024-12-20T00:00:00Z) |
diff --git a/docs/commands/gog-gmail-settings-vacation.md b/docs/commands/gog-gmail-settings-vacation.md
index 2cd6e9d1e..83e7b14c9 100644
--- a/docs/commands/gog-gmail-settings-vacation.md
+++ b/docs/commands/gog-gmail-settings-vacation.md
@@ -38,6 +38,7 @@ gog gmail (mail,email) settings vacation <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-watch-pull.md b/docs/commands/gog-gmail-settings-watch-pull.md
index 5dfeb61a0..d74ec08a8 100644
--- a/docs/commands/gog-gmail-settings-watch-pull.md
+++ b/docs/commands/gog-gmail-settings-watch-pull.md
@@ -41,6 +41,7 @@ gog gmail (mail,email) settings watch pull [flags]
 | `--max-bytes` | `int` | 20000 | Max bytes of body to include |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--save-hook` | `bool` |  | Persist hook settings to watch state |
 | `--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. |
diff --git a/docs/commands/gog-gmail-settings-watch-renew.md b/docs/commands/gog-gmail-settings-watch-renew.md
index 75ebcc39a..df53f2dfe 100644
--- a/docs/commands/gog-gmail-settings-watch-renew.md
+++ b/docs/commands/gog-gmail-settings-watch-renew.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings watch renew (update) [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--ttl` | `string` |  | Renew after duration (seconds or Go duration) |
diff --git a/docs/commands/gog-gmail-settings-watch-serve.md b/docs/commands/gog-gmail-settings-watch-serve.md
index 7f5a9f60c..e01213c24 100644
--- a/docs/commands/gog-gmail-settings-watch-serve.md
+++ b/docs/commands/gog-gmail-settings-watch-serve.md
@@ -46,6 +46,7 @@ gog gmail (mail,email) settings watch serve [flags]
 | `--path` | `string` | /gmail-pubsub | Push handler path |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--port` | `int` | 8788 | Listen port |
+| `--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) |
 | `--save-hook` | `bool` |  | Persist hook settings to watch state |
 | `--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. |
diff --git a/docs/commands/gog-gmail-settings-watch-start.md b/docs/commands/gog-gmail-settings-watch-start.md
index 5a03fab73..8e88eeb72 100644
--- a/docs/commands/gog-gmail-settings-watch-start.md
+++ b/docs/commands/gog-gmail-settings-watch-start.md
@@ -38,6 +38,7 @@ gog gmail (mail,email) settings watch start (begin) [flags]
 | `--max-bytes` | `int` | 20000 | Max bytes of body to include |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--topic` | `string` |  | Pub/Sub topic (projects/.../topics/...) |
diff --git a/docs/commands/gog-gmail-settings-watch-status.md b/docs/commands/gog-gmail-settings-watch-status.md
index 6fda41bf3..6d107b009 100644
--- a/docs/commands/gog-gmail-settings-watch-status.md
+++ b/docs/commands/gog-gmail-settings-watch-status.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings watch status (ls) [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--show-secrets` | `bool` |  | Show secret values (e.g. hook token) in plaintext |
diff --git a/docs/commands/gog-gmail-settings-watch-stop.md b/docs/commands/gog-gmail-settings-watch-stop.md
index 1895d598b..7022d49df 100644
--- a/docs/commands/gog-gmail-settings-watch-stop.md
+++ b/docs/commands/gog-gmail-settings-watch-stop.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) settings watch stop (rm,delete)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings-watch.md b/docs/commands/gog-gmail-settings-watch.md
index ff1e2b69a..a67bf17b6 100644
--- a/docs/commands/gog-gmail-settings-watch.md
+++ b/docs/commands/gog-gmail-settings-watch.md
@@ -42,6 +42,7 @@ gog gmail (mail,email) settings watch <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-settings.md b/docs/commands/gog-gmail-settings.md
index f2880de50..89dd5165c 100644
--- a/docs/commands/gog-gmail-settings.md
+++ b/docs/commands/gog-gmail-settings.md
@@ -43,6 +43,7 @@ gog gmail (mail,email) settings <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-thread-attachments.md b/docs/commands/gog-gmail-thread-attachments.md
index c542df790..6f3cfba8c 100644
--- a/docs/commands/gog-gmail-thread-attachments.md
+++ b/docs/commands/gog-gmail-thread-attachments.md
@@ -35,6 +35,7 @@ gog gmail (mail,email) thread (threads,read) attachments (files) <threadId> [fla
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--out-dir`<br>`--output-dir` | `string` |  | Directory to write attachments to (default: current directory) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-thread-get.md b/docs/commands/gog-gmail-thread-get.md
index 8e446e5e4..80708f1f4 100644
--- a/docs/commands/gog-gmail-thread-get.md
+++ b/docs/commands/gog-gmail-thread-get.md
@@ -36,6 +36,7 @@ gog gmail (mail,email) thread (threads,read) get (info,show) <threadId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--out-dir`<br>`--output-dir` | `string` |  | Directory to write attachments to (default: current directory) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--sanitize-content`<br>`--safe`<br>`--sanitize` | `bool` |  | Emit agent-oriented sanitized content: strip HTML, remove HTTP(S) URLs, and omit raw Gmail payloads from JSON |
 | `--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. |
diff --git a/docs/commands/gog-gmail-thread-modify.md b/docs/commands/gog-gmail-thread-modify.md
index 06f328c60..693140d2e 100644
--- a/docs/commands/gog-gmail-thread-modify.md
+++ b/docs/commands/gog-gmail-thread-modify.md
@@ -34,6 +34,7 @@ gog gmail (mail,email) thread (threads,read) modify (update,edit,set) <threadId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--remove` | `string` |  | Labels to remove (comma-separated, name or ID) |
 | `--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. |
diff --git a/docs/commands/gog-gmail-thread.md b/docs/commands/gog-gmail-thread.md
index 144e2e9d3..24e3101fc 100644
--- a/docs/commands/gog-gmail-thread.md
+++ b/docs/commands/gog-gmail-thread.md
@@ -39,6 +39,7 @@ gog gmail (mail,email) thread (threads,read) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-track-key-rotate.md b/docs/commands/gog-gmail-track-key-rotate.md
index 28570a13d..1a9353343 100644
--- a/docs/commands/gog-gmail-track-key-rotate.md
+++ b/docs/commands/gog-gmail-track-key-rotate.md
@@ -34,6 +34,7 @@ gog gmail (mail,email) track key rotate [flags]
 | `--no-deploy` | `bool` |  | Update local tracking keys without deploying the Worker |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-track-key.md b/docs/commands/gog-gmail-track-key.md
index 1ac4e23b9..53d35d1e4 100644
--- a/docs/commands/gog-gmail-track-key.md
+++ b/docs/commands/gog-gmail-track-key.md
@@ -37,6 +37,7 @@ gog gmail (mail,email) track key <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-track-opens.md b/docs/commands/gog-gmail-track-opens.md
index 3f628026e..f176b9ad9 100644
--- a/docs/commands/gog-gmail-track-opens.md
+++ b/docs/commands/gog-gmail-track-opens.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) track opens [<tracking-id>] [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--since` | `string` |  | Filter by time (e.g., '24h', '2024-01-01') |
diff --git a/docs/commands/gog-gmail-track-setup.md b/docs/commands/gog-gmail-track-setup.md
index b06c4cb29..7720c35bd 100644
--- a/docs/commands/gog-gmail-track-setup.md
+++ b/docs/commands/gog-gmail-track-setup.md
@@ -36,6 +36,7 @@ gog gmail (mail,email) track setup [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tracking-key` | `string` |  | Tracking key (base64; generates one if omitted) |
diff --git a/docs/commands/gog-gmail-track-status.md b/docs/commands/gog-gmail-track-status.md
index 4a76c1d13..2b7b7a31f 100644
--- a/docs/commands/gog-gmail-track-status.md
+++ b/docs/commands/gog-gmail-track-status.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) track status
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-track.md b/docs/commands/gog-gmail-track.md
index 3a030e399..fb440930a 100644
--- a/docs/commands/gog-gmail-track.md
+++ b/docs/commands/gog-gmail-track.md
@@ -40,6 +40,7 @@ gog gmail (mail,email) track <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail-trash.md b/docs/commands/gog-gmail-trash.md
index 04e4b4b93..f61dc93e8 100644
--- a/docs/commands/gog-gmail-trash.md
+++ b/docs/commands/gog-gmail-trash.md
@@ -35,6 +35,7 @@ gog gmail (mail,email) trash [<messageId> ...] [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `-q`<br>`--query` | `string` |  | Trash all messages matching this Gmail search query |
+| `--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 |
diff --git a/docs/commands/gog-gmail-unread.md b/docs/commands/gog-gmail-unread.md
index 21443a177..40aec47ed 100644
--- a/docs/commands/gog-gmail-unread.md
+++ b/docs/commands/gog-gmail-unread.md
@@ -35,6 +35,7 @@ gog gmail (mail,email) unread (mark-unread) [<messageId> ...] [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `-q`<br>`--query` | `string` |  | Mark all messages matching this query as unread |
+| `--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 |
diff --git a/docs/commands/gog-gmail-url.md b/docs/commands/gog-gmail-url.md
index 77d207825..7c7e0105e 100644
--- a/docs/commands/gog-gmail-url.md
+++ b/docs/commands/gog-gmail-url.md
@@ -33,6 +33,7 @@ gog gmail (mail,email) url <threadId> ...
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-gmail.md b/docs/commands/gog-gmail.md
index 080abfacf..37c84c8cb 100644
--- a/docs/commands/gog-gmail.md
+++ b/docs/commands/gog-gmail.md
@@ -58,6 +58,7 @@ gog gmail (mail,email) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-groups-list.md b/docs/commands/gog-groups-list.md
index 12fa0b529..e4640353f 100644
--- a/docs/commands/gog-groups-list.md
+++ b/docs/commands/gog-groups-list.md
@@ -37,6 +37,7 @@ gog groups (group) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-groups-members.md b/docs/commands/gog-groups-members.md
index 05e61b2f8..97a7be0c3 100644
--- a/docs/commands/gog-groups-members.md
+++ b/docs/commands/gog-groups-members.md
@@ -37,6 +37,7 @@ gog groups (group) members <groupEmail> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-groups.md b/docs/commands/gog-groups.md
index 9276ce627..921738ba7 100644
--- a/docs/commands/gog-groups.md
+++ b/docs/commands/gog-groups.md
@@ -38,6 +38,7 @@ gog groups (group) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-keep-attachment.md b/docs/commands/gog-keep-attachment.md
index 160cb19ab..0d5b8f02e 100644
--- a/docs/commands/gog-keep-attachment.md
+++ b/docs/commands/gog-keep-attachment.md
@@ -36,6 +36,7 @@ gog keep attachment <attachmentName> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--out` | `string` |  | Output file path (default: attachment filename or ID) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--service-account` | `string` |  | Path to service account JSON file |
diff --git a/docs/commands/gog-keep-create.md b/docs/commands/gog-keep-create.md
index 691c52dfd..7f73a24db 100644
--- a/docs/commands/gog-keep-create.md
+++ b/docs/commands/gog-keep-create.md
@@ -35,6 +35,7 @@ gog keep create [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--service-account` | `string` |  | Path to service account JSON file |
diff --git a/docs/commands/gog-keep-delete.md b/docs/commands/gog-keep-delete.md
index 459ddc68e..58fa21ebf 100644
--- a/docs/commands/gog-keep-delete.md
+++ b/docs/commands/gog-keep-delete.md
@@ -34,6 +34,7 @@ gog keep delete <noteId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--service-account` | `string` |  | Path to service account JSON file |
diff --git a/docs/commands/gog-keep-get.md b/docs/commands/gog-keep-get.md
index 8479dd33c..23079d8ac 100644
--- a/docs/commands/gog-keep-get.md
+++ b/docs/commands/gog-keep-get.md
@@ -34,6 +34,7 @@ gog keep get <noteId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--service-account` | `string` |  | Path to service account JSON file |
diff --git a/docs/commands/gog-keep-list.md b/docs/commands/gog-keep-list.md
index ccb63e240..11b2f1541 100644
--- a/docs/commands/gog-keep-list.md
+++ b/docs/commands/gog-keep-list.md
@@ -39,6 +39,7 @@ gog keep list [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--service-account` | `string` |  | Path to service account JSON file |
diff --git a/docs/commands/gog-keep-search.md b/docs/commands/gog-keep-search.md
index eca2e42df..7ba366b51 100644
--- a/docs/commands/gog-keep-search.md
+++ b/docs/commands/gog-keep-search.md
@@ -35,6 +35,7 @@ gog keep search <query> [flags]
 | `--max`<br>`--limit` | `int64` | 500 | Max results to fetch before filtering |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--service-account` | `string` |  | Path to service account JSON file |
diff --git a/docs/commands/gog-keep.md b/docs/commands/gog-keep.md
index ebb6f7884..d85773e74 100644
--- a/docs/commands/gog-keep.md
+++ b/docs/commands/gog-keep.md
@@ -43,6 +43,7 @@ gog keep <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--service-account` | `string` |  | Path to service account JSON file |
diff --git a/docs/commands/gog-login.md b/docs/commands/gog-login.md
index ff157d12d..08d4a42d3 100644
--- a/docs/commands/gog-login.md
+++ b/docs/commands/gog-login.md
@@ -40,7 +40,7 @@ gog login <email> [flags]
 | `--manual` | `bool` |  | Browserless auth flow (paste redirect URL) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
-| `--readonly` | `bool` |  | Use read-only scopes where available (still includes OIDC identity scopes) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--redirect-host` | `string` |  | Hostname for OAuth callback in browser flows; builds https://{host}/oauth2/callback |
 | `--redirect-uri` | `string` |  | Override OAuth redirect URI for manual/remote flows (for example https://host.example/oauth2/callback) |
 | `--remote` | `bool` |  | Remote/server-friendly manual flow (print URL, then exchange code) |
diff --git a/docs/commands/gog-logout.md b/docs/commands/gog-logout.md
index e524f8721..e0bbfe90c 100644
--- a/docs/commands/gog-logout.md
+++ b/docs/commands/gog-logout.md
@@ -33,6 +33,7 @@ gog logout <email> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-ls.md b/docs/commands/gog-ls.md
index 3e7f007b5..12e594416 100644
--- a/docs/commands/gog-ls.md
+++ b/docs/commands/gog-ls.md
@@ -40,6 +40,7 @@ gog ls (list) [flags]
 | `--parent` | `string` |  | Folder ID to list (default: root) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--query` | `string` |  | Drive query filter |
+| `--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 |
diff --git a/docs/commands/gog-maps-directions.md b/docs/commands/gog-maps-directions.md
index bee289e45..181eccff7 100644
--- a/docs/commands/gog-maps-directions.md
+++ b/docs/commands/gog-maps-directions.md
@@ -37,6 +37,7 @@ gog maps (map) directions (route) --origin=STRING --destination=STRING [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--origin` | `string` |  | Origin address, place ID, or lat,lng |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--region` | `string` |  | Region bias |
 | `--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. |
diff --git a/docs/commands/gog-maps-distance.md b/docs/commands/gog-maps-distance.md
index 5597b2c74..462742ffd 100644
--- a/docs/commands/gog-maps-distance.md
+++ b/docs/commands/gog-maps-distance.md
@@ -37,6 +37,7 @@ gog maps (map) distance (distance-matrix,matrix) --origins=STRING --destinations
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--origins` | `string` |  | Comma-separated origins |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--region` | `string` |  | Region bias |
 | `--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. |
diff --git a/docs/commands/gog-maps-geocode.md b/docs/commands/gog-maps-geocode.md
index 7c1aa099b..10af63926 100644
--- a/docs/commands/gog-maps-geocode.md
+++ b/docs/commands/gog-maps-geocode.md
@@ -34,6 +34,7 @@ gog maps (map) geocode <address> ... [flags]
 | `--language` | `string` |  | BCP-47 language code |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--region` | `string` |  | Region bias |
 | `--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. |
diff --git a/docs/commands/gog-maps-places-details.md b/docs/commands/gog-maps-places-details.md
index 7b6eaada0..5cbad93f1 100644
--- a/docs/commands/gog-maps-places-details.md
+++ b/docs/commands/gog-maps-places-details.md
@@ -34,6 +34,7 @@ gog maps (map) places (place) details (get,info,show) <placeId> [flags]
 | `--language` | `string` |  | BCP-47 language code |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--region` | `string` |  | CLDR region code |
 | `--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. |
diff --git a/docs/commands/gog-maps-places-search.md b/docs/commands/gog-maps-places-search.md
index 06c927555..d96c6a849 100644
--- a/docs/commands/gog-maps-places-search.md
+++ b/docs/commands/gog-maps-places-search.md
@@ -34,6 +34,7 @@ gog maps (map) places (place) search (find) <query> ... [flags]
 | `--language` | `string` |  | BCP-47 language code |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--region` | `string` |  | CLDR region code |
 | `--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. |
diff --git a/docs/commands/gog-maps-places.md b/docs/commands/gog-maps-places.md
index 3998c0844..d6b1e58d0 100644
--- a/docs/commands/gog-maps-places.md
+++ b/docs/commands/gog-maps-places.md
@@ -38,6 +38,7 @@ gog maps (map) places (place) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-maps-reverse-geocode.md b/docs/commands/gog-maps-reverse-geocode.md
index 678a079c3..ac303a2c0 100644
--- a/docs/commands/gog-maps-reverse-geocode.md
+++ b/docs/commands/gog-maps-reverse-geocode.md
@@ -36,6 +36,7 @@ gog maps (map) reverse-geocode (reverse) --lat=STRING --lng=STRING [flags]
 | `--lng` | `string` |  | Longitude |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--region` | `string` |  | Region bias |
 | `--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. |
diff --git a/docs/commands/gog-maps.md b/docs/commands/gog-maps.md
index c5616510d..c006ad6a6 100644
--- a/docs/commands/gog-maps.md
+++ b/docs/commands/gog-maps.md
@@ -41,6 +41,7 @@ gog maps (map) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-mcp.md b/docs/commands/gog-mcp.md
index 82700b34f..f3eac3a3d 100644
--- a/docs/commands/gog-mcp.md
+++ b/docs/commands/gog-mcp.md
@@ -37,6 +37,7 @@ gog mcp [flags]
 | `--max-output-bytes` | `int` | 102400 | Max stdout/stderr bytes captured per tool call |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--timeout-seconds` | `int` | 60 | Per-tool subprocess timeout |
diff --git a/docs/commands/gog-me.md b/docs/commands/gog-me.md
index fa4a9683d..81026bcdb 100644
--- a/docs/commands/gog-me.md
+++ b/docs/commands/gog-me.md
@@ -33,6 +33,7 @@ gog me [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-meet-create.md b/docs/commands/gog-meet-create.md
index cb53fc6ae..060f6e160 100644
--- a/docs/commands/gog-meet-create.md
+++ b/docs/commands/gog-meet-create.md
@@ -35,6 +35,7 @@ gog meet (meeting) create (new) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--open`<br>`--browser` | `bool` |  | Open the meeting in a browser after creation |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-meet-end.md b/docs/commands/gog-meet-end.md
index e29dc4eae..030d2a7e4 100644
--- a/docs/commands/gog-meet-end.md
+++ b/docs/commands/gog-meet-end.md
@@ -33,6 +33,7 @@ gog meet (meeting) end (stop) <meeting-code>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-meet-get.md b/docs/commands/gog-meet-get.md
index 6285b812c..b5829ac11 100644
--- a/docs/commands/gog-meet-get.md
+++ b/docs/commands/gog-meet-get.md
@@ -33,6 +33,7 @@ gog meet (meeting) get (info,show) <meeting-code>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-meet-history.md b/docs/commands/gog-meet-history.md
index 28eda31af..6dc4a5fbc 100644
--- a/docs/commands/gog-meet-history.md
+++ b/docs/commands/gog-meet-history.md
@@ -37,6 +37,7 @@ gog meet (meeting) history (calls,past) <meeting-code> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-meet-participants.md b/docs/commands/gog-meet-participants.md
index 212cf4b6a..b90f55749 100644
--- a/docs/commands/gog-meet-participants.md
+++ b/docs/commands/gog-meet-participants.md
@@ -38,6 +38,7 @@ gog meet (meeting) participants (people,attendees,who) <meeting-code> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-meet-update.md b/docs/commands/gog-meet-update.md
index 0e21559e5..8a6fa6a1e 100644
--- a/docs/commands/gog-meet-update.md
+++ b/docs/commands/gog-meet-update.md
@@ -34,6 +34,7 @@ gog meet (meeting) update (edit,set) <meeting-code> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-meet.md b/docs/commands/gog-meet.md
index d36f7bc96..c6b0ea805 100644
--- a/docs/commands/gog-meet.md
+++ b/docs/commands/gog-meet.md
@@ -42,6 +42,7 @@ gog meet (meeting) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-open.md b/docs/commands/gog-open.md
index ef78a943a..d0254b089 100644
--- a/docs/commands/gog-open.md
+++ b/docs/commands/gog-open.md
@@ -33,6 +33,7 @@ gog open (browse) <target> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--type` | `string` | auto | Type hint (auto\|drive\|folder\|docs\|sheets\|slides\|sites\|gmail-thread) |
diff --git a/docs/commands/gog-people-get.md b/docs/commands/gog-people-get.md
index 47e8c2f84..343793e9d 100644
--- a/docs/commands/gog-people-get.md
+++ b/docs/commands/gog-people-get.md
@@ -33,6 +33,7 @@ gog people (person) get (info,show) <userId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-people-me.md b/docs/commands/gog-people-me.md
index f4a74525a..c638948be 100644
--- a/docs/commands/gog-people-me.md
+++ b/docs/commands/gog-people-me.md
@@ -33,6 +33,7 @@ gog people (person) me
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-people-raw.md b/docs/commands/gog-people-raw.md
index 6e9412dd6..b0fc2c7f8 100644
--- a/docs/commands/gog-people-raw.md
+++ b/docs/commands/gog-people-raw.md
@@ -35,6 +35,7 @@ gog people (person) raw <userId> [flags]
 | `--person-fields` | `string` |  | People API personFields mask (default: broad set; pass a narrower list to reduce output) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
+| `--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 |
diff --git a/docs/commands/gog-people-relations.md b/docs/commands/gog-people-relations.md
index 1df13e5b3..23f0b030d 100644
--- a/docs/commands/gog-people-relations.md
+++ b/docs/commands/gog-people-relations.md
@@ -33,6 +33,7 @@ gog people (person) relations [<userId>] [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--type` | `string` |  | Filter relation type |
diff --git a/docs/commands/gog-people-search.md b/docs/commands/gog-people-search.md
index 294baf5fa..be713f43b 100644
--- a/docs/commands/gog-people-search.md
+++ b/docs/commands/gog-people-search.md
@@ -37,6 +37,7 @@ gog people (person) search (find,query) <query> ... [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-people.md b/docs/commands/gog-people.md
index b21680e76..d1c00e0f8 100644
--- a/docs/commands/gog-people.md
+++ b/docs/commands/gog-people.md
@@ -41,6 +41,7 @@ gog people (person) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-photos-download.md b/docs/commands/gog-photos-download.md
index 0c0b9022c..dfda5c556 100644
--- a/docs/commands/gog-photos-download.md
+++ b/docs/commands/gog-photos-download.md
@@ -35,6 +35,7 @@ gog photos (photo) download (dl) <mediaItemId> [flags]
 | `--out` | `string` |  | Output path, directory, or '-' for stdout |
 | `--overwrite` | `bool` |  | Overwrite an existing output file |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-photos-get.md b/docs/commands/gog-photos-get.md
index a3fb195f9..84680b65c 100644
--- a/docs/commands/gog-photos-get.md
+++ b/docs/commands/gog-photos-get.md
@@ -33,6 +33,7 @@ gog photos (photo) get (info,show) <mediaItemId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-photos-list.md b/docs/commands/gog-photos-list.md
index 8d035aff4..28490fb0a 100644
--- a/docs/commands/gog-photos-list.md
+++ b/docs/commands/gog-photos-list.md
@@ -35,6 +35,7 @@ gog photos (photo) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-photos-picker-create.md b/docs/commands/gog-photos-picker-create.md
index b12e52e04..4b2b8cc9b 100644
--- a/docs/commands/gog-photos-picker-create.md
+++ b/docs/commands/gog-photos-picker-create.md
@@ -35,6 +35,7 @@ gog photos (photo) picker create (new,start) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--open`<br>`--browser` | `bool` |  | Open the Picker URI in the default browser |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-photos-picker-delete.md b/docs/commands/gog-photos-picker-delete.md
index 25ac36ca8..70ceaa3f3 100644
--- a/docs/commands/gog-photos-picker-delete.md
+++ b/docs/commands/gog-photos-picker-delete.md
@@ -33,6 +33,7 @@ gog photos (photo) picker delete (rm,close) <sessionId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-photos-picker-download.md b/docs/commands/gog-photos-picker-download.md
index 34dafd20d..599dfcdd9 100644
--- a/docs/commands/gog-photos-picker-download.md
+++ b/docs/commands/gog-photos-picker-download.md
@@ -35,6 +35,7 @@ gog photos (photo) picker download (dl) <sessionId> <mediaItemId> [flags]
 | `--out` | `string` |  | Output path, directory, or '-' for stdout |
 | `--overwrite` | `bool` |  | Overwrite an existing output file |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-photos-picker-get.md b/docs/commands/gog-photos-picker-get.md
index 23224b786..85d0ca9fe 100644
--- a/docs/commands/gog-photos-picker-get.md
+++ b/docs/commands/gog-photos-picker-get.md
@@ -33,6 +33,7 @@ gog photos (photo) picker get (info,show) <sessionId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-photos-picker-list.md b/docs/commands/gog-photos-picker-list.md
index 76a6d0548..d933afa2b 100644
--- a/docs/commands/gog-photos-picker-list.md
+++ b/docs/commands/gog-photos-picker-list.md
@@ -36,6 +36,7 @@ gog photos (photo) picker list (ls,items) <sessionId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-photos-picker-wait.md b/docs/commands/gog-photos-picker-wait.md
index 2b116153a..fa4d325ba 100644
--- a/docs/commands/gog-photos-picker-wait.md
+++ b/docs/commands/gog-photos-picker-wait.md
@@ -33,6 +33,7 @@ gog photos (photo) picker wait (poll) <sessionId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--timeout` | `time.Duration` | 0s | Maximum local wait; 0 uses the API-provided timeout |
diff --git a/docs/commands/gog-photos-picker.md b/docs/commands/gog-photos-picker.md
index d063893d4..45e862525 100644
--- a/docs/commands/gog-photos-picker.md
+++ b/docs/commands/gog-photos-picker.md
@@ -42,6 +42,7 @@ gog photos (photo) picker <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-photos-search.md b/docs/commands/gog-photos-search.md
index 293afae6b..afa491393 100644
--- a/docs/commands/gog-photos-search.md
+++ b/docs/commands/gog-photos-search.md
@@ -40,6 +40,7 @@ gog photos (photo) search (find) [flags]
 | `--order` | `string` | desc | Creation time order: desc\|asc |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--to` | `string` |  | End date YYYY-MM-DD |
diff --git a/docs/commands/gog-photos.md b/docs/commands/gog-photos.md
index d01f86646..489f51a12 100644
--- a/docs/commands/gog-photos.md
+++ b/docs/commands/gog-photos.md
@@ -41,6 +41,7 @@ gog photos (photo) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-schema.md b/docs/commands/gog-schema.md
index dab890151..d02a199c3 100644
--- a/docs/commands/gog-schema.md
+++ b/docs/commands/gog-schema.md
@@ -34,6 +34,7 @@ gog schema (help-json,helpjson) [<command> ...] [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-search.md b/docs/commands/gog-search.md
index c9de6d161..18528eb09 100644
--- a/docs/commands/gog-search.md
+++ b/docs/commands/gog-search.md
@@ -39,6 +39,7 @@ gog search (find) <query> ... [flags]
 | `--parent` | `string` |  | Scope search to direct children of a specific folder or shared drive. Wraps the query with "'<parentId>' in parents". |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--raw-query`<br>`--raw` | `bool` |  | Treat query as Drive query language (pass through; may error if invalid) |
+| `--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 |
diff --git a/docs/commands/gog-searchconsole-query.md b/docs/commands/gog-searchconsole-query.md
index 6c6c4c921..763bc54b3 100644
--- a/docs/commands/gog-searchconsole-query.md
+++ b/docs/commands/gog-searchconsole-query.md
@@ -41,6 +41,7 @@ gog searchconsole (gsc,search-console,webmasters) query (report) <siteUrl> [flag
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--offset`<br>`--start-row` | `int64` | 0 | Row offset for pagination |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--request` | `string` |  | SearchAnalyticsQueryRequest JSON spec. Accepts @file, a plain file path, -, or inline JSON. |
 | `--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. |
diff --git a/docs/commands/gog-searchconsole-searchanalytics-query.md b/docs/commands/gog-searchconsole-searchanalytics-query.md
index 2dc55e327..6dd735199 100644
--- a/docs/commands/gog-searchconsole-searchanalytics-query.md
+++ b/docs/commands/gog-searchconsole-searchanalytics-query.md
@@ -41,6 +41,7 @@ gog searchconsole (gsc,search-console,webmasters) searchanalytics (analytics) qu
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--offset`<br>`--start-row` | `int64` | 0 | Row offset for pagination |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--request` | `string` |  | SearchAnalyticsQueryRequest JSON spec. Accepts @file, a plain file path, -, or inline JSON. |
 | `--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. |
diff --git a/docs/commands/gog-searchconsole-searchanalytics.md b/docs/commands/gog-searchconsole-searchanalytics.md
index cfaaa59d4..3736a8ee6 100644
--- a/docs/commands/gog-searchconsole-searchanalytics.md
+++ b/docs/commands/gog-searchconsole-searchanalytics.md
@@ -37,6 +37,7 @@ gog searchconsole (gsc,search-console,webmasters) searchanalytics (analytics) <c
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-searchconsole-sitemaps-delete.md b/docs/commands/gog-searchconsole-sitemaps-delete.md
index 6b3c24c4c..7b1246931 100644
--- a/docs/commands/gog-searchconsole-sitemaps-delete.md
+++ b/docs/commands/gog-searchconsole-sitemaps-delete.md
@@ -33,6 +33,7 @@ gog searchconsole (gsc,search-console,webmasters) sitemaps delete (rm,remove) <s
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-searchconsole-sitemaps-get.md b/docs/commands/gog-searchconsole-sitemaps-get.md
index f3e9133d0..55f675b50 100644
--- a/docs/commands/gog-searchconsole-sitemaps-get.md
+++ b/docs/commands/gog-searchconsole-sitemaps-get.md
@@ -33,6 +33,7 @@ gog searchconsole (gsc,search-console,webmasters) sitemaps get (info,show) <site
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-searchconsole-sitemaps-list.md b/docs/commands/gog-searchconsole-sitemaps-list.md
index 4629a5ff8..e4fe7493f 100644
--- a/docs/commands/gog-searchconsole-sitemaps-list.md
+++ b/docs/commands/gog-searchconsole-sitemaps-list.md
@@ -34,6 +34,7 @@ gog searchconsole (gsc,search-console,webmasters) sitemaps list (ls) <siteUrl> [
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--sitemap-index` | `string` |  | Filter to a sitemap index URL |
diff --git a/docs/commands/gog-searchconsole-sitemaps-submit.md b/docs/commands/gog-searchconsole-sitemaps-submit.md
index 2309c4e24..ce96db4e1 100644
--- a/docs/commands/gog-searchconsole-sitemaps-submit.md
+++ b/docs/commands/gog-searchconsole-sitemaps-submit.md
@@ -33,6 +33,7 @@ gog searchconsole (gsc,search-console,webmasters) sitemaps submit <siteUrl> <fee
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-searchconsole-sitemaps.md b/docs/commands/gog-searchconsole-sitemaps.md
index c41397ef4..701f62e75 100644
--- a/docs/commands/gog-searchconsole-sitemaps.md
+++ b/docs/commands/gog-searchconsole-sitemaps.md
@@ -40,6 +40,7 @@ gog searchconsole (gsc,search-console,webmasters) sitemaps <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-searchconsole-sites-get.md b/docs/commands/gog-searchconsole-sites-get.md
index 4230e8ff6..9b56ba01e 100644
--- a/docs/commands/gog-searchconsole-sites-get.md
+++ b/docs/commands/gog-searchconsole-sites-get.md
@@ -33,6 +33,7 @@ gog searchconsole (gsc,search-console,webmasters) sites (list,ls) get (info,show
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-searchconsole-sites-list.md b/docs/commands/gog-searchconsole-sites-list.md
index 36a143fd0..8dd583187 100644
--- a/docs/commands/gog-searchconsole-sites-list.md
+++ b/docs/commands/gog-searchconsole-sites-list.md
@@ -34,6 +34,7 @@ gog searchconsole (gsc,search-console,webmasters) sites (list,ls) list (ls) [fla
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-searchconsole-sites.md b/docs/commands/gog-searchconsole-sites.md
index 2d16175b9..50e5b6761 100644
--- a/docs/commands/gog-searchconsole-sites.md
+++ b/docs/commands/gog-searchconsole-sites.md
@@ -38,6 +38,7 @@ gog searchconsole (gsc,search-console,webmasters) sites (list,ls) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-searchconsole.md b/docs/commands/gog-searchconsole.md
index 2ca5d8a30..eaa055979 100644
--- a/docs/commands/gog-searchconsole.md
+++ b/docs/commands/gog-searchconsole.md
@@ -40,6 +40,7 @@ gog searchconsole (gsc,search-console,webmasters) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-send.md b/docs/commands/gog-send.md
index 56b62559f..a0abdaac6 100644
--- a/docs/commands/gog-send.md
+++ b/docs/commands/gog-send.md
@@ -42,6 +42,7 @@ gog send [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--quote` | `bool` |  | Include quoted original message in reply (requires --reply-to-message-id or --thread-id) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--reply-all` | `bool` |  | Auto-populate recipients from original message (requires --reply-to-message-id or --thread-id) |
 | `--reply-to` | `string` |  | Reply-To header address |
 | `--reply-to-message-id`<br>`--in-reply-to` | `string` |  | Reply to Gmail message ID (sets In-Reply-To/References and thread) |
diff --git a/docs/commands/gog-sheets-add-tab.md b/docs/commands/gog-sheets-add-tab.md
index af90cbf0c..fe5f31c9b 100644
--- a/docs/commands/gog-sheets-add-tab.md
+++ b/docs/commands/gog-sheets-add-tab.md
@@ -34,6 +34,7 @@ gog sheets (sheet) add-tab (add-sheet) <spreadsheetId> <tabName> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-append.md b/docs/commands/gog-sheets-append.md
index 6a2e57729..8739c9a64 100644
--- a/docs/commands/gog-sheets-append.md
+++ b/docs/commands/gog-sheets-append.md
@@ -36,6 +36,7 @@ gog sheets (sheet) append (add) <spreadsheetId> <range> [<values> ...] [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--values-json` | `string` |  | Values as JSON 2D array |
diff --git a/docs/commands/gog-sheets-banding-clear.md b/docs/commands/gog-sheets-banding-clear.md
index fba91cb6e..12ea6b1d9 100644
--- a/docs/commands/gog-sheets-banding-clear.md
+++ b/docs/commands/gog-sheets-banding-clear.md
@@ -35,6 +35,7 @@ gog sheets (sheet) banding (banded-ranges) clear (delete,rm,remove) <spreadsheet
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--sheet` | `string` |  | Sheet name for --all |
diff --git a/docs/commands/gog-sheets-banding-list.md b/docs/commands/gog-sheets-banding-list.md
index 576a277e1..e7f9424f3 100644
--- a/docs/commands/gog-sheets-banding-list.md
+++ b/docs/commands/gog-sheets-banding-list.md
@@ -33,6 +33,7 @@ gog sheets (sheet) banding (banded-ranges) list <spreadsheetId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--sheet` | `string` |  | Only list banding from this sheet |
diff --git a/docs/commands/gog-sheets-banding-set.md b/docs/commands/gog-sheets-banding-set.md
index 5daa1d288..e7fb5e524 100644
--- a/docs/commands/gog-sheets-banding-set.md
+++ b/docs/commands/gog-sheets-banding-set.md
@@ -34,6 +34,7 @@ gog sheets (sheet) banding (banded-ranges) set (add,create) <spreadsheetId> <ran
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--row-properties-json` | `string` |  | Sheets API BandingProperties JSON for row colors |
 | `--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. |
diff --git a/docs/commands/gog-sheets-banding.md b/docs/commands/gog-sheets-banding.md
index cda9829eb..632e38715 100644
--- a/docs/commands/gog-sheets-banding.md
+++ b/docs/commands/gog-sheets-banding.md
@@ -39,6 +39,7 @@ gog sheets (sheet) banding (banded-ranges) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-batch-update.md b/docs/commands/gog-sheets-batch-update.md
index a29d4aeb8..5ba3806cc 100644
--- a/docs/commands/gog-sheets-batch-update.md
+++ b/docs/commands/gog-sheets-batch-update.md
@@ -36,6 +36,7 @@ gog sheets (sheet) batch-update (batch) --data-json=STRING <spreadsheetId> [flag
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--response-date-time-render` | `string` |  | Response date/time render option: SERIAL_NUMBER or FORMATTED_STRING |
 | `--response-render` | `string` |  | Response value render option: FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
diff --git a/docs/commands/gog-sheets-chart-create.md b/docs/commands/gog-sheets-chart-create.md
index d461336f1..eb9e31360 100644
--- a/docs/commands/gog-sheets-chart-create.md
+++ b/docs/commands/gog-sheets-chart-create.md
@@ -35,6 +35,7 @@ gog sheets (sheet) chart (charts) create (add,new) --spec-json=STRING <spreadshe
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--sheet` | `string` |  | Sheet name for anchor (resolved to sheetId) |
diff --git a/docs/commands/gog-sheets-chart-delete.md b/docs/commands/gog-sheets-chart-delete.md
index aa3e779e6..41d6500fa 100644
--- a/docs/commands/gog-sheets-chart-delete.md
+++ b/docs/commands/gog-sheets-chart-delete.md
@@ -33,6 +33,7 @@ gog sheets (sheet) chart (charts) delete (rm,remove,del) <spreadsheetId> <chartI
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-chart-get.md b/docs/commands/gog-sheets-chart-get.md
index 2d4da1a8c..d2dfc73df 100644
--- a/docs/commands/gog-sheets-chart-get.md
+++ b/docs/commands/gog-sheets-chart-get.md
@@ -33,6 +33,7 @@ gog sheets (sheet) chart (charts) get (show,info) <spreadsheetId> <chartId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-chart-list.md b/docs/commands/gog-sheets-chart-list.md
index a64cba1c2..0cec50199 100644
--- a/docs/commands/gog-sheets-chart-list.md
+++ b/docs/commands/gog-sheets-chart-list.md
@@ -33,6 +33,7 @@ gog sheets (sheet) chart (charts) list <spreadsheetId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-chart-update.md b/docs/commands/gog-sheets-chart-update.md
index 79ff6eba0..800f03df4 100644
--- a/docs/commands/gog-sheets-chart-update.md
+++ b/docs/commands/gog-sheets-chart-update.md
@@ -33,6 +33,7 @@ gog sheets (sheet) chart (charts) update (edit,set) --spec-json=STRING <spreadsh
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--spec-json` | `string` |  | ChartSpec or EmbeddedChart JSON (inline or @file) |
diff --git a/docs/commands/gog-sheets-chart.md b/docs/commands/gog-sheets-chart.md
index 9477a5ddc..72df1384c 100644
--- a/docs/commands/gog-sheets-chart.md
+++ b/docs/commands/gog-sheets-chart.md
@@ -41,6 +41,7 @@ gog sheets (sheet) chart (charts) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-clear.md b/docs/commands/gog-sheets-clear.md
index a77d758b8..04340d697 100644
--- a/docs/commands/gog-sheets-clear.md
+++ b/docs/commands/gog-sheets-clear.md
@@ -33,6 +33,7 @@ gog sheets (sheet) clear <spreadsheetId> <range>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-conditional-format-add.md b/docs/commands/gog-sheets-conditional-format-add.md
index 511e6f65e..fb4e37ff6 100644
--- a/docs/commands/gog-sheets-conditional-format-add.md
+++ b/docs/commands/gog-sheets-conditional-format-add.md
@@ -37,6 +37,7 @@ gog sheets (sheet) conditional-format (cf,conditional-formats) add (create,new)
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--type` | `string` |  | Rule type: text-eq\|text-contains\|text-starts-with\|text-ends-with\|number-eq\|number-gt\|number-gte\|number-lt\|number-lte\|blank\|not-blank\|custom-formula |
diff --git a/docs/commands/gog-sheets-conditional-format-clear.md b/docs/commands/gog-sheets-conditional-format-clear.md
index 0d9264880..493f8ccbc 100644
--- a/docs/commands/gog-sheets-conditional-format-clear.md
+++ b/docs/commands/gog-sheets-conditional-format-clear.md
@@ -35,6 +35,7 @@ gog sheets (sheet) conditional-format (cf,conditional-formats) clear (delete,rm,
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--sheet` | `string` |  | Sheet name |
diff --git a/docs/commands/gog-sheets-conditional-format-list.md b/docs/commands/gog-sheets-conditional-format-list.md
index aaf0309b0..8ca293b45 100644
--- a/docs/commands/gog-sheets-conditional-format-list.md
+++ b/docs/commands/gog-sheets-conditional-format-list.md
@@ -33,6 +33,7 @@ gog sheets (sheet) conditional-format (cf,conditional-formats) list <spreadsheet
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--sheet` | `string` |  | Only list rules from this sheet |
diff --git a/docs/commands/gog-sheets-conditional-format.md b/docs/commands/gog-sheets-conditional-format.md
index 6593e4482..78fddf8c8 100644
--- a/docs/commands/gog-sheets-conditional-format.md
+++ b/docs/commands/gog-sheets-conditional-format.md
@@ -39,6 +39,7 @@ gog sheets (sheet) conditional-format (cf,conditional-formats) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-copy-paste.md b/docs/commands/gog-sheets-copy-paste.md
index 2bf252cbc..6cd124d55 100644
--- a/docs/commands/gog-sheets-copy-paste.md
+++ b/docs/commands/gog-sheets-copy-paste.md
@@ -33,6 +33,7 @@ gog sheets (sheet) copy-paste (fill,copy-range) <spreadsheetId> <source> <dest>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--transpose` | `bool` |  | Paste transposed (swap rows and columns) |
diff --git a/docs/commands/gog-sheets-copy.md b/docs/commands/gog-sheets-copy.md
index 71c5355e4..a8424bc61 100644
--- a/docs/commands/gog-sheets-copy.md
+++ b/docs/commands/gog-sheets-copy.md
@@ -34,6 +34,7 @@ gog sheets (sheet) copy (cp,duplicate) <spreadsheetId> <title> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Destination folder ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-create.md b/docs/commands/gog-sheets-create.md
index 07e0ee137..b358e358c 100644
--- a/docs/commands/gog-sheets-create.md
+++ b/docs/commands/gog-sheets-create.md
@@ -34,6 +34,7 @@ gog sheets (sheet) create (new) <title> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Destination folder ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--sheets` | `string` |  | Comma-separated sheet names to create |
diff --git a/docs/commands/gog-sheets-delete-dimension.md b/docs/commands/gog-sheets-delete-dimension.md
index 1e9748494..aa2c14d5a 100644
--- a/docs/commands/gog-sheets-delete-dimension.md
+++ b/docs/commands/gog-sheets-delete-dimension.md
@@ -35,6 +35,7 @@ gog sheets (sheet) delete-dimension (delete-dim) --dimension=STRING <spreadsheet
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--start` | `int64` |  | First row/column to delete (1-based, inclusive; required with a sheet target) |
diff --git a/docs/commands/gog-sheets-delete-tab.md b/docs/commands/gog-sheets-delete-tab.md
index 2fa6d01f7..7ceeedf25 100644
--- a/docs/commands/gog-sheets-delete-tab.md
+++ b/docs/commands/gog-sheets-delete-tab.md
@@ -33,6 +33,7 @@ gog sheets (sheet) delete-tab (delete-sheet) <spreadsheetId> <tabName>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-export.md b/docs/commands/gog-sheets-export.md
index a27a23ca6..c376a4fd0 100644
--- a/docs/commands/gog-sheets-export.md
+++ b/docs/commands/gog-sheets-export.md
@@ -36,6 +36,7 @@ gog sheets (sheet) export (download,dl) <spreadsheetId> [flags]
 | `--out`<br>`--output` | `string` |  | Output file path (default: gogcli config dir) |
 | `--overwrite` | `bool` |  | Overwrite an existing output file |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-find-replace.md b/docs/commands/gog-sheets-find-replace.md
index 71e454f23..eca74d914 100644
--- a/docs/commands/gog-sheets-find-replace.md
+++ b/docs/commands/gog-sheets-find-replace.md
@@ -36,6 +36,7 @@ gog sheets (sheet) find-replace <spreadsheetId> <find> <replace> [flags]
 | `--match-entire`<br>`--exact` | `bool` |  | Match entire cell value |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--regex` | `bool` |  | Treat find text as a regex |
 | `--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. |
diff --git a/docs/commands/gog-sheets-format.md b/docs/commands/gog-sheets-format.md
index cc15dd96d..fe0822583 100644
--- a/docs/commands/gog-sheets-format.md
+++ b/docs/commands/gog-sheets-format.md
@@ -35,6 +35,7 @@ gog sheets (sheet) format <spreadsheetId> <range> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-freeze.md b/docs/commands/gog-sheets-freeze.md
index 6b7465eb3..076cdda8a 100644
--- a/docs/commands/gog-sheets-freeze.md
+++ b/docs/commands/gog-sheets-freeze.md
@@ -34,6 +34,7 @@ gog sheets (sheet) freeze <spreadsheetId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--rows` | `int64` | -1 | Number of rows to freeze (0 to unfreeze) |
 | `--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. |
diff --git a/docs/commands/gog-sheets-get.md b/docs/commands/gog-sheets-get.md
index 6a07cf7f7..219f66f87 100644
--- a/docs/commands/gog-sheets-get.md
+++ b/docs/commands/gog-sheets-get.md
@@ -34,6 +34,7 @@ gog sheets (sheet) get (read,show) <spreadsheetId> <range> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--render` | `string` |  | Value render option: FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA |
 | `--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. |
diff --git a/docs/commands/gog-sheets-insert.md b/docs/commands/gog-sheets-insert.md
index 5ce61b23d..cd3da59c7 100644
--- a/docs/commands/gog-sheets-insert.md
+++ b/docs/commands/gog-sheets-insert.md
@@ -36,6 +36,7 @@ gog sheets (sheet) insert <spreadsheetId> <sheet> <dimension> <start> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-links-get.md b/docs/commands/gog-sheets-links-get.md
index 68a46488c..44b1eca64 100644
--- a/docs/commands/gog-sheets-links-get.md
+++ b/docs/commands/gog-sheets-links-get.md
@@ -33,6 +33,7 @@ gog sheets (sheet) links (hyperlinks) get (list,show) <spreadsheetId> <range>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-links-set.md b/docs/commands/gog-sheets-links-set.md
index 4c45f5ce3..5ff81ebd4 100644
--- a/docs/commands/gog-sheets-links-set.md
+++ b/docs/commands/gog-sheets-links-set.md
@@ -34,6 +34,7 @@ gog sheets (sheet) links (hyperlinks) set (write) <spreadsheetId> [<cell> [<url>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--runs-json` | `string` |  | Multi-link cell: JSON array of runs, eg. [{"text":"Act A","uri":"https://a"},{"text":" / "},{"text":"Act B","uri":"https://b"}]. A run with an empty uri is plain text. |
 | `--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. |
diff --git a/docs/commands/gog-sheets-links.md b/docs/commands/gog-sheets-links.md
index 19769f1b9..b74f78329 100644
--- a/docs/commands/gog-sheets-links.md
+++ b/docs/commands/gog-sheets-links.md
@@ -38,6 +38,7 @@ gog sheets (sheet) links (hyperlinks) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-merge.md b/docs/commands/gog-sheets-merge.md
index 4fb1fc57e..e25bd7b2a 100644
--- a/docs/commands/gog-sheets-merge.md
+++ b/docs/commands/gog-sheets-merge.md
@@ -33,6 +33,7 @@ gog sheets (sheet) merge <spreadsheetId> <range> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--type` | `string` | MERGE_ALL | Merge type: MERGE_ALL, MERGE_COLUMNS, MERGE_ROWS |
diff --git a/docs/commands/gog-sheets-metadata.md b/docs/commands/gog-sheets-metadata.md
index 20e9740ff..398437b31 100644
--- a/docs/commands/gog-sheets-metadata.md
+++ b/docs/commands/gog-sheets-metadata.md
@@ -33,6 +33,7 @@ gog sheets (sheet) metadata (info) <spreadsheetId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-named-ranges-add.md b/docs/commands/gog-sheets-named-ranges-add.md
index 64b29399c..731f1ee23 100644
--- a/docs/commands/gog-sheets-named-ranges-add.md
+++ b/docs/commands/gog-sheets-named-ranges-add.md
@@ -33,6 +33,7 @@ gog sheets (sheet) named-ranges (namedranges,nr) add (create,new) <spreadsheetId
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-named-ranges-delete.md b/docs/commands/gog-sheets-named-ranges-delete.md
index a5048beca..1870a24c0 100644
--- a/docs/commands/gog-sheets-named-ranges-delete.md
+++ b/docs/commands/gog-sheets-named-ranges-delete.md
@@ -33,6 +33,7 @@ gog sheets (sheet) named-ranges (namedranges,nr) delete (rm,remove,del) <spreads
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-named-ranges-get.md b/docs/commands/gog-sheets-named-ranges-get.md
index d9c3005ff..bf070cef0 100644
--- a/docs/commands/gog-sheets-named-ranges-get.md
+++ b/docs/commands/gog-sheets-named-ranges-get.md
@@ -33,6 +33,7 @@ gog sheets (sheet) named-ranges (namedranges,nr) get (show,info) <spreadsheetId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-named-ranges-list.md b/docs/commands/gog-sheets-named-ranges-list.md
index 2d1b97002..516c5cc1b 100644
--- a/docs/commands/gog-sheets-named-ranges-list.md
+++ b/docs/commands/gog-sheets-named-ranges-list.md
@@ -33,6 +33,7 @@ gog sheets (sheet) named-ranges (namedranges,nr) list <spreadsheetId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-named-ranges-update.md b/docs/commands/gog-sheets-named-ranges-update.md
index c701b7248..8ac94d326 100644
--- a/docs/commands/gog-sheets-named-ranges-update.md
+++ b/docs/commands/gog-sheets-named-ranges-update.md
@@ -35,6 +35,7 @@ gog sheets (sheet) named-ranges (namedranges,nr) update (edit,set) <spreadsheetI
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--range` | `string` |  | New A1 range (must include sheet name; e.g. Sheet1!A1:B2 or Sheet1!A:C) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-named-ranges.md b/docs/commands/gog-sheets-named-ranges.md
index 7ac8a50e9..f8369f405 100644
--- a/docs/commands/gog-sheets-named-ranges.md
+++ b/docs/commands/gog-sheets-named-ranges.md
@@ -41,6 +41,7 @@ gog sheets (sheet) named-ranges (namedranges,nr) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-notes.md b/docs/commands/gog-sheets-notes.md
index 71f155b9e..2cb118cf1 100644
--- a/docs/commands/gog-sheets-notes.md
+++ b/docs/commands/gog-sheets-notes.md
@@ -33,6 +33,7 @@ gog sheets (sheet) notes <spreadsheetId> <range>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-number-format.md b/docs/commands/gog-sheets-number-format.md
index 974f5a33a..f11711ce3 100644
--- a/docs/commands/gog-sheets-number-format.md
+++ b/docs/commands/gog-sheets-number-format.md
@@ -34,6 +34,7 @@ gog sheets (sheet) number-format <spreadsheetId> <range> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--pattern` | `string` |  | Custom number format pattern (eg. $#,##0.00 or yyyy-mm-dd) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--type` | `string` | NUMBER | Number format type: NUMBER, CURRENCY, PERCENT, DATE, TIME, DATE_TIME, SCIENTIFIC, TEXT |
diff --git a/docs/commands/gog-sheets-raw.md b/docs/commands/gog-sheets-raw.md
index 7383d7898..30d1f5ca9 100644
--- a/docs/commands/gog-sheets-raw.md
+++ b/docs/commands/gog-sheets-raw.md
@@ -35,6 +35,7 @@ gog sheets (sheet) raw <spreadsheetId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-read-format.md b/docs/commands/gog-sheets-read-format.md
index a3cd5afaa..9b57c4203 100644
--- a/docs/commands/gog-sheets-read-format.md
+++ b/docs/commands/gog-sheets-read-format.md
@@ -34,6 +34,7 @@ gog sheets (sheet) read-format (get-format,format-read) <spreadsheetId> <range>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-rename-tab.md b/docs/commands/gog-sheets-rename-tab.md
index f5ce12f5f..ada405321 100644
--- a/docs/commands/gog-sheets-rename-tab.md
+++ b/docs/commands/gog-sheets-rename-tab.md
@@ -33,6 +33,7 @@ gog sheets (sheet) rename-tab (rename-sheet) <spreadsheetId> <oldName> <newName>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-reorder-tab.md b/docs/commands/gog-sheets-reorder-tab.md
index 9c8e03b3a..21726cf01 100644
--- a/docs/commands/gog-sheets-reorder-tab.md
+++ b/docs/commands/gog-sheets-reorder-tab.md
@@ -33,6 +33,7 @@ gog sheets (sheet) reorder-tab (move-tab,reorder-sheet,move-sheet) --tab=STRING
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--tab` | `string` |  | Target tab by name or numeric sheet ID (see sheets metadata) |
diff --git a/docs/commands/gog-sheets-resize-columns.md b/docs/commands/gog-sheets-resize-columns.md
index 912e34c8a..073c85e97 100644
--- a/docs/commands/gog-sheets-resize-columns.md
+++ b/docs/commands/gog-sheets-resize-columns.md
@@ -34,6 +34,7 @@ gog sheets (sheet) resize-columns <spreadsheetId> <columns> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-resize-rows.md b/docs/commands/gog-sheets-resize-rows.md
index 4b12b0ddf..1cb49d0bb 100644
--- a/docs/commands/gog-sheets-resize-rows.md
+++ b/docs/commands/gog-sheets-resize-rows.md
@@ -35,6 +35,7 @@ gog sheets (sheet) resize-rows <spreadsheetId> <rows> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-table-append.md b/docs/commands/gog-sheets-table-append.md
index ba626264c..77259fe6d 100644
--- a/docs/commands/gog-sheets-table-append.md
+++ b/docs/commands/gog-sheets-table-append.md
@@ -34,6 +34,7 @@ gog sheets (sheet) table (tables) append (add-row,add-rows) <spreadsheetId> <tab
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--values-json` | `string` |  | Values as JSON 2D array |
diff --git a/docs/commands/gog-sheets-table-clear.md b/docs/commands/gog-sheets-table-clear.md
index 9a4a71406..5106189c2 100644
--- a/docs/commands/gog-sheets-table-clear.md
+++ b/docs/commands/gog-sheets-table-clear.md
@@ -33,6 +33,7 @@ gog sheets (sheet) table (tables) clear (clear-rows) <spreadsheetId> <tableId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-table-create.md b/docs/commands/gog-sheets-table-create.md
index 9fbc6c855..44abbde53 100644
--- a/docs/commands/gog-sheets-table-create.md
+++ b/docs/commands/gog-sheets-table-create.md
@@ -35,6 +35,7 @@ gog sheets (sheet) table (tables) create (add,new) --name=STRING --columns-json=
 | `--name` | `string` |  | Table name |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-table-delete.md b/docs/commands/gog-sheets-table-delete.md
index 8439a77ec..f3214ac94 100644
--- a/docs/commands/gog-sheets-table-delete.md
+++ b/docs/commands/gog-sheets-table-delete.md
@@ -34,6 +34,7 @@ gog sheets (sheet) table (tables) delete (rm,remove,del) <spreadsheetId> <tableI
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-table-get.md b/docs/commands/gog-sheets-table-get.md
index 60aed5431..f840055f5 100644
--- a/docs/commands/gog-sheets-table-get.md
+++ b/docs/commands/gog-sheets-table-get.md
@@ -33,6 +33,7 @@ gog sheets (sheet) table (tables) get (show,info) <spreadsheetId> <tableId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-table-list.md b/docs/commands/gog-sheets-table-list.md
index 6e4e5c254..4ef2eb2ee 100644
--- a/docs/commands/gog-sheets-table-list.md
+++ b/docs/commands/gog-sheets-table-list.md
@@ -33,6 +33,7 @@ gog sheets (sheet) table (tables) list <spreadsheetId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-table.md b/docs/commands/gog-sheets-table.md
index e8a61ff03..2e9261300 100644
--- a/docs/commands/gog-sheets-table.md
+++ b/docs/commands/gog-sheets-table.md
@@ -42,6 +42,7 @@ gog sheets (sheet) table (tables) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-unmerge.md b/docs/commands/gog-sheets-unmerge.md
index 6bfb3575c..b4599bb9c 100644
--- a/docs/commands/gog-sheets-unmerge.md
+++ b/docs/commands/gog-sheets-unmerge.md
@@ -33,6 +33,7 @@ gog sheets (sheet) unmerge <spreadsheetId> <range>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-update-note.md b/docs/commands/gog-sheets-update-note.md
index 764f3c9ea..2cb0d55c2 100644
--- a/docs/commands/gog-sheets-update-note.md
+++ b/docs/commands/gog-sheets-update-note.md
@@ -35,6 +35,7 @@ gog sheets (sheet) update-note (set-note) <spreadsheetId> <range> [flags]
 | `--note` | `*string` |  | Note text to set (use --note '' to clear notes) |
 | `--note-file` | `string` |  | Path to file containing note text |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-update.md b/docs/commands/gog-sheets-update.md
index c0b303419..de64743dc 100644
--- a/docs/commands/gog-sheets-update.md
+++ b/docs/commands/gog-sheets-update.md
@@ -36,6 +36,7 @@ gog sheets (sheet) update (edit,set) <spreadsheetId> <range> [<values> ...] [fla
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--values-json` | `string` |  | Values as a JSON 2D array, @file, or @- for stdin |
diff --git a/docs/commands/gog-sheets-validation-clear.md b/docs/commands/gog-sheets-validation-clear.md
index a40588b3c..9eba5357d 100644
--- a/docs/commands/gog-sheets-validation-clear.md
+++ b/docs/commands/gog-sheets-validation-clear.md
@@ -34,6 +34,7 @@ gog sheets (sheet) validation (data-validation,validations) clear (delete,remove
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-validation-get.md b/docs/commands/gog-sheets-validation-get.md
index 0aff450a8..ba3e74de5 100644
--- a/docs/commands/gog-sheets-validation-get.md
+++ b/docs/commands/gog-sheets-validation-get.md
@@ -33,6 +33,7 @@ gog sheets (sheet) validation (data-validation,validations) get (list,show) <spr
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets-validation-set.md b/docs/commands/gog-sheets-validation-set.md
index e2d2fa6a2..675e9623f 100644
--- a/docs/commands/gog-sheets-validation-set.md
+++ b/docs/commands/gog-sheets-validation-set.md
@@ -35,6 +35,7 @@ gog sheets (sheet) validation (data-validation,validations) set (add,create) --t
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--show-custom-ui` | `bool` | true | Show dropdown or checkbox UI where supported |
diff --git a/docs/commands/gog-sheets-validation.md b/docs/commands/gog-sheets-validation.md
index 934f17c8e..fb39dcbaa 100644
--- a/docs/commands/gog-sheets-validation.md
+++ b/docs/commands/gog-sheets-validation.md
@@ -39,6 +39,7 @@ gog sheets (sheet) validation (data-validation,validations) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sheets.md b/docs/commands/gog-sheets.md
index 2d08c84e3..3d746f7e5 100644
--- a/docs/commands/gog-sheets.md
+++ b/docs/commands/gog-sheets.md
@@ -71,6 +71,7 @@ gog sheets (sheet) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sites-get.md b/docs/commands/gog-sites-get.md
index 05d051243..a4193d804 100644
--- a/docs/commands/gog-sites-get.md
+++ b/docs/commands/gog-sites-get.md
@@ -34,6 +34,7 @@ gog sites (site) get (info,show) <siteId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sites-list.md b/docs/commands/gog-sites-list.md
index 0679c14e9..fcbe79adc 100644
--- a/docs/commands/gog-sites-list.md
+++ b/docs/commands/gog-sites-list.md
@@ -38,6 +38,7 @@ gog sites (site) list (ls) [flags]
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--query` | `string` |  | Additional Drive query filter |
+| `--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 |
diff --git a/docs/commands/gog-sites-search.md b/docs/commands/gog-sites-search.md
index f2a333fa3..1d717422f 100644
--- a/docs/commands/gog-sites-search.md
+++ b/docs/commands/gog-sites-search.md
@@ -38,6 +38,7 @@ gog sites (site) search (find) <query> ... [flags]
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--raw-query`<br>`--raw` | `bool` |  | Treat query as Drive query language (pass through; will still be constrained to Google Sites) |
+| `--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 |
diff --git a/docs/commands/gog-sites-url.md b/docs/commands/gog-sites-url.md
index 7d2376a95..e62d38fd9 100644
--- a/docs/commands/gog-sites-url.md
+++ b/docs/commands/gog-sites-url.md
@@ -33,6 +33,7 @@ gog sites (site) url (open) <siteId> ...
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-sites.md b/docs/commands/gog-sites.md
index 2f0726af6..aad9fa665 100644
--- a/docs/commands/gog-sites.md
+++ b/docs/commands/gog-sites.md
@@ -40,6 +40,7 @@ gog sites (site) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-add-slide.md b/docs/commands/gog-slides-add-slide.md
index 0fbaa392a..0cc36f52e 100644
--- a/docs/commands/gog-slides-add-slide.md
+++ b/docs/commands/gog-slides-add-slide.md
@@ -36,6 +36,7 @@ gog slides (slide) add-slide <presentationId> <image> [flags]
 | `--notes` | `string` |  | Speaker notes text |
 | `--notes-file` | `string` |  | Path to file containing speaker notes |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-bullets.md b/docs/commands/gog-slides-bullets.md
index dffe557c6..d2ec24c7d 100644
--- a/docs/commands/gog-slides-bullets.md
+++ b/docs/commands/gog-slides-bullets.md
@@ -37,6 +37,7 @@ gog slides (slide) bullets --range=STRING <presentationId> <objectId> [flags]
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--preset` | `string` | BULLET_DISC_CIRCLE_SQUARE | Slides bullet preset when using --on |
 | `--range` | `string` |  | UTF-16 paragraph range as start:end |
+| `--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 |
diff --git a/docs/commands/gog-slides-copy.md b/docs/commands/gog-slides-copy.md
index 648da166b..1b6dd22fa 100644
--- a/docs/commands/gog-slides-copy.md
+++ b/docs/commands/gog-slides-copy.md
@@ -34,6 +34,7 @@ gog slides (slide) copy (cp,duplicate) <presentationId> <title> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Destination folder ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-create-from-markdown.md b/docs/commands/gog-slides-create-from-markdown.md
index 88fffd168..160541b5d 100644
--- a/docs/commands/gog-slides-create-from-markdown.md
+++ b/docs/commands/gog-slides-create-from-markdown.md
@@ -41,6 +41,7 @@ gog slides (slide) create-from-markdown <title> [flags]
 | `--no-notes` | `bool` |  | Discard ## Notes sections instead of inserting as speaker notes |
 | `--parent` | `string` |  | Destination folder ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--strict` | `bool` |  | Treat skipped FA/diagram assets as fatal |
diff --git a/docs/commands/gog-slides-create-from-template.md b/docs/commands/gog-slides-create-from-template.md
index d1f9ef585..9dfd2870a 100644
--- a/docs/commands/gog-slides-create-from-template.md
+++ b/docs/commands/gog-slides-create-from-template.md
@@ -35,6 +35,7 @@ gog slides (slide) create-from-template <templateId> <title> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Destination folder ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--replace` | `[]string` |  | Text replacement in format 'key=value' (repeatable) |
 | `--replacements` | `string` |  | JSON file containing replacements |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
diff --git a/docs/commands/gog-slides-create.md b/docs/commands/gog-slides-create.md
index 7fd842090..2fb542076 100644
--- a/docs/commands/gog-slides-create.md
+++ b/docs/commands/gog-slides-create.md
@@ -34,6 +34,7 @@ gog slides (slide) create (add,new) <title> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Destination folder ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--template` | `string` |  | Template presentation ID to copy from |
diff --git a/docs/commands/gog-slides-delete-slide.md b/docs/commands/gog-slides-delete-slide.md
index 119d1eda0..9156a6bb5 100644
--- a/docs/commands/gog-slides-delete-slide.md
+++ b/docs/commands/gog-slides-delete-slide.md
@@ -33,6 +33,7 @@ gog slides (slide) delete-slide <presentationId> <slideId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-duplicate-slide.md b/docs/commands/gog-slides-duplicate-slide.md
index 53b682060..a66f7d9c0 100644
--- a/docs/commands/gog-slides-duplicate-slide.md
+++ b/docs/commands/gog-slides-duplicate-slide.md
@@ -33,6 +33,7 @@ gog slides (slide) duplicate-slide <presentationId> <slideId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--to-index` | `*int64` |  | Zero-based insertion index for the duplicated slide |
diff --git a/docs/commands/gog-slides-element-alt-text.md b/docs/commands/gog-slides-element-alt-text.md
index 52a950827..b537bbebf 100644
--- a/docs/commands/gog-slides-element-alt-text.md
+++ b/docs/commands/gog-slides-element-alt-text.md
@@ -34,6 +34,7 @@ gog slides (slide) element alt-text <presentationId> <objectId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--title` | `*string` |  | Accessibility title; pass an empty value to clear |
diff --git a/docs/commands/gog-slides-element-create-line.md b/docs/commands/gog-slides-element-create-line.md
index cb49699a9..bc2b8b289 100644
--- a/docs/commands/gog-slides-element-create-line.md
+++ b/docs/commands/gog-slides-element-create-line.md
@@ -36,6 +36,7 @@ gog slides (slide) element create-line <presentationId> <slideId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--object-id` | `string` |  | Optional stable object ID (5-50 allowed characters) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--unit` | `string` | PT | Geometry unit |
diff --git a/docs/commands/gog-slides-element-create-shape.md b/docs/commands/gog-slides-element-create-shape.md
index bdfe8086d..7f0aef981 100644
--- a/docs/commands/gog-slides-element-create-shape.md
+++ b/docs/commands/gog-slides-element-create-shape.md
@@ -35,6 +35,7 @@ gog slides (slide) element create-shape <presentationId> <slideId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--object-id` | `string` |  | Optional stable object ID (5-50 allowed characters) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--type` | `string` | RECTANGLE | Slides shape type (for example RECTANGLE, TEXT_BOX, ELLIPSE) |
diff --git a/docs/commands/gog-slides-element-delete.md b/docs/commands/gog-slides-element-delete.md
index fd9541e69..c201d931d 100644
--- a/docs/commands/gog-slides-element-delete.md
+++ b/docs/commands/gog-slides-element-delete.md
@@ -33,6 +33,7 @@ gog slides (slide) element delete (rm) <presentationId> <objectId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-element-group.md b/docs/commands/gog-slides-element-group.md
index c5b8dc33e..f1651d196 100644
--- a/docs/commands/gog-slides-element-group.md
+++ b/docs/commands/gog-slides-element-group.md
@@ -34,6 +34,7 @@ gog slides (slide) element group <presentationId> <objectId> ... [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-element-style.md b/docs/commands/gog-slides-element-style.md
index 689555dfb..337f8f0ec 100644
--- a/docs/commands/gog-slides-element-style.md
+++ b/docs/commands/gog-slides-element-style.md
@@ -40,6 +40,7 @@ gog slides (slide) element style <presentationId> <objectId> [flags]
 | `--outline-transparent` | `bool` |  | Remove the shape outline or make the line transparent |
 | `--outline-weight` | `*float64` |  | Shape outline or line weight in points |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-element-transform.md b/docs/commands/gog-slides-element-transform.md
index 15b639db0..f43e9c2f1 100644
--- a/docs/commands/gog-slides-element-transform.md
+++ b/docs/commands/gog-slides-element-transform.md
@@ -34,6 +34,7 @@ gog slides (slide) element transform (move,resize,rotate) <presentationId> <obje
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--rotate` | `*float64` |  | Clockwise rotation in degrees around the element origin |
 | `--scale-x` | `*float64` |  | X scale; omitted axis defaults to 1 |
diff --git a/docs/commands/gog-slides-element-ungroup.md b/docs/commands/gog-slides-element-ungroup.md
index 38d2063b9..bc5495ae5 100644
--- a/docs/commands/gog-slides-element-ungroup.md
+++ b/docs/commands/gog-slides-element-ungroup.md
@@ -33,6 +33,7 @@ gog slides (slide) element ungroup <presentationId> <groupId> ...
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-element-z-order.md b/docs/commands/gog-slides-element-z-order.md
index 095c78904..fd24585e5 100644
--- a/docs/commands/gog-slides-element-z-order.md
+++ b/docs/commands/gog-slides-element-z-order.md
@@ -34,6 +34,7 @@ gog slides (slide) element z-order --operation=STRING <presentationId> <objectId
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--operation` | `string` |  | Stacking operation |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-element.md b/docs/commands/gog-slides-element.md
index d2d8a43d7..53f3a8329 100644
--- a/docs/commands/gog-slides-element.md
+++ b/docs/commands/gog-slides-element.md
@@ -45,6 +45,7 @@ gog slides (slide) element <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-export.md b/docs/commands/gog-slides-export.md
index e722af9b8..c3b975a8f 100644
--- a/docs/commands/gog-slides-export.md
+++ b/docs/commands/gog-slides-export.md
@@ -36,6 +36,7 @@ gog slides (slide) export (download,dl) <presentationId> [flags]
 | `--out`<br>`--output` | `string` |  | Output file path (default: gogcli config dir) |
 | `--overwrite` | `bool` |  | Overwrite an existing output file |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-info.md b/docs/commands/gog-slides-info.md
index 23761d9b2..e79f9442f 100644
--- a/docs/commands/gog-slides-info.md
+++ b/docs/commands/gog-slides-info.md
@@ -33,6 +33,7 @@ gog slides (slide) info (get,show) <presentationId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-insert-image.md b/docs/commands/gog-slides-insert-image.md
index c08ec1959..f87019a14 100644
--- a/docs/commands/gog-slides-insert-image.md
+++ b/docs/commands/gog-slides-insert-image.md
@@ -34,6 +34,7 @@ gog slides (slide) insert-image --width=FLOAT-64 <presentationId> <slideId> [<im
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--unit` | `string` | PT | Measurement unit for x/y/width/height (PT or EMU) |
diff --git a/docs/commands/gog-slides-insert-text.md b/docs/commands/gog-slides-insert-text.md
index 9a2b763f3..f90d56656 100644
--- a/docs/commands/gog-slides-insert-text.md
+++ b/docs/commands/gog-slides-insert-text.md
@@ -35,6 +35,7 @@ gog slides (slide) insert-text <presentationId> <objectId> <text> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--replace` | `bool` |  | Clear existing text in the element before inserting (emits DeleteText + InsertText in the same batch) |
 | `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
 | `--row` | `*int64` |  | 0-based table row index for cell-targeted text; requires --col |
diff --git a/docs/commands/gog-slides-link.md b/docs/commands/gog-slides-link.md
index 88dfc5e31..400624732 100644
--- a/docs/commands/gog-slides-link.md
+++ b/docs/commands/gog-slides-link.md
@@ -35,6 +35,7 @@ gog slides (slide) link --range=STRING <presentationId> <objectId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--range` | `string` |  | UTF-16 text range as start:end |
+| `--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. |
 | `--url` | `string` |  | External URL to apply as the hyperlink |
diff --git a/docs/commands/gog-slides-list-slides.md b/docs/commands/gog-slides-list-slides.md
index 3a9d9a853..96ca1b8d1 100644
--- a/docs/commands/gog-slides-list-slides.md
+++ b/docs/commands/gog-slides-list-slides.md
@@ -33,6 +33,7 @@ gog slides (slide) list-slides <presentationId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-locate.md b/docs/commands/gog-slides-locate.md
index 1570163fb..f74bbfc90 100644
--- a/docs/commands/gog-slides-locate.md
+++ b/docs/commands/gog-slides-locate.md
@@ -38,6 +38,7 @@ gog slides (slide) locate (find-element) <presentationId> <text> [flags]
 | `--occurrence` | `*int` |  | Return the Nth occurrence (1-based; default first) |
 | `--page` | `string` |  | Limit matches to one slide object ID |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-move-slide.md b/docs/commands/gog-slides-move-slide.md
index d6cb0ef9e..81cefda18 100644
--- a/docs/commands/gog-slides-move-slide.md
+++ b/docs/commands/gog-slides-move-slide.md
@@ -33,6 +33,7 @@ gog slides (slide) move-slide --to-index=TO-INDEX <presentationId> <slideId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--to-index` | `*int64` |  | Zero-based insertion index where the slide should be moved |
diff --git a/docs/commands/gog-slides-new-slide.md b/docs/commands/gog-slides-new-slide.md
index 445a0df93..87a7dd05c 100644
--- a/docs/commands/gog-slides-new-slide.md
+++ b/docs/commands/gog-slides-new-slide.md
@@ -36,6 +36,7 @@ gog slides (slide) new-slide <presentationId> [flags]
 | `--layout-id` | `string` |  | Exact presentation layout object ID from 'slides info --json'; mutually exclusive with --layout |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-raw.md b/docs/commands/gog-slides-raw.md
index f6535b04e..aeb8a2b13 100644
--- a/docs/commands/gog-slides-raw.md
+++ b/docs/commands/gog-slides-raw.md
@@ -34,6 +34,7 @@ gog slides (slide) raw <presentationId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
+| `--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 |
diff --git a/docs/commands/gog-slides-read-slide.md b/docs/commands/gog-slides-read-slide.md
index 73b45bded..61a16ee9c 100644
--- a/docs/commands/gog-slides-read-slide.md
+++ b/docs/commands/gog-slides-read-slide.md
@@ -34,6 +34,7 @@ gog slides (slide) read-slide <presentationId> <slideId> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-replace-slide.md b/docs/commands/gog-slides-replace-slide.md
index 43b6fcad8..4dce644e1 100644
--- a/docs/commands/gog-slides-replace-slide.md
+++ b/docs/commands/gog-slides-replace-slide.md
@@ -35,6 +35,7 @@ gog slides (slide) replace-slide <presentationId> <slideId> [<image>] [flags]
 | `--notes` | `*string` |  | New speaker notes text (omit to preserve existing notes; use --notes '' to clear) |
 | `--notes-file` | `string` |  | Path to file containing new speaker notes |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--url` | `string` |  | Public HTTPS image URL to use directly |
diff --git a/docs/commands/gog-slides-replace-text.md b/docs/commands/gog-slides-replace-text.md
index 4463f253f..9a1dfee3f 100644
--- a/docs/commands/gog-slides-replace-text.md
+++ b/docs/commands/gog-slides-replace-text.md
@@ -37,6 +37,7 @@ gog slides (slide) replace-text <presentationId> <find> <replacement> [flags]
 | `--object` | `string` |  | Restrict replacement to a single shape text object ID |
 | `--page` | `[]string` |  | Restrict replacement to specific slide object IDs (repeatable) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-style-text.md b/docs/commands/gog-slides-style-text.md
index 1a4e21f82..c8bb386ea 100644
--- a/docs/commands/gog-slides-style-text.md
+++ b/docs/commands/gog-slides-style-text.md
@@ -40,6 +40,7 @@ gog slides (slide) style-text --range=STRING <presentationId> <objectId> [flags]
 | `--no-underline` | `bool` |  | Clear underline |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--range` | `string` |  | UTF-16 text range as start:end |
+| `--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. |
 | `--size` | `float64` |  | Font size in points |
diff --git a/docs/commands/gog-slides-table-border-style.md b/docs/commands/gog-slides-table-border-style.md
index e77fba91c..5572fdd2e 100644
--- a/docs/commands/gog-slides-table-border-style.md
+++ b/docs/commands/gog-slides-table-border-style.md
@@ -38,6 +38,7 @@ gog slides (slide) table border style --row=INT-64 --col=INT-64 <presentationId>
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--position` | `string` | ALL | Borders within the selected range to update |
+| `--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) |
 | `--row` | `int64` |  | Zero-based starting row |
 | `--row-span` | `int64` | 1 | Number of rows in the range |
diff --git a/docs/commands/gog-slides-table-border.md b/docs/commands/gog-slides-table-border.md
index 9aef833d1..cf806c7f2 100644
--- a/docs/commands/gog-slides-table-border.md
+++ b/docs/commands/gog-slides-table-border.md
@@ -37,6 +37,7 @@ gog slides (slide) table border <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-table-cell-style.md b/docs/commands/gog-slides-table-cell-style.md
index 2da4c8eb2..cfd140d4f 100644
--- a/docs/commands/gog-slides-table-cell-style.md
+++ b/docs/commands/gog-slides-table-cell-style.md
@@ -44,6 +44,7 @@ gog slides (slide) table cell style --row=INT-64 --col=INT-64 <presentationId> <
 | `--no-underline` | `bool` |  | Clear cell text underline |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--range` | `string` |  | Optional UTF-16 text range as start:end; defaults to all cell text |
+| `--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) |
 | `--row` | `int64` |  | Zero-based row |
 | `--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. |
diff --git a/docs/commands/gog-slides-table-cell.md b/docs/commands/gog-slides-table-cell.md
index 066ce408d..5fa468e9c 100644
--- a/docs/commands/gog-slides-table-cell.md
+++ b/docs/commands/gog-slides-table-cell.md
@@ -37,6 +37,7 @@ gog slides (slide) table cell <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-table-column-delete.md b/docs/commands/gog-slides-table-column-delete.md
index fb818c75d..9863ad90e 100644
--- a/docs/commands/gog-slides-table-column-delete.md
+++ b/docs/commands/gog-slides-table-column-delete.md
@@ -34,6 +34,7 @@ gog slides (slide) table column (col) delete (rm,remove,del) --col=INT-64 <prese
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-table-column-insert.md b/docs/commands/gog-slides-table-column-insert.md
index d60a46655..e9be3a007 100644
--- a/docs/commands/gog-slides-table-column-insert.md
+++ b/docs/commands/gog-slides-table-column-insert.md
@@ -35,6 +35,7 @@ gog slides (slide) table column (col) insert (add) --col=INT-64 <presentationId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--right` | `bool` |  | Insert right of the reference column instead of left |
 | `--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. |
diff --git a/docs/commands/gog-slides-table-column-size.md b/docs/commands/gog-slides-table-column-size.md
index ba8781151..695db704d 100644
--- a/docs/commands/gog-slides-table-column-size.md
+++ b/docs/commands/gog-slides-table-column-size.md
@@ -34,6 +34,7 @@ gog slides (slide) table column (col) size --col=INT-64 --width=FLOAT-64 <presen
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-table-column.md b/docs/commands/gog-slides-table-column.md
index e35683373..35626e904 100644
--- a/docs/commands/gog-slides-table-column.md
+++ b/docs/commands/gog-slides-table-column.md
@@ -39,6 +39,7 @@ gog slides (slide) table column (col) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-table-create.md b/docs/commands/gog-slides-table-create.md
index fd113e576..ac4ce3c0c 100644
--- a/docs/commands/gog-slides-table-create.md
+++ b/docs/commands/gog-slides-table-create.md
@@ -35,6 +35,7 @@ gog slides (slide) table create (add) --rows=INT-64 --cols=INT-64 <presentationI
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--object-id` | `string` |  | Optional table object ID to assign |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--rows` | `int64` |  | Number of table rows (>=1) |
 | `--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. |
diff --git a/docs/commands/gog-slides-table-merge.md b/docs/commands/gog-slides-table-merge.md
index d5192f10c..d26971f4d 100644
--- a/docs/commands/gog-slides-table-merge.md
+++ b/docs/commands/gog-slides-table-merge.md
@@ -35,6 +35,7 @@ gog slides (slide) table merge --row=INT-64 --col=INT-64 <presentationId> <table
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--row` | `int64` |  | Zero-based starting row |
 | `--row-span` | `int64` | 1 | Number of rows in the range |
diff --git a/docs/commands/gog-slides-table-row-delete.md b/docs/commands/gog-slides-table-row-delete.md
index 27d97ca7c..8cfef18c2 100644
--- a/docs/commands/gog-slides-table-row-delete.md
+++ b/docs/commands/gog-slides-table-row-delete.md
@@ -33,6 +33,7 @@ gog slides (slide) table row delete (rm,remove,del) --row=INT-64 <presentationId
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--row` | `int64` |  | Zero-based row to delete |
 | `--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. |
diff --git a/docs/commands/gog-slides-table-row-insert.md b/docs/commands/gog-slides-table-row-insert.md
index 25af860b5..0f5c8b89e 100644
--- a/docs/commands/gog-slides-table-row-insert.md
+++ b/docs/commands/gog-slides-table-row-insert.md
@@ -35,6 +35,7 @@ gog slides (slide) table row insert (add) --row=INT-64 <presentationId> <tableOb
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--row` | `int64` |  | Zero-based reference row |
 | `--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. |
diff --git a/docs/commands/gog-slides-table-row-size.md b/docs/commands/gog-slides-table-row-size.md
index 77e64fa96..81c5e1357 100644
--- a/docs/commands/gog-slides-table-row-size.md
+++ b/docs/commands/gog-slides-table-row-size.md
@@ -34,6 +34,7 @@ gog slides (slide) table row size --row=INT-64 --height=FLOAT-64 <presentationId
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--row` | `int64` |  | Zero-based row |
 | `--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. |
diff --git a/docs/commands/gog-slides-table-row.md b/docs/commands/gog-slides-table-row.md
index 24e49ae4a..13b7c7b6a 100644
--- a/docs/commands/gog-slides-table-row.md
+++ b/docs/commands/gog-slides-table-row.md
@@ -39,6 +39,7 @@ gog slides (slide) table row <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-table-unmerge.md b/docs/commands/gog-slides-table-unmerge.md
index a17cef7e6..166afa7d8 100644
--- a/docs/commands/gog-slides-table-unmerge.md
+++ b/docs/commands/gog-slides-table-unmerge.md
@@ -35,6 +35,7 @@ gog slides (slide) table unmerge (split) --row=INT-64 --col=INT-64 <presentation
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--row` | `int64` |  | Zero-based starting row |
 | `--row-span` | `int64` | 1 | Number of rows in the range |
diff --git a/docs/commands/gog-slides-table.md b/docs/commands/gog-slides-table.md
index a4ef648b7..b7e8cab28 100644
--- a/docs/commands/gog-slides-table.md
+++ b/docs/commands/gog-slides-table.md
@@ -43,6 +43,7 @@ gog slides (slide) table <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides-thumbnail.md b/docs/commands/gog-slides-thumbnail.md
index ba5e30ad6..2640e9465 100644
--- a/docs/commands/gog-slides-thumbnail.md
+++ b/docs/commands/gog-slides-thumbnail.md
@@ -36,6 +36,7 @@ gog slides (slide) thumbnail (thumb) <presentationId> <slideId> [flags]
 | `--out`<br>`--output` | `string` |  | Write the thumbnail image to a local file |
 | `--overwrite` | `bool` |  | Overwrite an existing output file |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--size` | `string` | large | Thumbnail size: small\|medium\|large |
diff --git a/docs/commands/gog-slides-update-notes.md b/docs/commands/gog-slides-update-notes.md
index 225ca6b2a..1940ae0c9 100644
--- a/docs/commands/gog-slides-update-notes.md
+++ b/docs/commands/gog-slides-update-notes.md
@@ -35,6 +35,7 @@ gog slides (slide) update-notes <presentationId> <slideId> [flags]
 | `--notes` | `*string` |  | Speaker notes text (use --notes '' to clear notes) |
 | `--notes-file` | `string` |  | Path to file containing speaker notes |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-slides.md b/docs/commands/gog-slides.md
index d0a526f94..9f2738de4 100644
--- a/docs/commands/gog-slides.md
+++ b/docs/commands/gog-slides.md
@@ -62,6 +62,7 @@ gog slides (slide) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-status.md b/docs/commands/gog-status.md
index d0a03b95b..118098ab4 100644
--- a/docs/commands/gog-status.md
+++ b/docs/commands/gog-status.md
@@ -33,6 +33,7 @@ gog status (st) [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-tasks-add.md b/docs/commands/gog-tasks-add.md
index 863226396..75420e8f5 100644
--- a/docs/commands/gog-tasks-add.md
+++ b/docs/commands/gog-tasks-add.md
@@ -37,6 +37,7 @@ gog tasks (task) add (create) <tasklistId> [flags]
 | `--parent` | `string` |  | Parent task ID (create as subtask) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--previous` | `string` |  | Previous sibling task ID (controls ordering) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--recur` | `string` |  | Alias for --repeat cadence: daily, weekly, monthly, yearly |
 | `--recur-rrule` | `string` |  | Alias for --repeat cadence via RRULE (supports FREQ + optional INTERVAL) |
 | `--repeat` | `string` |  | Materialize repeated tasks: daily, weekly, monthly, yearly |
diff --git a/docs/commands/gog-tasks-clear.md b/docs/commands/gog-tasks-clear.md
index a5e900ab3..406d58a05 100644
--- a/docs/commands/gog-tasks-clear.md
+++ b/docs/commands/gog-tasks-clear.md
@@ -33,6 +33,7 @@ gog tasks (task) clear <tasklistId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-tasks-delete.md b/docs/commands/gog-tasks-delete.md
index 7e1822d98..905c40434 100644
--- a/docs/commands/gog-tasks-delete.md
+++ b/docs/commands/gog-tasks-delete.md
@@ -33,6 +33,7 @@ gog tasks (task) delete (rm,del,remove) <tasklistId> <taskId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-tasks-done.md b/docs/commands/gog-tasks-done.md
index 86b9554e4..18ee6defa 100644
--- a/docs/commands/gog-tasks-done.md
+++ b/docs/commands/gog-tasks-done.md
@@ -33,6 +33,7 @@ gog tasks (task) done (complete) <tasklistId> <taskId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-tasks-get.md b/docs/commands/gog-tasks-get.md
index 4cbf43044..761c9f860 100644
--- a/docs/commands/gog-tasks-get.md
+++ b/docs/commands/gog-tasks-get.md
@@ -33,6 +33,7 @@ gog tasks (task) get (info,show) <tasklistId> <taskId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-tasks-list.md b/docs/commands/gog-tasks-list.md
index 7ff239e35..dec64d049 100644
--- a/docs/commands/gog-tasks-list.md
+++ b/docs/commands/gog-tasks-list.md
@@ -41,6 +41,7 @@ gog tasks (task) list (ls) <tasklistId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--show-assigned` | `bool` | true | Include tasks assigned to current user |
diff --git a/docs/commands/gog-tasks-lists-create.md b/docs/commands/gog-tasks-lists-create.md
index d8c21b30d..07b112f03 100644
--- a/docs/commands/gog-tasks-lists-create.md
+++ b/docs/commands/gog-tasks-lists-create.md
@@ -33,6 +33,7 @@ gog tasks (task) lists create (add,new) <title> ...
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-tasks-lists-list.md b/docs/commands/gog-tasks-lists-list.md
index ed735a1b7..64c597db2 100644
--- a/docs/commands/gog-tasks-lists-list.md
+++ b/docs/commands/gog-tasks-lists-list.md
@@ -37,6 +37,7 @@ gog tasks (task) lists list [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-tasks-lists.md b/docs/commands/gog-tasks-lists.md
index b87006102..c96311bf3 100644
--- a/docs/commands/gog-tasks-lists.md
+++ b/docs/commands/gog-tasks-lists.md
@@ -38,6 +38,7 @@ gog tasks (task) lists <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-tasks-raw.md b/docs/commands/gog-tasks-raw.md
index b1fffdf76..0976462cd 100644
--- a/docs/commands/gog-tasks-raw.md
+++ b/docs/commands/gog-tasks-raw.md
@@ -34,6 +34,7 @@ gog tasks (task) raw <tasklistId> <taskId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
+| `--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 |
diff --git a/docs/commands/gog-tasks-undo.md b/docs/commands/gog-tasks-undo.md
index 2933b1abb..46b06ce77 100644
--- a/docs/commands/gog-tasks-undo.md
+++ b/docs/commands/gog-tasks-undo.md
@@ -33,6 +33,7 @@ gog tasks (task) undo (uncomplete,undone) <tasklistId> <taskId>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-tasks-update.md b/docs/commands/gog-tasks-update.md
index c992477ca..dd7869833 100644
--- a/docs/commands/gog-tasks-update.md
+++ b/docs/commands/gog-tasks-update.md
@@ -35,6 +35,7 @@ gog tasks (task) update (edit,set) <tasklistId> <taskId> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--notes` | `string` |  | New notes (set empty to clear) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--status` | `string` |  | New status: needsAction\|completed (set empty to clear) |
diff --git a/docs/commands/gog-tasks.md b/docs/commands/gog-tasks.md
index fb2248bb6..9f9a7af10 100644
--- a/docs/commands/gog-tasks.md
+++ b/docs/commands/gog-tasks.md
@@ -46,6 +46,7 @@ gog tasks (task) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-time-now.md b/docs/commands/gog-time-now.md
index 901e91529..aae316828 100644
--- a/docs/commands/gog-time-now.md
+++ b/docs/commands/gog-time-now.md
@@ -33,6 +33,7 @@ gog time now [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--timezone` | `string` |  | Timezone (e.g., America/New_York, UTC). Default: GOG_TIMEZONE, config, then local |
diff --git a/docs/commands/gog-time.md b/docs/commands/gog-time.md
index 7f74928e7..f0606a204 100644
--- a/docs/commands/gog-time.md
+++ b/docs/commands/gog-time.md
@@ -37,6 +37,7 @@ gog time <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-upload.md b/docs/commands/gog-upload.md
index 13876e1bd..4d8a24fa5 100644
--- a/docs/commands/gog-upload.md
+++ b/docs/commands/gog-upload.md
@@ -40,6 +40,7 @@ gog upload (up,put) <localPath> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--parent` | `string` |  | Destination folder ID (create only) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--replace` | `string` |  | Replace the content of an existing Drive file ID (preserves shared link/permissions) |
 | `--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. |
diff --git a/docs/commands/gog-version.md b/docs/commands/gog-version.md
index 096abb2d3..b02af864f 100644
--- a/docs/commands/gog-version.md
+++ b/docs/commands/gog-version.md
@@ -33,6 +33,7 @@ gog version [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-whoami.md b/docs/commands/gog-whoami.md
index 52228db6b..6f7c3a0e8 100644
--- a/docs/commands/gog-whoami.md
+++ b/docs/commands/gog-whoami.md
@@ -33,6 +33,7 @@ gog whoami (who-am-i) [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-activities-list.md b/docs/commands/gog-youtube-activities-list.md
index 08fc6cdec..8bf41a62b 100644
--- a/docs/commands/gog-youtube-activities-list.md
+++ b/docs/commands/gog-youtube-activities-list.md
@@ -37,6 +37,7 @@ gog youtube (yt) activities (activity) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-activities.md b/docs/commands/gog-youtube-activities.md
index 1cb0e1228..d59a248ab 100644
--- a/docs/commands/gog-youtube-activities.md
+++ b/docs/commands/gog-youtube-activities.md
@@ -37,6 +37,7 @@ gog youtube (yt) activities (activity) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-channels-list.md b/docs/commands/gog-youtube-channels-list.md
index b7b931bc0..f904168cf 100644
--- a/docs/commands/gog-youtube-channels-list.md
+++ b/docs/commands/gog-youtube-channels-list.md
@@ -37,6 +37,7 @@ gog youtube (yt) channels (channel) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-channels.md b/docs/commands/gog-youtube-channels.md
index dcb41e875..8e2ab616d 100644
--- a/docs/commands/gog-youtube-channels.md
+++ b/docs/commands/gog-youtube-channels.md
@@ -37,6 +37,7 @@ gog youtube (yt) channels (channel) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-comments-list.md b/docs/commands/gog-youtube-comments-list.md
index 8956bfcc3..bade97833 100644
--- a/docs/commands/gog-youtube-comments-list.md
+++ b/docs/commands/gog-youtube-comments-list.md
@@ -36,6 +36,7 @@ gog youtube (yt) comments (comment) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-comments.md b/docs/commands/gog-youtube-comments.md
index 1b7f35391..869330cf7 100644
--- a/docs/commands/gog-youtube-comments.md
+++ b/docs/commands/gog-youtube-comments.md
@@ -37,6 +37,7 @@ gog youtube (yt) comments (comment) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-playlists-add.md b/docs/commands/gog-youtube-playlists-add.md
index 54e634915..d4f77642d 100644
--- a/docs/commands/gog-youtube-playlists-add.md
+++ b/docs/commands/gog-youtube-playlists-add.md
@@ -35,6 +35,7 @@ gog youtube (yt) playlists (playlist) add --playlist-id=STRING --video-id=STRING
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--playlist-id` | `string` |  | Playlist ID |
 | `--position` | `int64` | -1 | Position in playlist (0-based); appends if not set |
+| `--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 |
diff --git a/docs/commands/gog-youtube-playlists-create.md b/docs/commands/gog-youtube-playlists-create.md
index 305bc4e83..fd35d9429 100644
--- a/docs/commands/gog-youtube-playlists-create.md
+++ b/docs/commands/gog-youtube-playlists-create.md
@@ -35,6 +35,7 @@ gog youtube (yt) playlists (playlist) create --title=STRING [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--privacy` | `string` | private | Privacy: public, unlisted, private |
+| `--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. |
 | `--title` | `string` |  | Playlist title |
diff --git a/docs/commands/gog-youtube-playlists-delete.md b/docs/commands/gog-youtube-playlists-delete.md
index ab642f668..47011cf02 100644
--- a/docs/commands/gog-youtube-playlists-delete.md
+++ b/docs/commands/gog-youtube-playlists-delete.md
@@ -33,6 +33,7 @@ gog youtube (yt) playlists (playlist) delete (del) <playlist-id>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-playlists-items-list.md b/docs/commands/gog-youtube-playlists-items-list.md
index 4fb23c6b5..38579acae 100644
--- a/docs/commands/gog-youtube-playlists-items-list.md
+++ b/docs/commands/gog-youtube-playlists-items-list.md
@@ -37,6 +37,7 @@ gog youtube (yt) playlists (playlist) items (item) list (ls) [flags]
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--playlist-id` | `string` |  | Playlist ID (use LL for your liked videos; LL/private playlists require -a account) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-playlists-items.md b/docs/commands/gog-youtube-playlists-items.md
index 1cac0afcb..c3c9f7c61 100644
--- a/docs/commands/gog-youtube-playlists-items.md
+++ b/docs/commands/gog-youtube-playlists-items.md
@@ -37,6 +37,7 @@ gog youtube (yt) playlists (playlist) items (item) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-playlists-list.md b/docs/commands/gog-youtube-playlists-list.md
index 7ab1a7f2b..54353d816 100644
--- a/docs/commands/gog-youtube-playlists-list.md
+++ b/docs/commands/gog-youtube-playlists-list.md
@@ -37,6 +37,7 @@ gog youtube (yt) playlists (playlist) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-playlists-remove.md b/docs/commands/gog-youtube-playlists-remove.md
index e36a249e7..cba84753f 100644
--- a/docs/commands/gog-youtube-playlists-remove.md
+++ b/docs/commands/gog-youtube-playlists-remove.md
@@ -35,6 +35,7 @@ gog youtube (yt) playlists (playlist) remove (rm) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--playlist-id` | `string` |  | Playlist ID (required with --video-id) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-playlists.md b/docs/commands/gog-youtube-playlists.md
index 3dee10d33..5d1e30b56 100644
--- a/docs/commands/gog-youtube-playlists.md
+++ b/docs/commands/gog-youtube-playlists.md
@@ -42,6 +42,7 @@ gog youtube (yt) playlists (playlist) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-search-list.md b/docs/commands/gog-youtube-search-list.md
index 05d7a3f57..72b21dd72 100644
--- a/docs/commands/gog-youtube-search-list.md
+++ b/docs/commands/gog-youtube-search-list.md
@@ -37,6 +37,7 @@ gog youtube (yt) search (find) list (ls) <query> [flags]
 | `--order` | `string` | relevance | Sort order: relevance, date, rating, title, videoCount, viewCount |
 | `--page` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--type` | `string` | video | Resource type: video, channel, playlist (comma-separated) |
diff --git a/docs/commands/gog-youtube-search.md b/docs/commands/gog-youtube-search.md
index 85159161e..449f831c0 100644
--- a/docs/commands/gog-youtube-search.md
+++ b/docs/commands/gog-youtube-search.md
@@ -37,6 +37,7 @@ gog youtube (yt) search (find) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-subscriptions-list.md b/docs/commands/gog-youtube-subscriptions-list.md
index b3dd68420..2198c1b1b 100644
--- a/docs/commands/gog-youtube-subscriptions-list.md
+++ b/docs/commands/gog-youtube-subscriptions-list.md
@@ -36,6 +36,7 @@ gog youtube (yt) subscriptions (subscription) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page`<br>`--cursor` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-subscriptions-subscribe.md b/docs/commands/gog-youtube-subscriptions-subscribe.md
index d45621905..5cd07351c 100644
--- a/docs/commands/gog-youtube-subscriptions-subscribe.md
+++ b/docs/commands/gog-youtube-subscriptions-subscribe.md
@@ -34,6 +34,7 @@ gog youtube (yt) subscriptions (subscription) subscribe [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-subscriptions-unsubscribe.md b/docs/commands/gog-youtube-subscriptions-unsubscribe.md
index 8e25c04ac..e2265bcbb 100644
--- a/docs/commands/gog-youtube-subscriptions-unsubscribe.md
+++ b/docs/commands/gog-youtube-subscriptions-unsubscribe.md
@@ -35,6 +35,7 @@ gog youtube (yt) subscriptions (subscription) unsubscribe [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-subscriptions.md b/docs/commands/gog-youtube-subscriptions.md
index a9dba4478..af4500dce 100644
--- a/docs/commands/gog-youtube-subscriptions.md
+++ b/docs/commands/gog-youtube-subscriptions.md
@@ -39,6 +39,7 @@ gog youtube (yt) subscriptions (subscription) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube-videos-list.md b/docs/commands/gog-youtube-videos-list.md
index 673f2fdeb..30f1bad92 100644
--- a/docs/commands/gog-youtube-videos-list.md
+++ b/docs/commands/gog-youtube-videos-list.md
@@ -38,6 +38,7 @@ gog youtube (yt) videos (video) list (ls) [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--page` | `string` |  | Page token |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--readonly` | `bool` | false | Block mutating API requests at runtime; auth add also requests read-only OAuth scopes |
 | `--region` | `string` |  | Region code (e.g. US) for chart |
 | `--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. |
diff --git a/docs/commands/gog-youtube-videos.md b/docs/commands/gog-youtube-videos.md
index abef35201..2cec80717 100644
--- a/docs/commands/gog-youtube-videos.md
+++ b/docs/commands/gog-youtube-videos.md
@@ -37,6 +37,7 @@ gog youtube (yt) videos (video) <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-youtube.md b/docs/commands/gog-youtube.md
index 31629d720..655957b64 100644
--- a/docs/commands/gog-youtube.md
+++ b/docs/commands/gog-youtube.md
@@ -43,6 +43,7 @@ gog youtube (yt) <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-zoom-auth-doctor.md b/docs/commands/gog-zoom-auth-doctor.md
index bb1aa9da3..0985ad16f 100644
--- a/docs/commands/gog-zoom-auth-doctor.md
+++ b/docs/commands/gog-zoom-auth-doctor.md
@@ -34,6 +34,7 @@ gog zoom auth doctor [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-zoom-auth-setup.md b/docs/commands/gog-zoom-auth-setup.md
index 136452a4c..05204e0b4 100644
--- a/docs/commands/gog-zoom-auth-setup.md
+++ b/docs/commands/gog-zoom-auth-setup.md
@@ -37,6 +37,7 @@ gog zoom auth setup [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
 | `--skip-validate` | `bool` |  | Store credentials without calling Zoom /users/me |
diff --git a/docs/commands/gog-zoom-auth.md b/docs/commands/gog-zoom-auth.md
index 492c51996..7e1e35fcc 100644
--- a/docs/commands/gog-zoom-auth.md
+++ b/docs/commands/gog-zoom-auth.md
@@ -38,6 +38,7 @@ gog zoom auth <command>
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-zoom.md b/docs/commands/gog-zoom.md
index 46a0c88cd..2eea265d8 100644
--- a/docs/commands/gog-zoom.md
+++ b/docs/commands/gog-zoom.md
@@ -37,6 +37,7 @@ gog zoom <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog.md b/docs/commands/gog.md
index 5ba1dbc79..8d8498c00 100644
--- a/docs/commands/gog.md
+++ b/docs/commands/gog.md
@@ -81,6 +81,7 @@ gog <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/internal/cmd/auth_add.go b/internal/cmd/auth_add.go
index 095714da2..5a997e827 100644
--- a/internal/cmd/auth_add.go
+++ b/internal/cmd/auth_add.go
@@ -28,13 +28,12 @@ type AuthAddCmd struct {
 	Timeout      time.Duration `name:"timeout" help:"Authorization timeout (manual flows default to 5m)"`
 	ForceConsent bool          `name:"force-consent" help:"Force consent screen to obtain a refresh token"`
 	ServicesCSV  string        `name:"services" help:"Services to authorize: user|all-user or comma-separated ${auth_services}; explicit opt-in: photospicker; all means all default user OAuth services. Workspace service-account-only services: admin, groups, keep" default:"user"`
-	Readonly     bool          `name:"readonly" help:"Use read-only scopes where available (still includes OIDC identity scopes)"`
 	DriveScope   string        `name:"drive-scope" help:"Drive scope mode: full|readonly|file" enum:"full,readonly,file" default:"full"`
 	GmailScope   string        `name:"gmail-scope" help:"Gmail scope mode: full|readonly" enum:"full,readonly" default:"full"`
 	ExtraScopes  string        `name:"extra-scopes" help:"Comma-separated list of additional OAuth scope URIs to request (appended after service scopes)"`
 }
 
-func formatRemoteStep2Instruction(services []googleauth.Service, c *AuthAddCmd) string {
+func formatRemoteStep2Instruction(services []googleauth.Service, c *AuthAddCmd, readonly bool) string {
 	parts := []string{"--remote", "--step", "2", "--auth-url", "<redirect-url>"}
 	if redirectHost := strings.TrimSpace(c.RedirectHost); redirectHost != "" {
 		parts = append(parts, "--redirect-host", redirectHost)
@@ -49,7 +48,7 @@ func formatRemoteStep2Instruction(services []googleauth.Service, c *AuthAddCmd)
 		}
 		parts = append(parts, "--services", strings.Join(serialized, ","))
 	}
-	if c.Readonly {
+	if readonly {
 		parts = append(parts, "--readonly")
 	}
 	if driveScope := strings.ToLower(strings.TrimSpace(c.DriveScope)); driveScope != "" && driveScope != string(googleauth.DriveScopeFull) {
@@ -95,6 +94,7 @@ func (c *AuthAddCmd) isManualFlow(authURL, authCode string) bool {
 
 func (c *AuthAddCmd) Run(ctx context.Context, flags *RootFlags) error {
 	u := ui.FromContext(ctx)
+	readonly := readOnlyEnabled(flags)
 
 	override := authclient.ClientOverrideFromContext(ctx)
 	client, err := authclient.ResolveClientWithOverride(ctx, c.Email, override)
@@ -111,11 +111,11 @@ func (c *AuthAddCmd) Run(ctx context.Context, flags *RootFlags) error {
 	}
 
 	driveScope := strings.ToLower(strings.TrimSpace(c.DriveScope))
-	if c.Readonly && driveScope == strFile {
+	if readonly && driveScope == strFile {
 		return usage("cannot combine --readonly with --drive-scope=file (file is write-capable)")
 	}
 	gmailScope := strings.ToLower(strings.TrimSpace(c.GmailScope))
-	disableIncludeGrantedScopes := c.Readonly ||
+	disableIncludeGrantedScopes := readonly ||
 		driveScope == "readonly" ||
 		driveScope == strFile ||
 		gmailScope == "readonly"
@@ -123,7 +123,7 @@ func (c *AuthAddCmd) Run(ctx context.Context, flags *RootFlags) error {
 	extraScopes := parseExtraScopesCSV(c.ExtraScopes)
 
 	scopes, err := googleauth.ScopesForManageWithOptions(services, googleauth.ScopeOptions{
-		Readonly:    c.Readonly,
+		Readonly:    readonly,
 		DriveScope:  googleauth.DriveScopeMode(driveScope),
 		GmailScope:  googleauth.GmailScopeMode(gmailScope),
 		ExtraScopes: extraScopes,
@@ -184,7 +184,7 @@ func (c *AuthAddCmd) Run(ctx context.Context, flags *RootFlags) error {
 			}
 			u.Out().Linef("auth_url\t%s", result.URL)
 			u.Out().Linef("state_reused\t%t", result.StateReused)
-			u.Err().Linef("Run again with the same root flags and %s", formatRemoteStep2Instruction(services, c))
+			u.Err().Linef("Run again with the same root flags and %s", formatRemoteStep2Instruction(services, c, readonly))
 			return nil
 		case 2:
 			if authCode != "" {
@@ -213,7 +213,7 @@ func (c *AuthAddCmd) Run(ctx context.Context, flags *RootFlags) error {
 		"redirect_host": strings.TrimSpace(c.RedirectHost),
 		"redirect_uri":  redirectURI,
 		"force_consent": c.ForceConsent,
-		"readonly":      c.Readonly,
+		"readonly":      readonly,
 		"drive_scope":   c.DriveScope,
 		"gmail_scope":   c.GmailScope,
 		"extra_scopes":  extraScopes,
@@ -318,6 +318,10 @@ func (c *AuthAddCmd) Run(ctx context.Context, flags *RootFlags) error {
 	return nil
 }
 
+func readOnlyEnabled(flags *RootFlags) bool {
+	return flags != nil && flags.ReadOnly
+}
+
 func wrapAuthAddStoreError(err error) error {
 	if err == nil {
 		return nil
diff --git a/internal/cmd/exit_codes.go b/internal/cmd/exit_codes.go
index 7d091cd77..c60ff1a5c 100644
--- a/internal/cmd/exit_codes.go
+++ b/internal/cmd/exit_codes.go
@@ -63,6 +63,9 @@ func stableExitCode(err error) error {
 	if errors.Is(err, context.Canceled) {
 		return &ExitError{Code: exitCodeCancelled, Err: err}
 	}
+	if errors.Is(err, gogapi.ErrReadOnly) {
+		return &ExitError{Code: 2, Err: err}
+	}
 
 	var authErr *gogapi.AuthRequiredError
 	if errors.As(err, &authErr) {
diff --git a/internal/cmd/exit_codes_test.go b/internal/cmd/exit_codes_test.go
index bd818ebcf..3e5f5613f 100644
--- a/internal/cmd/exit_codes_test.go
+++ b/internal/cmd/exit_codes_test.go
@@ -130,6 +130,13 @@ func TestStableExitCode_Cancelled(t *testing.T) {
 	}
 }
 
+func TestStableExitCode_ReadOnly(t *testing.T) {
+	out := stableExitCode(gogapi.ErrReadOnly)
+	if got := ExitCode(out); got != 2 {
+		t.Fatalf("expected exit code 2, got %d", got)
+	}
+}
+
 func TestStableExitCode_DeadlineExceeded(t *testing.T) {
 	out := stableExitCode(context.DeadlineExceeded)
 	if got := ExitCode(out); got != exitCodeRetryable {
diff --git a/internal/cmd/gmail_watch_pull.go b/internal/cmd/gmail_watch_pull.go
index a92bd2a9c..f1407c60e 100644
--- a/internal/cmd/gmail_watch_pull.go
+++ b/internal/cmd/gmail_watch_pull.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"net/http"
 	"strings"
 	"time"
@@ -14,6 +15,7 @@ import (
 
 	"github.com/steipete/gogcli/internal/authclient"
 	"github.com/steipete/gogcli/internal/gmailwatch"
+	"github.com/steipete/gogcli/internal/googleapi"
 	"github.com/steipete/gogcli/internal/ui"
 )
 
@@ -32,6 +34,10 @@ type GmailWatchPullCmd struct {
 }
 
 func (c *GmailWatchPullCmd) Run(ctx context.Context, kctx *kong.Context, flags *RootFlags) error {
+	if googleapi.ReadOnly(ctx) && (flags == nil || !flags.DryRun) {
+		return fmt.Errorf("%w: Gmail watch pull acknowledges Pub/Sub messages", googleapi.ErrReadOnly)
+	}
+
 	u := ui.FromContext(ctx)
 	account, err := requireAccount(flags)
 	if err != nil {
diff --git a/internal/cmd/gmail_watch_pull_test.go b/internal/cmd/gmail_watch_pull_test.go
index 07da5323e..db6446f83 100644
--- a/internal/cmd/gmail_watch_pull_test.go
+++ b/internal/cmd/gmail_watch_pull_test.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"io"
 	"net/http"
 	"net/http/httptest"
@@ -15,6 +16,7 @@ import (
 	"google.golang.org/api/gmail/v1"
 	"google.golang.org/api/option"
 
+	"github.com/steipete/gogcli/internal/googleapi"
 	"github.com/steipete/gogcli/internal/outfmt"
 	"github.com/steipete/gogcli/internal/ui"
 )
@@ -188,6 +190,14 @@ func TestGmailWatchPullCmd_DryRunDoesNotCreateReceiverOrState(t *testing.T) {
 	}
 }
 
+func TestGmailWatchPullCmd_ReadOnlyBlocksPubSubAck(t *testing.T) {
+	ctx := googleapi.WithReadOnly(context.Background(), true)
+	err := runKong(t, &GmailWatchPullCmd{}, nil, ctx, &RootFlags{ReadOnly: true})
+	if !errors.Is(err, googleapi.ErrReadOnly) {
+		t.Fatalf("error = %v, want ErrReadOnly", err)
+	}
+}
+
 func TestGmailWatchPullMessage_AcksInvalidAndWrongAccount(t *testing.T) {
 	server := &gmailWatchServer{
 		cfg:   gmailWatchServeConfig{Account: "a@b.com"},
diff --git a/internal/cmd/mcp.go b/internal/cmd/mcp.go
index 58d8faf9f..25b083611 100644
--- a/internal/cmd/mcp.go
+++ b/internal/cmd/mcp.go
@@ -227,6 +227,9 @@ func mcpParentSafetyArgs(flags *RootFlags) []string {
 	if flags.GmailNoSend {
 		out = append(out, "--gmail-no-send")
 	}
+	if flags.ReadOnly {
+		out = append(out, "--readonly")
+	}
 	if s := strings.TrimSpace(flags.EnableCommands); s != "" {
 		out = append(out, "--enable-commands="+s)
 	}
diff --git a/internal/cmd/mcp_test.go b/internal/cmd/mcp_test.go
index 5f953877d..aecf613e5 100644
--- a/internal/cmd/mcp_test.go
+++ b/internal/cmd/mcp_test.go
@@ -63,6 +63,7 @@ func TestMCPParentArgsPreserveContextAndSafety(t *testing.T) {
 		Select:              "messages",
 		DryRun:              true,
 		GmailNoSend:         true,
+		ReadOnly:            true,
 		EnableCommands:      "gmail.search,docs.cat",
 		EnableCommandsExact: "mcp,gmail.messages.search",
 		DisableCommands:     "drive.delete",
@@ -74,7 +75,7 @@ func TestMCPParentArgsPreserveContextAndSafety(t *testing.T) {
 		}
 	}
 	safety := strings.Join(mcpParentSafetyArgs(flags), "\x00")
-	for _, want := range []string{"--gmail-no-send", "--enable-commands=gmail.search,docs.cat", "--enable-commands-exact=mcp,gmail.messages.search", "--disable-commands=drive.delete"} {
+	for _, want := range []string{"--gmail-no-send", "--readonly", "--enable-commands=gmail.search,docs.cat", "--enable-commands-exact=mcp,gmail.messages.search", "--disable-commands=drive.delete"} {
 		if !strings.Contains(safety, want) {
 			t.Fatalf("safety args missing %q in %#v", want, mcpParentSafetyArgs(flags))
 		}
diff --git a/internal/cmd/root.go b/internal/cmd/root.go
index dc5d5267a..ba11e0976 100644
--- a/internal/cmd/root.go
+++ b/internal/cmd/root.go
@@ -40,6 +40,7 @@ type RootFlags struct {
 	EnableCommandsExact string `name:"enable-commands-exact" help:"Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children" default:"${enabled_commands_exact}"`
 	DisableCommands     string `help:"Comma-separated list of disabled commands; dot paths allowed" default:"${disabled_commands}"`
 	GmailNoSend         bool   `help:"Block Gmail send operations (agent safety)" default:"${gmail_no_send}"`
+	ReadOnly            bool   `name:"readonly" help:"Block mutating API requests at runtime; auth add also requests read-only OAuth scopes" default:"${readonly}"`
 	JSON                bool   `help:"Output JSON to stdout (best for scripting)" default:"${json}" aliases:"machine" short:"j"`
 	Plain               bool   `help:"Output stable, parseable text to stdout (TSV; no colors)" default:"${plain}" aliases:"tsv" short:"p"`
 	WrapUntrusted       bool   `name:"wrap-untrusted" help:"In JSON/raw output, wrap fetched text fields in external untrusted-content markers" default:"${wrap_untrusted}"`
@@ -205,6 +206,7 @@ func executeWithRuntime(args []string, runtime *app.Runtime) (err error) {
 
 	ctx := context.Background()
 	ctx = app.WithRuntime(ctx, runtime)
+	ctx = googleapi.WithReadOnly(ctx, cli.ReadOnly)
 	runtimeContext := ctx
 	serviceAccounts := func() (*config.ServiceAccountStore, error) {
 		return commandServiceAccountStore(runtimeContext)
@@ -477,6 +479,7 @@ func newParserWithWriters(description string, stdout, stderr io.Writer) (*kong.K
 		"gmail_no_send":          boolString(envBool("GOG_GMAIL_NO_SEND")),
 		"json":                   boolString(envMode.JSON),
 		"plain":                  boolString(envMode.Plain),
+		"readonly":               boolString(envBool("GOG_READONLY")),
 		"wrap_untrusted":         boolString(envBool("GOG_WRAP_UNTRUSTED")),
 		"version":                VersionString(),
 	}
diff --git a/internal/cmd/runtime_services.go b/internal/cmd/runtime_services.go
index eefb67921..311beda30 100644
--- a/internal/cmd/runtime_services.go
+++ b/internal/cmd/runtime_services.go
@@ -398,6 +398,10 @@ func slidesService(ctx context.Context, account string) (*slides.Service, error)
 }
 
 func zoomMeetingClient(ctx context.Context, alias string) (app.ZoomMeetingClient, error) {
+	if googleapi.ReadOnly(ctx) {
+		return nil, fmt.Errorf("%w: Zoom meeting mutations are disabled", googleapi.ErrReadOnly)
+	}
+
 	runtime, err := runtimeWithService(ctx, "zoom")
 	if err != nil || runtime.Services.Zoom == nil {
 		return nil, serviceError(err, "zoom")
diff --git a/internal/cmd/schema.go b/internal/cmd/schema.go
index 6c46afe5a..17f17fbd4 100644
--- a/internal/cmd/schema.go
+++ b/internal/cmd/schema.go
@@ -34,6 +34,7 @@ type schemaSafetyState struct {
 	NoInput       bool               `json:"no_input"`
 	WrapUntrusted bool               `json:"wrap_untrusted"`
 	GmailNoSend   bool               `json:"gmail_no_send"`
+	ReadOnly      bool               `json:"readonly"`
 	BakedProfile  schemaBakedProfile `json:"baked_profile"`
 	CommandRules  schemaCommandRules `json:"command_rules"`
 }
@@ -154,6 +155,7 @@ func buildSchemaAutomation(ctx context.Context, flags *RootFlags, profile bakedS
 		safety.NoInput = flags.NoInput
 		safety.WrapUntrusted = flags.WrapUntrusted
 		safety.GmailNoSend = flags.GmailNoSend
+		safety.ReadOnly = flags.ReadOnly
 		safety.CommandRules.EnabledPrefixes = sortedCommandRules(flags.EnableCommands)
 		safety.CommandRules.EnabledExact = sortedCommandRules(flags.EnableCommandsExact)
 		safety.CommandRules.Disabled = sortedCommandRules(flags.DisableCommands)
diff --git a/internal/cmd/schema_test.go b/internal/cmd/schema_test.go
index 2a698e3c8..1341e05ef 100644
--- a/internal/cmd/schema_test.go
+++ b/internal/cmd/schema_test.go
@@ -68,6 +68,7 @@ func TestExecute_SchemaIncludesAutomationContract(t *testing.T) {
 				"--no-input",
 				"--wrap-untrusted",
 				"--gmail-no-send",
+				"--readonly",
 				"--enable-commands-exact", "schema,gmail.search",
 				"--disable-commands", "gmail.send",
 				"schema",
@@ -91,7 +92,7 @@ func TestExecute_SchemaIncludesAutomationContract(t *testing.T) {
 		t.Fatalf("schema command metadata was transformed: %#v", doc.Command)
 	}
 	assertSchemaAliases(t, doc.Command)
-	if !doc.Automation.Safety.DryRun || !doc.Automation.Safety.NoInput || !doc.Automation.Safety.WrapUntrusted || !doc.Automation.Safety.GmailNoSend {
+	if !doc.Automation.Safety.DryRun || !doc.Automation.Safety.NoInput || !doc.Automation.Safety.WrapUntrusted || !doc.Automation.Safety.GmailNoSend || !doc.Automation.Safety.ReadOnly {
 		t.Fatalf("safety = %#v", doc.Automation.Safety)
 	}
 	if got := strings.Join(doc.Automation.Safety.CommandRules.EnabledExact, ","); got != "gmail.search,schema" {
diff --git a/internal/googleapi/client.go b/internal/googleapi/client.go
index c44c02339..5d299357e 100644
--- a/internal/googleapi/client.go
+++ b/internal/googleapi/client.go
@@ -148,10 +148,10 @@ func authenticatedTransportWithStoredScopeCheck(
 		}
 	}
 
-	return NewRetryTransport(&oauth2.Transport{
+	return readOnlyTransportFromContext(ctx, NewRetryTransport(&oauth2.Transport{
 		Source: ts,
 		Base:   newBaseTransport(),
-	}), nil
+	})), nil
 }
 
 func optionsForAccountScopes(ctx context.Context, serviceLabel string, email string, scopes []string) ([]option.ClientOption, error) {
@@ -171,13 +171,13 @@ func optionsForServiceAccountScopes(ctx context.Context, serviceLabel string, em
 			return nil, err
 		}
 
-		return tokenSourceClientOptions(ts), nil
+		return tokenSourceClientOptions(ctx, ts), nil
 	}
 
 	if accessToken := authclient.AccessTokenFromContext(ctx); accessToken != "" {
 		slog.Debug("using direct access token", "serviceLabel", serviceLabel)
 
-		return tokenSourceClientOptions(oauth2.StaticTokenSource(&oauth2.Token{AccessToken: accessToken})), nil
+		return tokenSourceClientOptions(ctx, oauth2.StaticTokenSource(&oauth2.Token{AccessToken: accessToken})), nil
 	}
 
 	dependencies, err := requireAuthDependencies(ctx)
@@ -196,15 +196,15 @@ func optionsForServiceAccountScopes(ctx context.Context, serviceLabel string, em
 
 	slog.Debug("using required service account credentials", "email", email, "path", path)
 
-	return tokenSourceClientOptions(ts), nil
+	return tokenSourceClientOptions(ctx, ts), nil
 }
 
-func tokenSourceClientOptions(ts oauth2.TokenSource) []option.ClientOption {
+func tokenSourceClientOptions(ctx context.Context, ts oauth2.TokenSource) []option.ClientOption {
 	return []option.ClientOption{option.WithHTTPClient(&http.Client{
-		Transport: NewRetryTransport(&oauth2.Transport{
+		Transport: readOnlyTransportFromContext(ctx, NewRetryTransport(&oauth2.Transport{
 			Source: ts,
 			Base:   newBaseTransport(),
-		}),
+		})),
 	})}
 }
 
diff --git a/internal/googleapi/keep.go b/internal/googleapi/keep.go
index 40bc7a696..7e7f309f3 100644
--- a/internal/googleapi/keep.go
+++ b/internal/googleapi/keep.go
@@ -6,7 +6,6 @@ import (
 	"os"
 
 	"google.golang.org/api/keep/v1"
-	"google.golang.org/api/option"
 
 	"github.com/steipete/gogcli/internal/googleauth"
 )
@@ -44,7 +43,7 @@ func newKeepWithServiceAccount(
 		return nil, err
 	}
 
-	svc, err := keep.NewService(ctx, option.WithTokenSource(tokenSource))
+	svc, err := keep.NewService(ctx, tokenSourceClientOptions(ctx, tokenSource)...)
 	if err != nil {
 		return nil, fmt.Errorf("create keep service: %w", err)
 	}
diff --git a/internal/googleapi/read_only.go b/internal/googleapi/read_only.go
new file mode 100644
index 000000000..bdfbcb0b0
--- /dev/null
+++ b/internal/googleapi/read_only.go
@@ -0,0 +1,111 @@
+package googleapi
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+)
+
+var ErrReadOnly = errors.New("request blocked by --readonly")
+
+type readOnlyContextKey struct{}
+
+func WithReadOnly(ctx context.Context, enabled bool) context.Context {
+	if !enabled {
+		return ctx
+	}
+
+	return context.WithValue(ctx, readOnlyContextKey{}, true)
+}
+
+func ReadOnly(ctx context.Context) bool {
+	if ctx == nil {
+		return false
+	}
+
+	enabled, _ := ctx.Value(readOnlyContextKey{}).(bool)
+
+	return enabled
+}
+
+type readOnlyTransport struct {
+	base http.RoundTripper
+}
+
+func readOnlyTransportFromContext(ctx context.Context, base http.RoundTripper) http.RoundTripper {
+	if !ReadOnly(ctx) {
+		return base
+	}
+
+	if base == nil {
+		base = http.DefaultTransport
+	}
+
+	return &readOnlyTransport{base: base}
+}
+
+func (t *readOnlyTransport) RoundTrip(request *http.Request) (*http.Response, error) {
+	if !readOnlyHTTPRequest(request) {
+		method := ""
+		path := ""
+
+		if request != nil {
+			method = request.Method
+			if request.URL != nil {
+				path = request.URL.Path
+			}
+		}
+
+		return nil, fmt.Errorf("%w: %s %s", ErrReadOnly, method, path)
+	}
+
+	response, err := t.base.RoundTrip(request)
+	if err != nil {
+		return nil, fmt.Errorf("read-only transport: %w", err)
+	}
+
+	return response, nil
+}
+
+func readOnlyHTTPRequest(request *http.Request) bool {
+	if request == nil || request.URL == nil {
+		return false
+	}
+
+	switch request.Method {
+	case http.MethodGet, http.MethodHead, http.MethodOptions:
+		return true
+	case http.MethodPost:
+		return readOnlyPOSTPath(request.URL.Path)
+	default:
+		return false
+	}
+}
+
+func readOnlyPOSTPath(path string) bool {
+	if path == "" {
+		return false
+	}
+
+	for _, suffix := range []string{
+		"/freeBusy",
+		"/searchAnalytics/query",
+		"/urlInspection/index:inspect",
+		"/mediaItems:search",
+		":batchGetByDataFilter",
+		":getByDataFilter",
+		":query",
+		":runReport",
+		":batchRunReports",
+		":runPivotReport",
+		":runRealtimeReport",
+	} {
+		if strings.HasSuffix(path, suffix) {
+			return true
+		}
+	}
+
+	return false
+}
diff --git a/internal/googleapi/read_only_test.go b/internal/googleapi/read_only_test.go
new file mode 100644
index 000000000..d94507c38
--- /dev/null
+++ b/internal/googleapi/read_only_test.go
@@ -0,0 +1,119 @@
+package googleapi
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"golang.org/x/oauth2"
+	"google.golang.org/api/keep/v1"
+)
+
+type readOnlyTestTransport struct {
+	calls int
+}
+
+func (t *readOnlyTestTransport) RoundTrip(*http.Request) (*http.Response, error) {
+	t.calls++
+
+	return &http.Response{StatusCode: http.StatusNoContent, Body: http.NoBody}, nil
+}
+
+func TestReadOnlyTransport(t *testing.T) {
+	base := &readOnlyTestTransport{}
+	transport := readOnlyTransportFromContext(WithReadOnly(context.Background(), true), base)
+
+	readRequest, err := http.NewRequestWithContext(context.Background(), http.MethodGet, "https://example.test/items", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	roundTripErr := readOnlyTestRoundTrip(transport, readRequest)
+	if roundTripErr != nil {
+		t.Fatalf("GET: %v", roundTripErr)
+	}
+
+	queryRequest, err := http.NewRequestWithContext(context.Background(), http.MethodPost, "https://example.test/v3/freeBusy", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	roundTripErr = readOnlyTestRoundTrip(transport, queryRequest)
+	if roundTripErr != nil {
+		t.Fatalf("query POST: %v", roundTripErr)
+	}
+
+	writeRequest, err := http.NewRequestWithContext(context.Background(), http.MethodPost, "https://example.test/gmail/v1/users/me/messages/send", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	roundTripErr = readOnlyTestRoundTrip(transport, writeRequest)
+
+	if !errors.Is(roundTripErr, ErrReadOnly) {
+		t.Fatalf("write error = %v, want ErrReadOnly", roundTripErr)
+	}
+
+	if base.calls != 2 {
+		t.Fatalf("base calls = %d, want 2", base.calls)
+	}
+}
+
+func TestReadOnlyTransportDisabled(t *testing.T) {
+	base := &readOnlyTestTransport{}
+	transport := readOnlyTransportFromContext(context.Background(), base)
+
+	request, err := http.NewRequestWithContext(context.Background(), http.MethodDelete, "https://example.test/items/1", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	roundTripErr := readOnlyTestRoundTrip(transport, request)
+	if roundTripErr != nil {
+		t.Fatal(roundTripErr)
+	}
+
+	if base.calls != 1 {
+		t.Fatalf("base calls = %d, want 1", base.calls)
+	}
+}
+
+func TestKeepServiceAccountUsesReadOnlyTransport(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "service-account.json")
+	if err := os.WriteFile(path, []byte(`{}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	ctx := WithReadOnly(context.Background(), true)
+
+	svc, err := newKeepWithServiceAccount(ctx, path, "user@example.com", func(context.Context, []byte, string, []string) (oauth2.TokenSource, error) {
+		return oauth2.StaticTokenSource(&oauth2.Token{AccessToken: "test"}), nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = svc.Notes.Create(&keep.Note{}).Do()
+
+	if !errors.Is(err, ErrReadOnly) {
+		t.Fatalf("create error = %v, want ErrReadOnly", err)
+	}
+}
+
+func readOnlyTestRoundTrip(transport http.RoundTripper, request *http.Request) error {
+	response, err := transport.RoundTrip(request)
+
+	if response != nil && response.Body != nil {
+		_ = response.Body.Close()
+	}
+
+	if err != nil {
+		return fmt.Errorf("round trip: %w", err)
+	}
+
+	return nil
+}

From e00cbb54c46005eb28328fd1cc78dad8c1717797 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 22 Jun 2026 13:22:24 -0400
Subject: [PATCH 2/7] fix(safety): scope readonly query allowlist

---
 internal/googleapi/read_only.go      | 48 +++++++++++++++------------
 internal/googleapi/read_only_test.go | 49 +++++++++++++++++++++++++++-
 2 files changed, 75 insertions(+), 22 deletions(-)

diff --git a/internal/googleapi/read_only.go b/internal/googleapi/read_only.go
index bdfbcb0b0..45541ff52 100644
--- a/internal/googleapi/read_only.go
+++ b/internal/googleapi/read_only.go
@@ -73,39 +73,45 @@ func readOnlyHTTPRequest(request *http.Request) bool {
 	if request == nil || request.URL == nil {
 		return false
 	}
+	if strings.TrimSpace(request.Header.Get("X-HTTP-Method-Override")) != "" {
+		return false
+	}
 
 	switch request.Method {
 	case http.MethodGet, http.MethodHead, http.MethodOptions:
 		return true
 	case http.MethodPost:
-		return readOnlyPOSTPath(request.URL.Path)
+		return readOnlyPOSTRequest(request)
 	default:
 		return false
 	}
 }
 
-func readOnlyPOSTPath(path string) bool {
-	if path == "" {
+func readOnlyPOSTRequest(request *http.Request) bool {
+	if request == nil || request.URL == nil || request.URL.Scheme != "https" {
 		return false
 	}
 
-	for _, suffix := range []string{
-		"/freeBusy",
-		"/searchAnalytics/query",
-		"/urlInspection/index:inspect",
-		"/mediaItems:search",
-		":batchGetByDataFilter",
-		":getByDataFilter",
-		":query",
-		":runReport",
-		":batchRunReports",
-		":runPivotReport",
-		":runRealtimeReport",
-	} {
-		if strings.HasSuffix(path, suffix) {
-			return true
-		}
+	host := strings.ToLower(strings.TrimSuffix(request.URL.Hostname(), "."))
+	path := request.URL.Path
+
+	switch host {
+	case "www.googleapis.com", "www.mtls.googleapis.com", "calendar-json.googleapis.com", "calendar-json.mtls.googleapis.com":
+		return strings.HasSuffix(path, "/calendar/v3/freeBusy")
+	case "searchconsole.googleapis.com", "searchconsole.mtls.googleapis.com":
+		return strings.HasSuffix(path, "/searchAnalytics/query") || strings.HasSuffix(path, "/urlInspection/index:inspect")
+	case "photoslibrary.googleapis.com", "photoslibrary.mtls.googleapis.com":
+		return strings.HasSuffix(path, "/v1/mediaItems:search")
+	case "sheets.googleapis.com", "sheets.mtls.googleapis.com":
+		return strings.HasSuffix(path, ":batchGetByDataFilter") || strings.HasSuffix(path, ":getByDataFilter")
+	case "driveactivity.googleapis.com", "driveactivity.mtls.googleapis.com":
+		return strings.HasSuffix(path, "/v2/activity:query")
+	case "analyticsdata.googleapis.com", "analyticsdata.mtls.googleapis.com":
+		return strings.HasSuffix(path, ":runReport") ||
+			strings.HasSuffix(path, ":batchRunReports") ||
+			strings.HasSuffix(path, ":runPivotReport") ||
+			strings.HasSuffix(path, ":runRealtimeReport")
+	default:
+		return false
 	}
-
-	return false
 }
diff --git a/internal/googleapi/read_only_test.go b/internal/googleapi/read_only_test.go
index d94507c38..2d8ea4ca0 100644
--- a/internal/googleapi/read_only_test.go
+++ b/internal/googleapi/read_only_test.go
@@ -37,7 +37,7 @@ func TestReadOnlyTransport(t *testing.T) {
 		t.Fatalf("GET: %v", roundTripErr)
 	}
 
-	queryRequest, err := http.NewRequestWithContext(context.Background(), http.MethodPost, "https://example.test/v3/freeBusy", nil)
+	queryRequest, err := http.NewRequestWithContext(context.Background(), http.MethodPost, "https://www.googleapis.com/calendar/v3/freeBusy", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -63,6 +63,53 @@ func TestReadOnlyTransport(t *testing.T) {
 	}
 }
 
+func TestReadOnlyPOSTAllowlist(t *testing.T) {
+	allowed := []string{
+		"https://www.googleapis.com/calendar/v3/freeBusy",
+		"https://searchconsole.googleapis.com/webmasters/v3/sites/example/searchAnalytics/query",
+		"https://searchconsole.googleapis.com/v1/urlInspection/index:inspect",
+		"https://photoslibrary.googleapis.com/v1/mediaItems:search",
+		"https://sheets.googleapis.com/v4/spreadsheets/id/values:batchGetByDataFilter",
+		"https://driveactivity.googleapis.com/v2/activity:query",
+		"https://analyticsdata.googleapis.com/v1beta/properties/1:runReport",
+	}
+	for _, requestURL := range allowed {
+		request, err := http.NewRequestWithContext(context.Background(), http.MethodPost, requestURL, nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !readOnlyPOSTRequest(request) {
+			t.Errorf("readOnlyPOSTRequest(%q) = false, want true", requestURL)
+		}
+	}
+
+	blocked := []string{
+		"http://www.googleapis.com/calendar/v3/freeBusy",
+		"https://example.test/calendar/v3/freeBusy",
+		"https://www.googleapis.com/v2/activity:query",
+		"https://driveactivity.googleapis.com/v2/items:query",
+		"https://sheets.googleapis.com/v4/spreadsheets/id:batchUpdate",
+	}
+	for _, requestURL := range blocked {
+		request, err := http.NewRequestWithContext(context.Background(), http.MethodPost, requestURL, nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if readOnlyPOSTRequest(request) {
+			t.Errorf("readOnlyPOSTRequest(%q) = true, want false", requestURL)
+		}
+	}
+
+	override, err := http.NewRequestWithContext(context.Background(), http.MethodPost, "https://www.googleapis.com/calendar/v3/freeBusy", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	override.Header.Set("X-HTTP-Method-Override", http.MethodDelete)
+	if readOnlyHTTPRequest(override) {
+		t.Error("POST with X-HTTP-Method-Override unexpectedly allowed")
+	}
+}
+
 func TestReadOnlyTransportDisabled(t *testing.T) {
 	base := &readOnlyTestTransport{}
 	transport := readOnlyTransportFromContext(context.Background(), base)

From 1f9b59478fb0a9f3d449448b97afc2f358309b43 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 22 Jun 2026 13:22:27 -0400
Subject: [PATCH 3/7] fix(safety): cover auth setup and discovery writes

---
 docs/commands/gog-api-call.md     |  1 +
 docs/commands/gog-api-describe.md |  1 +
 docs/commands/gog-api-list.md     |  1 +
 docs/commands/gog-api.md          |  1 +
 docs/commands/gog-auth-setup.md   |  2 +-
 internal/cmd/api.go               |  3 +++
 internal/cmd/api_test.go          | 17 +++++++++++++++++
 internal/cmd/auth_setup.go        |  9 ++++++---
 internal/cmd/auth_setup_test.go   | 13 +++++++++++--
 9 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/docs/commands/gog-api-call.md b/docs/commands/gog-api-call.md
index d4d50916a..ebfe4cacb 100644
--- a/docs/commands/gog-api-call.md
+++ b/docs/commands/gog-api-call.md
@@ -36,6 +36,7 @@ gog api call <api> <version> <method> [flags]
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `--params` | `string` | {} | JSON object of path and query parameters |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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) |
 | `--scope` | `string` |  | OAuth scope override (default: narrowest Discovery-listed scope) |
 | `--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. |
diff --git a/docs/commands/gog-api-describe.md b/docs/commands/gog-api-describe.md
index 046ffbc46..a1d464b44 100644
--- a/docs/commands/gog-api-describe.md
+++ b/docs/commands/gog-api-describe.md
@@ -33,6 +33,7 @@ gog api describe <api> <version> [<method>]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-api-list.md b/docs/commands/gog-api-list.md
index 1e0e634b7..f0e01693e 100644
--- a/docs/commands/gog-api-list.md
+++ b/docs/commands/gog-api-list.md
@@ -34,6 +34,7 @@ gog api list [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-api.md b/docs/commands/gog-api.md
index ec05d4165..17d0eb0c2 100644
--- a/docs/commands/gog-api.md
+++ b/docs/commands/gog-api.md
@@ -39,6 +39,7 @@ gog api <command> [flags]
 | `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
 | `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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 |
diff --git a/docs/commands/gog-auth-setup.md b/docs/commands/gog-auth-setup.md
index 4a2fad516..a0b1a9510 100644
--- a/docs/commands/gog-auth-setup.md
+++ b/docs/commands/gog-auth-setup.md
@@ -41,7 +41,7 @@ gog auth setup [<email>] [flags]
 | `--open-console` | `bool` |  | Open the OAuth client page for the selected project |
 | `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
 | `--project-name` | `string` | gog CLI | Display name when creating a project |
-| `--readonly` | `bool` |  | Use read-only OAuth scopes when --login runs |
+| `--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. |
 | `--services` | `string` | gmail,calendar,drive,docs,sheets,contacts | Services to configure: comma-separated gmail,calendar,chat,classroom,drive,driveactivity,drivelabels,docs,slides,contacts,tasks,sheets,people,forms,sites,meet,appscript,analytics,searchconsole,ads,youtube,photos |
diff --git a/internal/cmd/api.go b/internal/cmd/api.go
index cbc48944a..ac76e4c31 100644
--- a/internal/cmd/api.go
+++ b/internal/cmd/api.go
@@ -121,6 +121,9 @@ func (c *APICallCmd) Run(ctx context.Context, flags *RootFlags) error {
 	if targetErr := discoveryapi.ValidateGoogleAPIURL(requestURL); targetErr != nil {
 		return usage(targetErr.Error())
 	}
+	if !read && googleapi.ReadOnly(ctx) {
+		return fmt.Errorf("%w: Discovery method %s uses %s", googleapi.ErrReadOnly, method.ID, method.Spec.HttpMethod)
+	}
 	if !read {
 		if confirmErr := confirmDestructiveChecked(ctx, flags, "invoke Discovery method "+method.ID); confirmErr != nil {
 			return confirmErr
diff --git a/internal/cmd/api_test.go b/internal/cmd/api_test.go
index 5734a86c2..785f9fd92 100644
--- a/internal/cmd/api_test.go
+++ b/internal/cmd/api_test.go
@@ -3,12 +3,14 @@ package cmd
 import (
 	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
 
+	"github.com/steipete/gogcli/internal/googleapi"
 	"github.com/steipete/gogcli/internal/outfmt"
 )
 
@@ -26,6 +28,21 @@ func TestAPICallRequiresWriteOptIn(t *testing.T) {
 	}
 }
 
+func TestAPICallReadOnlyBlocksWriteBeforeAuth(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = fmt.Fprint(w, `{"rootUrl":"https://gmail.googleapis.com/","servicePath":"gmail/v1/","resources":{"users":{"methods":{"stop":{"id":"gmail.users.stop","httpMethod":"POST","path":"users/{userId}/stop","parameters":{"userId":{"location":"path","required":true}},"scopes":["scope"]}}}}}`)
+	}))
+	t.Cleanup(server.Close)
+	t.Setenv("GOG_DISCOVERY_BASE_URL", server.URL)
+
+	ctx := googleapi.WithReadOnly(context.Background(), true)
+	err := (&APICallCmd{API: "gmail", Version: "v1", Method: "gmail.users.stop", ParamsJSON: `{"userId":"me"}`, AllowWrite: true}).Run(ctx, &RootFlags{ReadOnly: true, Force: true})
+	if !errors.Is(err, googleapi.ErrReadOnly) {
+		t.Fatalf("error = %v, want ErrReadOnly", err)
+	}
+}
+
 func TestAPICallRejectsNonGoogleTargetBeforeAuth(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
diff --git a/internal/cmd/auth_setup.go b/internal/cmd/auth_setup.go
index 2c06b7982..2cc74cd73 100644
--- a/internal/cmd/auth_setup.go
+++ b/internal/cmd/auth_setup.go
@@ -11,6 +11,7 @@ import (
 
 	"github.com/steipete/gogcli/internal/authclient"
 	"github.com/steipete/gogcli/internal/config"
+	"github.com/steipete/gogcli/internal/googleapi"
 	"github.com/steipete/gogcli/internal/googleauth"
 	"github.com/steipete/gogcli/internal/outfmt"
 	"github.com/steipete/gogcli/internal/ui"
@@ -25,7 +26,6 @@ type AuthSetupCmd struct {
 	CreateProject bool   `name:"create-project" help:"Create --gcloud-project with gcloud (requires confirmation)"`
 	EnableAPIs    bool   `name:"enable-apis" help:"Enable selected Google APIs with gcloud"`
 	Login         bool   `name:"login" help:"Run browser OAuth after project/client setup"`
-	Readonly      bool   `name:"readonly" help:"Use read-only OAuth scopes when --login runs"`
 	ForceConsent  bool   `name:"force-consent" help:"Force OAuth consent when --login runs"`
 	OpenConsole   bool   `name:"open-console" help:"Open the OAuth client page for the selected project"`
 }
@@ -43,6 +43,7 @@ type authSetupResult struct {
 }
 
 func (c *AuthSetupCmd) Run(ctx context.Context, flags *RootFlags) error {
+	readonly := readOnlyEnabled(flags)
 	services, err := parseAuthServices(c.ServicesCSV)
 	if err != nil {
 		return err
@@ -77,6 +78,9 @@ func (c *AuthSetupCmd) Run(ctx context.Context, flags *RootFlags) error {
 	if c.OpenConsole && project == "" {
 		return usage("--open-console requires --gcloud-project or an active gcloud project")
 	}
+	if readonly && (c.CreateProject || c.EnableAPIs) && (flags == nil || !flags.DryRun) {
+		return fmt.Errorf("%w: auth setup project/API mutations are disabled", googleapi.ErrReadOnly)
+	}
 	if (c.CreateProject || c.EnableAPIs) && !gcloudAvailable && (flags == nil || !flags.DryRun) {
 		return usage("gcloud is required for --create-project or --enable-apis; install it or omit those flags for manual guidance")
 	}
@@ -99,7 +103,7 @@ func (c *AuthSetupCmd) Run(ctx context.Context, flags *RootFlags) error {
 		"enable_apis":      c.EnableAPIs,
 		"credentials_file": strings.TrimSpace(c.Credentials),
 		"login_email":      strings.TrimSpace(c.Email),
-		"readonly":         c.Readonly,
+		"readonly":         readonly,
 		"force_consent":    c.ForceConsent,
 		"open_console":     c.OpenConsole,
 	}
@@ -157,7 +161,6 @@ func (c *AuthSetupCmd) Run(ctx context.Context, flags *RootFlags) error {
 		return (&AuthAddCmd{
 			Email:        strings.TrimSpace(c.Email),
 			ServicesCSV:  c.ServicesCSV,
-			Readonly:     c.Readonly,
 			ForceConsent: c.ForceConsent,
 		}).Run(ctx, flags)
 	}
diff --git a/internal/cmd/auth_setup_test.go b/internal/cmd/auth_setup_test.go
index c7497c29e..e5c50b110 100644
--- a/internal/cmd/auth_setup_test.go
+++ b/internal/cmd/auth_setup_test.go
@@ -4,10 +4,12 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 
 	"github.com/steipete/gogcli/internal/authclient"
+	"github.com/steipete/gogcli/internal/googleapi"
 	"github.com/steipete/gogcli/internal/googleauth"
 )
 
@@ -22,8 +24,7 @@ func TestAuthSetupDryRun(t *testing.T) {
 		EnableAPIs:    true,
 		Credentials:   "/tmp/client.json",
 		Login:         true,
-		Readonly:      true,
-	}).Run(ctx, &RootFlags{DryRun: true, NoInput: true})
+	}).Run(ctx, &RootFlags{DryRun: true, NoInput: true, ReadOnly: true})
 	if ExitCode(err) != 0 {
 		t.Fatalf("exit code = %d, want 0: %v", ExitCode(err), err)
 	}
@@ -103,6 +104,14 @@ func TestAuthSetupValidation(t *testing.T) {
 	}
 }
 
+func TestAuthSetupReadOnlyBlocksGcloudMutations(t *testing.T) {
+	t.Setenv("PATH", t.TempDir())
+	err := (&AuthSetupCmd{Project: "valid-project", CreateProject: true}).Run(context.Background(), &RootFlags{ReadOnly: true})
+	if !errors.Is(err, googleapi.ErrReadOnly) {
+		t.Fatalf("error = %v, want ErrReadOnly", err)
+	}
+}
+
 func TestAPIServiceIDsForServices(t *testing.T) {
 	got, err := googleauth.APIServiceIDsForServices([]googleauth.Service{
 		googleauth.ServiceSheets,

From e40fc19d5acdb595f4bf37a38b2c34d5a6e38d15 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 22 Jun 2026 13:26:00 -0400
Subject: [PATCH 4/7] fix(safety): align discovery query classification

---
 internal/cmd/api.go                  | 10 +++++-----
 internal/cmd/api_test.go             | 17 +++++++++++++++++
 internal/googleapi/read_only.go      |  5 +++--
 internal/googleapi/read_only_test.go |  2 +-
 4 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/internal/cmd/api.go b/internal/cmd/api.go
index ac76e4c31..25092ba95 100644
--- a/internal/cmd/api.go
+++ b/internal/cmd/api.go
@@ -109,8 +109,12 @@ func (c *APICallCmd) Run(ctx context.Context, flags *RootFlags) error {
 	if err != nil {
 		return err
 	}
+	request, err := discoveryapi.NewRequest(ctx, method.Spec.HttpMethod, requestURL, body)
+	if err != nil {
+		return fmt.Errorf("build API request: %w", err)
+	}
 
-	read := method.Spec.HttpMethod == http.MethodGet || method.Spec.HttpMethod == http.MethodHead
+	read := googleapi.ReadOnlyRequestAllowed(request)
 	if !read && !c.AllowWrite {
 		return usagef("method %s uses %s; pass --allow-write to opt in", method.ID, method.Spec.HttpMethod)
 	}
@@ -146,10 +150,6 @@ func (c *APICallCmd) Run(ctx context.Context, flags *RootFlags) error {
 		return err
 	}
 	httpClient.CheckRedirect = validateDiscoveryRedirect
-	request, err := discoveryapi.NewRequest(ctx, method.Spec.HttpMethod, requestURL, body)
-	if err != nil {
-		return fmt.Errorf("build API request: %w", err)
-	}
 	response, err := httpClient.Do(request)
 	if err != nil {
 		return fmt.Errorf("call %s: %w", method.ID, err)
diff --git a/internal/cmd/api_test.go b/internal/cmd/api_test.go
index 785f9fd92..492c0956d 100644
--- a/internal/cmd/api_test.go
+++ b/internal/cmd/api_test.go
@@ -43,6 +43,23 @@ func TestAPICallReadOnlyBlocksWriteBeforeAuth(t *testing.T) {
 	}
 }
 
+func TestAPICallReadOnlyAllowsQueryPOSTDryRun(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = fmt.Fprint(w, `{"rootUrl":"https://www.googleapis.com/","servicePath":"calendar/v3/","resources":{"freebusy":{"methods":{"query":{"id":"calendar.freebusy.query","httpMethod":"POST","path":"freeBusy","scopes":["scope"]}}}}}`)
+	}))
+	t.Cleanup(server.Close)
+	t.Setenv("GOG_DISCOVERY_BASE_URL", server.URL)
+
+	var stdout bytes.Buffer
+	ctx := newCmdRuntimeJSONOutputContext(t, &stdout, &bytes.Buffer{})
+	ctx = googleapi.WithReadOnly(ctx, true)
+	err := (&APICallCmd{API: "calendar", Version: "v3", Method: "calendar.freebusy.query"}).Run(ctx, &RootFlags{ReadOnly: true, DryRun: true, NoInput: true})
+	if ExitCode(err) != 0 {
+		t.Fatalf("query POST dry-run exit code = %d: %v", ExitCode(err), err)
+	}
+}
+
 func TestAPICallRejectsNonGoogleTargetBeforeAuth(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
diff --git a/internal/googleapi/read_only.go b/internal/googleapi/read_only.go
index 45541ff52..674ae1d7f 100644
--- a/internal/googleapi/read_only.go
+++ b/internal/googleapi/read_only.go
@@ -47,7 +47,7 @@ func readOnlyTransportFromContext(ctx context.Context, base http.RoundTripper) h
 }
 
 func (t *readOnlyTransport) RoundTrip(request *http.Request) (*http.Response, error) {
-	if !readOnlyHTTPRequest(request) {
+	if !ReadOnlyRequestAllowed(request) {
 		method := ""
 		path := ""
 
@@ -69,7 +69,8 @@ func (t *readOnlyTransport) RoundTrip(request *http.Request) (*http.Response, er
 	return response, nil
 }
 
-func readOnlyHTTPRequest(request *http.Request) bool {
+// ReadOnlyRequestAllowed reports whether request is safe under runtime read-only enforcement.
+func ReadOnlyRequestAllowed(request *http.Request) bool {
 	if request == nil || request.URL == nil {
 		return false
 	}
diff --git a/internal/googleapi/read_only_test.go b/internal/googleapi/read_only_test.go
index 2d8ea4ca0..6e9790019 100644
--- a/internal/googleapi/read_only_test.go
+++ b/internal/googleapi/read_only_test.go
@@ -105,7 +105,7 @@ func TestReadOnlyPOSTAllowlist(t *testing.T) {
 		t.Fatal(err)
 	}
 	override.Header.Set("X-HTTP-Method-Override", http.MethodDelete)
-	if readOnlyHTTPRequest(override) {
+	if ReadOnlyRequestAllowed(override) {
 		t.Error("POST with X-HTTP-Method-Override unexpectedly allowed")
 	}
 }

From d4449759ca3d58ff435eec5d5d8e332b8c0cff49 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 22 Jun 2026 13:27:25 -0400
Subject: [PATCH 5/7] style(safety): satisfy readonly lint checks

---
 internal/googleapi/read_only.go      | 1 +
 internal/googleapi/read_only_test.go | 4 ++++
 2 files changed, 5 insertions(+)

diff --git a/internal/googleapi/read_only.go b/internal/googleapi/read_only.go
index 674ae1d7f..9cf2a728e 100644
--- a/internal/googleapi/read_only.go
+++ b/internal/googleapi/read_only.go
@@ -74,6 +74,7 @@ func ReadOnlyRequestAllowed(request *http.Request) bool {
 	if request == nil || request.URL == nil {
 		return false
 	}
+
 	if strings.TrimSpace(request.Header.Get("X-HTTP-Method-Override")) != "" {
 		return false
 	}
diff --git a/internal/googleapi/read_only_test.go b/internal/googleapi/read_only_test.go
index 6e9790019..ebc971180 100644
--- a/internal/googleapi/read_only_test.go
+++ b/internal/googleapi/read_only_test.go
@@ -78,6 +78,7 @@ func TestReadOnlyPOSTAllowlist(t *testing.T) {
 		if err != nil {
 			t.Fatal(err)
 		}
+
 		if !readOnlyPOSTRequest(request) {
 			t.Errorf("readOnlyPOSTRequest(%q) = false, want true", requestURL)
 		}
@@ -95,6 +96,7 @@ func TestReadOnlyPOSTAllowlist(t *testing.T) {
 		if err != nil {
 			t.Fatal(err)
 		}
+
 		if readOnlyPOSTRequest(request) {
 			t.Errorf("readOnlyPOSTRequest(%q) = true, want false", requestURL)
 		}
@@ -104,7 +106,9 @@ func TestReadOnlyPOSTAllowlist(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
+
 	override.Header.Set("X-HTTP-Method-Override", http.MethodDelete)
+
 	if ReadOnlyRequestAllowed(override) {
 		t.Error("POST with X-HTTP-Method-Override unexpectedly allowed")
 	}

From 05731694cd5a28ef812879c25639271211fe4bd4 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 22 Jun 2026 13:30:28 -0400
Subject: [PATCH 6/7] fix(auth): preserve readonly setup guidance

---
 internal/cmd/auth_setup.go      | 12 ++++++++----
 internal/cmd/auth_setup_test.go |  4 ++--
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/internal/cmd/auth_setup.go b/internal/cmd/auth_setup.go
index 2cc74cd73..95dbca97d 100644
--- a/internal/cmd/auth_setup.go
+++ b/internal/cmd/auth_setup.go
@@ -156,7 +156,7 @@ func (c *AuthSetupCmd) Run(ctx context.Context, flags *RootFlags) error {
 		}
 	}
 
-	result.NextSteps = authSetupNextSteps(c, result, gcloudAvailable, authclient.ClientOverrideFromContext(ctx))
+	result.NextSteps = authSetupNextSteps(c, result, gcloudAvailable, authclient.ClientOverrideFromContext(ctx), readonly)
 	if c.Login {
 		return (&AuthAddCmd{
 			Email:        strings.TrimSpace(c.Email),
@@ -207,7 +207,7 @@ func authSetupClient(ctx context.Context, email string) (string, error) {
 	return normalizeClientForFlag(override)
 }
 
-func authSetupNextSteps(c *AuthSetupCmd, result authSetupResult, gcloudAvailable bool, clientOverride string) []string {
+func authSetupNextSteps(c *AuthSetupCmd, result authSetupResult, gcloudAvailable bool, clientOverride string, readonly bool) []string {
 	steps := make([]string, 0, 6)
 	gogCommand := "gog"
 	if client := strings.TrimSpace(clientOverride); client != "" {
@@ -229,10 +229,14 @@ func authSetupNextSteps(c *AuthSetupCmd, result authSetupResult, gcloudAvailable
 	if !result.CredentialsSaved {
 		steps = append(steps, "Store the download with `"+gogCommand+" auth credentials /path/to/client_secret.json`")
 	}
+	authCommand := gogCommand
+	if readonly {
+		authCommand += " --readonly"
+	}
 	if strings.TrimSpace(c.Email) != "" {
-		steps = append(steps, fmt.Sprintf("Authorize with `%s auth add %s --services %s`", gogCommand, strings.TrimSpace(c.Email), strings.Join(result.Services, ",")))
+		steps = append(steps, fmt.Sprintf("Authorize with `%s auth add %s --services %s`", authCommand, strings.TrimSpace(c.Email), strings.Join(result.Services, ",")))
 	} else {
-		steps = append(steps, "Authorize with `"+gogCommand+" auth add you@example.com --services "+strings.Join(result.Services, ",")+"`")
+		steps = append(steps, "Authorize with `"+authCommand+" auth add you@example.com --services "+strings.Join(result.Services, ",")+"`")
 	}
 	steps = append(steps, "Verify with `gog auth doctor --check`")
 	return steps
diff --git a/internal/cmd/auth_setup_test.go b/internal/cmd/auth_setup_test.go
index e5c50b110..80ba142e1 100644
--- a/internal/cmd/auth_setup_test.go
+++ b/internal/cmd/auth_setup_test.go
@@ -55,9 +55,9 @@ func TestAuthSetupGuidance(t *testing.T) {
 		Project:  "gog-test-project",
 		Services: []string{"gmail", "drive"},
 	}
-	steps := authSetupNextSteps(&AuthSetupCmd{Email: "user@example.com"}, result, true, "work")
+	steps := authSetupNextSteps(&AuthSetupCmd{Email: "user@example.com"}, result, true, "work", true)
 	joined := strings.Join(steps, "\n")
-	for _, want := range []string{"auth/branding?project=gog-test-project", "auth/clients?project=gog-test-project", "gog --client work auth credentials", "gog --client work auth add user@example.com --services gmail,drive", "gog auth doctor --check"} {
+	for _, want := range []string{"auth/branding?project=gog-test-project", "auth/clients?project=gog-test-project", "gog --client work auth credentials", "gog --client work --readonly auth add user@example.com --services gmail,drive", "gog auth doctor --check"} {
 		if !strings.Contains(joined, want) {
 			t.Fatalf("guidance missing %q:\n%s", want, joined)
 		}

From 557b1d28e78be49a7e7ce1bac0696db66d975e2c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 22 Jun 2026 13:32:54 -0400
Subject: [PATCH 7/7] style(auth): scope gcloud lint suppression

---
 internal/cmd/auth_setup.go | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/internal/cmd/auth_setup.go b/internal/cmd/auth_setup.go
index 95dbca97d..8c013cbdc 100644
--- a/internal/cmd/auth_setup.go
+++ b/internal/cmd/auth_setup.go
@@ -286,8 +286,9 @@ func authSetupGcloudValue(ctx context.Context, key string) (string, error) {
 	return value, nil
 }
 
+//nolint:gosec // Fixed gcloud binary; arguments are validated or generated.
 func authSetupRunGcloud(ctx context.Context, args ...string) (string, error) {
-	command := exec.CommandContext(ctx, authSetupGcloudBinary(), args...) //nolint:gosec // fixed gcloud binary; arguments are validated or generated
+	command := exec.CommandContext(ctx, authSetupGcloudBinary(), args...)
 	command.Env = append(os.Environ(), "CLOUDSDK_CORE_DISABLE_PROMPTS=1")
 	output, err := command.CombinedOutput()
 	if err != nil {