gogcli-mcp-docs 2.7.1 → 2.8.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
-    "version": "2.7.1"
+    "version": "2.8.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli (Docs)",
       "source": "./",
       "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
-      "version": "2.7.1",
+      "version": "2.8.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp-docs",
   "displayName": "gogcli (Docs)",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",

package/dist/index.js

@@ -31277,12 +31277,14 @@ function registerDocsTools(server2) {
       text: external_exports.string().describe("Text content to write"),
       append: external_exports.boolean().optional().describe("Append to existing content instead of replacing (default: false)"),
       checkOrphans: external_exports.boolean().optional().describe("Block the write (exit code 11) if it would orphan an open comment \u2014 i.e. remove the text the comment is anchored to. Recommended for replacement writes on commented docs."),
+      batch: external_exports.string().optional().describe("Append this mutation to a persisted batch (from gog_batch_begin in gogcli-mcp-docs) instead of applying it \u2014 nothing changes in the doc until the batch is submitted."),
       account: accountParam
     }
-  }, async ({ docId, text, append, checkOrphans, account }) => {
+  }, async ({ docId, text, append, checkOrphans, batch, account }) => {
     const args = ["docs", "write", docId, `--text=${text}`];
     if (append) args.push("--append");
     if (checkOrphans) args.push("--check-orphans");
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_find_replace", {
@@ -31320,7 +31322,7 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.7.1" : "0.0.0";
+var VERSION = true ? "2.8.0" : "0.0.0";
 function createServer(options) {
   return new McpServer({
     name: options?.name ?? "gogcli",
@@ -31354,9 +31356,10 @@ function registerExtraDocsTools(server2) {
       occurrence: external_exports.number().int().optional().describe("Use the Nth `at` match (1-based; required when `at` is ambiguous)"),
       matchCase: external_exports.boolean().optional().describe("Case-sensitive `at` matching"),
       tabId: external_exports.string().optional().describe("Tab ID to delete content from (for multi-tab docs)"),
+      batch: external_exports.string().optional().describe("Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it \u2014 nothing changes in the doc until gog_batch_end submits the batch."),
       account: accountParam
     }
-  }, async ({ docId, start, end, at, occurrence, matchCase, tabId, account }) => {
+  }, async ({ docId, start, end, at, occurrence, matchCase, tabId, batch, account }) => {
     const args = ["docs", "delete"];
     if (start !== void 0) args.push(`--start=${start}`);
     if (end !== void 0) args.push(`--end=${end}`);
@@ -31365,6 +31368,7 @@ function registerExtraDocsTools(server2) {
     if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push("--match-case");
     if (tabId) args.push(`--tab-id=${tabId}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_trash", {
@@ -31444,6 +31448,7 @@ function registerExtraDocsTools(server2) {
       lineSpacing: external_exports.number().optional().describe("Line spacing percentage (e.g. 100 for single, 150 for 1.5x, 200 for double)"),
       headingLevel: external_exports.number().int().optional().describe("Set paragraph named style to HEADING_1..HEADING_6 (shortcut for namedStyle=HEADING_N)"),
       namedStyle: external_exports.enum(["NORMAL_TEXT", "TITLE", "SUBTITLE", "HEADING_1", "HEADING_2", "HEADING_3", "HEADING_4", "HEADING_5", "HEADING_6"]).optional().describe("Set paragraph named style explicitly"),
+      batch: external_exports.string().optional().describe("Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it \u2014 nothing changes in the doc until gog_batch_end submits the batch."),
       account: accountParam
     }
   }, async (args) => {
@@ -31472,6 +31477,7 @@ function registerExtraDocsTools(server2) {
     if (a.lineSpacing !== void 0) argv.push(`--line-spacing=${a.lineSpacing}`);
     if (a.headingLevel !== void 0) argv.push(`--heading-level=${a.headingLevel}`);
     if (a.namedStyle) argv.push(`--named-style=${a.namedStyle}`);
+    if (a.batch) argv.push(`--batch=${a.batch}`);
     return runOrDiagnose(argv, { account: a.account });
   });
   server2.registerTool("gog_docs_export", {
@@ -31501,9 +31507,10 @@ function registerExtraDocsTools(server2) {
       occurrence: external_exports.number().int().optional().describe("Use the Nth `at` match (1-based; required when `at` is ambiguous)"),
       matchCase: external_exports.boolean().optional().describe("Case-sensitive `at` matching"),
       tabId: external_exports.string().optional().describe("Tab ID to insert into (for multi-tab docs)"),
+      batch: external_exports.string().optional().describe("Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it \u2014 nothing changes in the doc until gog_batch_end submits the batch."),
       account: accountParam
     }
-  }, async ({ docId, content, index, file: file2, at, occurrence, matchCase, tabId, account }) => {
+  }, async ({ docId, content, index, file: file2, at, occurrence, matchCase, tabId, batch, account }) => {
     const args = ["docs", "insert", docId];
     if (content) args.push(content);
     if (index !== void 0) args.push(`--index=${index}`);
@@ -31512,6 +31519,7 @@ function registerExtraDocsTools(server2) {
     if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push("--match-case");
     if (tabId) args.push(`--tab-id=${tabId}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_append", {
@@ -31581,9 +31589,10 @@ function registerExtraDocsTools(server2) {
       matchCase: external_exports.boolean().optional().describe("Case-sensitive `at` matching"),
       tabId: external_exports.string().optional().describe("Tab ID for multi-tab docs"),
       pageless: external_exports.boolean().optional().describe("Set document to pageless format"),
+      batch: external_exports.string().optional().describe("Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it \u2014 nothing changes in the doc until gog_batch_end submits the batch."),
       account: accountParam
     }
-  }, async ({ docId, text, file: file2, index, replaceRange, markdown, at, occurrence, matchCase, tabId, pageless, account }) => {
+  }, async ({ docId, text, file: file2, index, replaceRange, markdown, at, occurrence, matchCase, tabId, pageless, batch, account }) => {
     const args = ["docs", "update", docId];
     if (text) args.push(`--text=${text}`);
     if (file2) args.push(`--file=${file2}`);
@@ -31595,6 +31604,7 @@ function registerExtraDocsTools(server2) {
     if (matchCase) args.push("--match-case");
     if (tabId) args.push(`--tab-id=${tabId}`);
     if (pageless) args.push("--pageless");
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_comments_list", {
@@ -31727,6 +31737,74 @@ function registerExtraDocsTools(server2) {
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });
+  server2.registerTool("gog_batch_begin", {
+    description: "Open a persisted, revision-locked request batch for a Google Doc. Subsequent docs mutation tools called with batch=<batchId> append their requests locally instead of applying them; gog_batch_end submits everything atomically. Returns the batchId.",
+    inputSchema: {
+      docId: external_exports.string().describe("Google Doc ID the batch is locked to"),
+      name: external_exports.string().optional().describe("Optional batch label"),
+      account: accountParam
+    }
+  }, async ({ docId, name, account }) => {
+    const args = ["batch", "begin", `--doc=${docId}`];
+    if (name) args.push(`--name=${name}`);
+    return runOrDiagnose(args, { account });
+  });
+  server2.registerTool("gog_batch_end", {
+    description: "Submit a persisted batch: applies every composed request to the doc in one atomic batchUpdate against the locked revision. Atomic by default \u2014 set autoSplit to submit >500-request batches as ordered chunks (non-atomic), or continueOnError to retry individually after an atomic validation failure, retaining failures in the batch.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      batchId: external_exports.string().describe("Batch ID (from gog_batch_begin)"),
+      autoSplit: external_exports.boolean().optional().describe("Submit batches over 500 requests as ordered chunks (non-atomic)"),
+      continueOnError: external_exports.boolean().optional().describe("After an atomic validation failure, submit requests individually and retain failures"),
+      account: accountParam
+    }
+  }, async ({ batchId, autoSplit, continueOnError, account }) => {
+    const args = ["batch", "end", batchId];
+    if (autoSplit) args.push("--auto-split");
+    if (continueOnError) args.push("--continue-on-error");
+    return runOrDiagnose(args, { account });
+  });
+  server2.registerTool("gog_batch_abort", {
+    description: "Discard a persisted batch and its composed requests without applying anything to the doc.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      batchId: external_exports.string().describe("Batch ID to discard"),
+      account: accountParam
+    }
+  }, async ({ batchId, account }) => {
+    return runOrDiagnose(["batch", "abort", batchId], { account });
+  });
+  server2.registerTool("gog_batch_list", {
+    description: "List persisted Docs request batches (id, doc, label, request count, status).",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      account: accountParam
+    }
+  }, async ({ account }) => {
+    return runOrDiagnose(["batch", "list"], { account });
+  });
+  server2.registerTool("gog_batch_show", {
+    description: "Show one persisted batch: its doc, locked revision, and the composed requests awaiting submission.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      batchId: external_exports.string().describe("Batch ID"),
+      account: accountParam
+    }
+  }, async ({ batchId, account }) => {
+    return runOrDiagnose(["batch", "show", batchId], { account });
+  });
+  server2.registerTool("gog_batch_prune", {
+    description: "Delete stale persisted batches (not updated within olderThan).",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      olderThan: external_exports.string().optional().describe("Delete batches not updated within this duration (e.g. 72h, 7d)"),
+      account: accountParam
+    }
+  }, async ({ olderThan, account }) => {
+    const args = ["batch", "prune"];
+    if (olderThan) args.push(`--older-than=${olderThan}`);
+    return runOrDiagnose(args, { account });
+  });
   server2.registerTool("gog_docs_table_column_width", {
     description: "Set a fixed width (in points) for a table column, or reset columns to Docs-managed even distribution. Target the table by 1-based index in document order (negative counts from the end) and the column by 1-based number. Pass evenlyDistributed without col to reset every column in the table.",
     annotations: { destructiveHint: true },
@@ -31737,15 +31815,17 @@ function registerExtraDocsTools(server2) {
       evenlyDistributed: external_exports.boolean().optional().describe("Reset the selected column (or all columns when col is omitted) to Docs-managed equal width."),
       tableIndex: external_exports.number().int().optional().describe("1-based table index in document order; negative counts from the end (default: 1)"),
       tab: external_exports.string().optional().describe("Target tab title or ID"),
+      batch: external_exports.string().optional().describe("Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it \u2014 nothing changes in the doc until gog_batch_end submits the batch."),
       account: accountParam
     }
-  }, async ({ docId, col, width, evenlyDistributed, tableIndex, tab, account }) => {
+  }, async ({ docId, col, width, evenlyDistributed, tableIndex, tab, batch, account }) => {
     const args = ["docs", "table-column-width", docId];
     if (col !== void 0) args.push(`--col=${col}`);
     if (width !== void 0) args.push(`--width=${width}`);
     if (evenlyDistributed) args.push("--evenly-distributed");
     if (tableIndex !== void 0) args.push(`--table-index=${tableIndex}`);
     if (tab) args.push(`--tab=${tab}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
   const tableSelectorParam = external_exports.string().optional().describe("Table selector: 1-based index (negative from the end), exact first-cell text, * for the only table, or text:VALUE for numeric/syntax-looking first-cell text (default: 1)");
@@ -31983,9 +32063,10 @@ function registerExtraDocsTools(server2) {
       occurrence: external_exports.number().int().optional().describe("Use the Nth `at` match (1-based; required when `at` is ambiguous)"),
       matchCase: external_exports.boolean().optional().describe("Case-sensitive `at` matching"),
       tab: external_exports.string().optional().describe("Target a specific tab by title or ID"),
+      batch: external_exports.string().optional().describe("Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it \u2014 nothing changes in the doc until gog_batch_end submits the batch."),
       account: accountParam
     }
-  }, async ({ docId, index, atEnd, at, occurrence, matchCase, tab, account }) => {
+  }, async ({ docId, index, atEnd, at, occurrence, matchCase, tab, batch, account }) => {
     const args = ["docs", "insert-page-break", docId];
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
@@ -31993,6 +32074,7 @@ function registerExtraDocsTools(server2) {
     if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push("--match-case");
     if (tab) args.push(`--tab=${tab}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_page_layout", {
@@ -32084,9 +32166,10 @@ function registerExtraDocsTools(server2) {
       underline: external_exports.boolean().optional().describe("Set cell text underline"),
       tableIndex: external_exports.number().int().optional().describe("0-based table index in document order (default: 0)"),
       tab: external_exports.string().optional().describe("Target a specific tab by title or ID"),
+      batch: external_exports.string().optional().describe("Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it \u2014 nothing changes in the doc until gog_batch_end submits the batch."),
       account: accountParam
     }
-  }, async ({ docId, row, col, rowSpan, colSpan, backgroundColor, textColor, bold, italic, underline, tableIndex, tab, account }) => {
+  }, async ({ docId, row, col, rowSpan, colSpan, backgroundColor, textColor, bold, italic, underline, tableIndex, tab, batch, account }) => {
     const args = ["docs", "cell-style", docId, `--row=${row}`, `--col=${col}`];
     if (rowSpan !== void 0) args.push(`--row-span=${rowSpan}`);
     if (colSpan !== void 0) args.push(`--col-span=${colSpan}`);
@@ -32097,6 +32180,7 @@ function registerExtraDocsTools(server2) {
     if (underline) args.push("--underline");
     if (tableIndex !== void 0) args.push(`--table-index=${tableIndex}`);
     if (tab) args.push(`--tab=${tab}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_insert_image", {
@@ -32140,9 +32224,10 @@ function registerExtraDocsTools(server2) {
       occurrence: external_exports.number().int().optional().describe("Use the Nth `at` match (1-based; required when `at` is ambiguous)"),
       matchCase: external_exports.boolean().optional().describe("Case-sensitive `at` matching"),
       tab: external_exports.string().optional().describe("Target a specific tab by title or ID"),
+      batch: external_exports.string().optional().describe("Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it \u2014 nothing changes in the doc until gog_batch_end submits the batch."),
       account: accountParam
     }
-  }, async ({ docId, email: email3, index, atEnd, at, occurrence, matchCase, tab, account }) => {
+  }, async ({ docId, email: email3, index, atEnd, at, occurrence, matchCase, tab, batch, account }) => {
     const args = ["docs", "insert-person", docId, `--email=${email3}`];
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
@@ -32150,6 +32235,7 @@ function registerExtraDocsTools(server2) {
     if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push("--match-case");
     if (tab) args.push(`--tab=${tab}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_insert_date_chip", {
@@ -32162,15 +32248,17 @@ function registerExtraDocsTools(server2) {
       index: external_exports.number().int().optional().describe("Character index to insert at. Omit or use atEnd for end-of-doc."),
       atEnd: external_exports.boolean().optional().describe("Insert at end-of-doc/tab (mutually exclusive with index)"),
       tab: external_exports.string().optional().describe("Target a specific tab by title or ID"),
+      batch: external_exports.string().optional().describe("Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it \u2014 nothing changes in the doc until gog_batch_end submits the batch."),
       account: accountParam
     }
-  }, async ({ docId, date: date5, format, index, atEnd, tab, account }) => {
+  }, async ({ docId, date: date5, format, index, atEnd, tab, batch, account }) => {
     const args = ["docs", "insert-date-chip", docId];
     if (date5) args.push(`--date=${date5}`);
     if (format) args.push(`--format=${format}`);
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
     if (tab) args.push(`--tab=${tab}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_add_tab", {

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",
@@ -203,6 +203,30 @@
       "name": "gog_docs_find_range",
       "description": "Map literal text to its Docs API UTF-16 index range(s) for index-based edits."
     },
+    {
+      "name": "gog_batch_begin",
+      "description": "Open a persisted, revision-locked request batch for a Doc; compose mutations with batch=<id>."
+    },
+    {
+      "name": "gog_batch_end",
+      "description": "Submit a batch atomically (or with explicit split / partial-recovery modes)."
+    },
+    {
+      "name": "gog_batch_abort",
+      "description": "Discard a batch without applying anything."
+    },
+    {
+      "name": "gog_batch_list",
+      "description": "List persisted request batches."
+    },
+    {
+      "name": "gog_batch_show",
+      "description": "Show a batch's doc, locked revision, and composed requests."
+    },
+    {
+      "name": "gog_batch_prune",
+      "description": "Delete stale batches not updated within a duration."
+    },
     {
       "name": "gog_docs_table_column_width",
       "description": "Set a fixed table column width in points, or reset columns to Docs-managed even distribution."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-docs",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-docs",
   "description": "Extended Google Docs MCP server via gogcli — all base tools plus full Docs support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp-docs"
   },
-  "version": "2.7.1",
+  "version": "2.8.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp-docs",
-      "version": "2.7.1",
+      "version": "2.8.0",
       "transport": {
         "type": "stdio"
       },

package/src/tools/docs-extra.ts

@@ -28,9 +28,10 @@ export function registerExtraDocsTools(server: McpServer): void {
       occurrence: z.number().int().optional().describe('Use the Nth `at` match (1-based; required when `at` is ambiguous)'),
       matchCase: z.boolean().optional().describe('Case-sensitive `at` matching'),
       tabId: z.string().optional().describe('Tab ID to delete content from (for multi-tab docs)'),
+      batch: z.string().optional().describe('Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it — nothing changes in the doc until gog_batch_end submits the batch.'),
       account: accountParam,
     },
-  }, async ({ docId, start, end, at, occurrence, matchCase, tabId, account }) => {
+  }, async ({ docId, start, end, at, occurrence, matchCase, tabId, batch, account }) => {
     const args = ['docs', 'delete'];
     if (start !== undefined) args.push(`--start=${start}`);
     if (end !== undefined) args.push(`--end=${end}`);
@@ -39,6 +40,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     if (occurrence !== undefined) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push('--match-case');
     if (tabId) args.push(`--tab-id=${tabId}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
 
@@ -122,6 +124,7 @@ export function registerExtraDocsTools(server: McpServer): void {
       lineSpacing: z.number().optional().describe('Line spacing percentage (e.g. 100 for single, 150 for 1.5x, 200 for double)'),
       headingLevel: z.number().int().optional().describe('Set paragraph named style to HEADING_1..HEADING_6 (shortcut for namedStyle=HEADING_N)'),
       namedStyle: z.enum(['NORMAL_TEXT', 'TITLE', 'SUBTITLE', 'HEADING_1', 'HEADING_2', 'HEADING_3', 'HEADING_4', 'HEADING_5', 'HEADING_6']).optional().describe('Set paragraph named style explicitly'),
+      batch: z.string().optional().describe('Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it — nothing changes in the doc until gog_batch_end submits the batch.'),
       account: accountParam,
     },
   }, async (args) => {
@@ -142,6 +145,7 @@ export function registerExtraDocsTools(server: McpServer): void {
       code?: boolean;
       link?: string; noLink?: boolean;
       alignment?: string;
+      batch?: string;
       lineSpacing?: number;
       headingLevel?: number;
       namedStyle?: string;
@@ -171,6 +175,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     if (a.lineSpacing !== undefined) argv.push(`--line-spacing=${a.lineSpacing}`);
     if (a.headingLevel !== undefined) argv.push(`--heading-level=${a.headingLevel}`);
     if (a.namedStyle) argv.push(`--named-style=${a.namedStyle}`);
+    if (a.batch) argv.push(`--batch=${a.batch}`);
     return runOrDiagnose(argv, { account: a.account });
   });
 
@@ -202,9 +207,10 @@ export function registerExtraDocsTools(server: McpServer): void {
       occurrence: z.number().int().optional().describe('Use the Nth `at` match (1-based; required when `at` is ambiguous)'),
       matchCase: z.boolean().optional().describe('Case-sensitive `at` matching'),
       tabId: z.string().optional().describe('Tab ID to insert into (for multi-tab docs)'),
+      batch: z.string().optional().describe('Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it — nothing changes in the doc until gog_batch_end submits the batch.'),
       account: accountParam,
     },
-  }, async ({ docId, content, index, file, at, occurrence, matchCase, tabId, account }) => {
+  }, async ({ docId, content, index, file, at, occurrence, matchCase, tabId, batch, account }) => {
     const args = ['docs', 'insert', docId];
     if (content) args.push(content);
     if (index !== undefined) args.push(`--index=${index}`);
@@ -213,6 +219,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     if (occurrence !== undefined) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push('--match-case');
     if (tabId) args.push(`--tab-id=${tabId}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
 
@@ -286,9 +293,10 @@ export function registerExtraDocsTools(server: McpServer): void {
       matchCase: z.boolean().optional().describe('Case-sensitive `at` matching'),
       tabId: z.string().optional().describe('Tab ID for multi-tab docs'),
       pageless: z.boolean().optional().describe('Set document to pageless format'),
+      batch: z.string().optional().describe('Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it — nothing changes in the doc until gog_batch_end submits the batch.'),
       account: accountParam,
     },
-  }, async ({ docId, text, file, index, replaceRange, markdown, at, occurrence, matchCase, tabId, pageless, account }) => {
+  }, async ({ docId, text, file, index, replaceRange, markdown, at, occurrence, matchCase, tabId, pageless, batch, account }) => {
     const args = ['docs', 'update', docId];
     if (text) args.push(`--text=${text}`);
     if (file) args.push(`--file=${file}`);
@@ -300,6 +308,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     if (matchCase) args.push('--match-case');
     if (tabId) args.push(`--tab-id=${tabId}`);
     if (pageless) args.push('--pageless');
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
 
@@ -445,6 +454,83 @@ export function registerExtraDocsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+  // Persisted, revision-locked Docs request batches (gog 0.25): begin a batch,
+  // run docs mutation tools with batch=<id> to compose requests locally, then
+  // end to submit them atomically against the locked revision.
+  server.registerTool('gog_batch_begin', {
+    description: 'Open a persisted, revision-locked request batch for a Google Doc. Subsequent docs mutation tools called with batch=<batchId> append their requests locally instead of applying them; gog_batch_end submits everything atomically. Returns the batchId.',
+    inputSchema: {
+      docId: z.string().describe('Google Doc ID the batch is locked to'),
+      name: z.string().optional().describe('Optional batch label'),
+      account: accountParam,
+    },
+  }, async ({ docId, name, account }) => {
+    const args = ['batch', 'begin', `--doc=${docId}`];
+    if (name) args.push(`--name=${name}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_batch_end', {
+    description: 'Submit a persisted batch: applies every composed request to the doc in one atomic batchUpdate against the locked revision. Atomic by default — set autoSplit to submit >500-request batches as ordered chunks (non-atomic), or continueOnError to retry individually after an atomic validation failure, retaining failures in the batch.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      batchId: z.string().describe('Batch ID (from gog_batch_begin)'),
+      autoSplit: z.boolean().optional().describe('Submit batches over 500 requests as ordered chunks (non-atomic)'),
+      continueOnError: z.boolean().optional().describe('After an atomic validation failure, submit requests individually and retain failures'),
+      account: accountParam,
+    },
+  }, async ({ batchId, autoSplit, continueOnError, account }) => {
+    const args = ['batch', 'end', batchId];
+    if (autoSplit) args.push('--auto-split');
+    if (continueOnError) args.push('--continue-on-error');
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_batch_abort', {
+    description: 'Discard a persisted batch and its composed requests without applying anything to the doc.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      batchId: z.string().describe('Batch ID to discard'),
+      account: accountParam,
+    },
+  }, async ({ batchId, account }) => {
+    return runOrDiagnose(['batch', 'abort', batchId], { account });
+  });
+
+  server.registerTool('gog_batch_list', {
+    description: 'List persisted Docs request batches (id, doc, label, request count, status).',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      account: accountParam,
+    },
+  }, async ({ account }) => {
+    return runOrDiagnose(['batch', 'list'], { account });
+  });
+
+  server.registerTool('gog_batch_show', {
+    description: 'Show one persisted batch: its doc, locked revision, and the composed requests awaiting submission.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      batchId: z.string().describe('Batch ID'),
+      account: accountParam,
+    },
+  }, async ({ batchId, account }) => {
+    return runOrDiagnose(['batch', 'show', batchId], { account });
+  });
+
+  server.registerTool('gog_batch_prune', {
+    description: 'Delete stale persisted batches (not updated within olderThan).',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      olderThan: z.string().optional().describe('Delete batches not updated within this duration (e.g. 72h, 7d)'),
+      account: accountParam,
+    },
+  }, async ({ olderThan, account }) => {
+    const args = ['batch', 'prune'];
+    if (olderThan) args.push(`--older-than=${olderThan}`);
+    return runOrDiagnose(args, { account });
+  });
+
   server.registerTool('gog_docs_table_column_width', {
     description: 'Set a fixed width (in points) for a table column, or reset columns to Docs-managed even distribution. Target the table by 1-based index in document order (negative counts from the end) and the column by 1-based number. Pass evenlyDistributed without col to reset every column in the table.',
     annotations: { destructiveHint: true },
@@ -455,15 +541,17 @@ export function registerExtraDocsTools(server: McpServer): void {
       evenlyDistributed: z.boolean().optional().describe('Reset the selected column (or all columns when col is omitted) to Docs-managed equal width.'),
       tableIndex: z.number().int().optional().describe('1-based table index in document order; negative counts from the end (default: 1)'),
       tab: z.string().optional().describe('Target tab title or ID'),
+      batch: z.string().optional().describe('Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it — nothing changes in the doc until gog_batch_end submits the batch.'),
       account: accountParam,
     },
-  }, async ({ docId, col, width, evenlyDistributed, tableIndex, tab, account }) => {
+  }, async ({ docId, col, width, evenlyDistributed, tableIndex, tab, batch, account }) => {
     const args = ['docs', 'table-column-width', docId];
     if (col !== undefined) args.push(`--col=${col}`);
     if (width !== undefined) args.push(`--width=${width}`);
     if (evenlyDistributed) args.push('--evenly-distributed');
     if (tableIndex !== undefined) args.push(`--table-index=${tableIndex}`);
     if (tab) args.push(`--tab=${tab}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
 
@@ -719,9 +807,10 @@ export function registerExtraDocsTools(server: McpServer): void {
       occurrence: z.number().int().optional().describe('Use the Nth `at` match (1-based; required when `at` is ambiguous)'),
       matchCase: z.boolean().optional().describe('Case-sensitive `at` matching'),
       tab: z.string().optional().describe('Target a specific tab by title or ID'),
+      batch: z.string().optional().describe('Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it — nothing changes in the doc until gog_batch_end submits the batch.'),
       account: accountParam,
     },
-  }, async ({ docId, index, atEnd, at, occurrence, matchCase, tab, account }) => {
+  }, async ({ docId, index, atEnd, at, occurrence, matchCase, tab, batch, account }) => {
     const args = ['docs', 'insert-page-break', docId];
     if (index !== undefined) args.push(`--index=${index}`);
     if (atEnd) args.push('--at-end');
@@ -729,6 +818,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     if (occurrence !== undefined) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push('--match-case');
     if (tab) args.push(`--tab=${tab}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
 
@@ -824,9 +914,10 @@ export function registerExtraDocsTools(server: McpServer): void {
       underline: z.boolean().optional().describe('Set cell text underline'),
       tableIndex: z.number().int().optional().describe('0-based table index in document order (default: 0)'),
       tab: z.string().optional().describe('Target a specific tab by title or ID'),
+      batch: z.string().optional().describe('Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it — nothing changes in the doc until gog_batch_end submits the batch.'),
       account: accountParam,
     },
-  }, async ({ docId, row, col, rowSpan, colSpan, backgroundColor, textColor, bold, italic, underline, tableIndex, tab, account }) => {
+  }, async ({ docId, row, col, rowSpan, colSpan, backgroundColor, textColor, bold, italic, underline, tableIndex, tab, batch, account }) => {
     const args = ['docs', 'cell-style', docId, `--row=${row}`, `--col=${col}`];
     if (rowSpan !== undefined) args.push(`--row-span=${rowSpan}`);
     if (colSpan !== undefined) args.push(`--col-span=${colSpan}`);
@@ -837,6 +928,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     if (underline) args.push('--underline');
     if (tableIndex !== undefined) args.push(`--table-index=${tableIndex}`);
     if (tab) args.push(`--tab=${tab}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
 
@@ -882,9 +974,10 @@ export function registerExtraDocsTools(server: McpServer): void {
       occurrence: z.number().int().optional().describe('Use the Nth `at` match (1-based; required when `at` is ambiguous)'),
       matchCase: z.boolean().optional().describe('Case-sensitive `at` matching'),
       tab: z.string().optional().describe('Target a specific tab by title or ID'),
+      batch: z.string().optional().describe('Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it — nothing changes in the doc until gog_batch_end submits the batch.'),
       account: accountParam,
     },
-  }, async ({ docId, email, index, atEnd, at, occurrence, matchCase, tab, account }) => {
+  }, async ({ docId, email, index, atEnd, at, occurrence, matchCase, tab, batch, account }) => {
     const args = ['docs', 'insert-person', docId, `--email=${email}`];
     if (index !== undefined) args.push(`--index=${index}`);
     if (atEnd) args.push('--at-end');
@@ -892,6 +985,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     if (occurrence !== undefined) args.push(`--occurrence=${occurrence}`);
     if (matchCase) args.push('--match-case');
     if (tab) args.push(`--tab=${tab}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
 
@@ -905,15 +999,17 @@ export function registerExtraDocsTools(server: McpServer): void {
       index: z.number().int().optional().describe('Character index to insert at. Omit or use atEnd for end-of-doc.'),
       atEnd: z.boolean().optional().describe('Insert at end-of-doc/tab (mutually exclusive with index)'),
       tab: z.string().optional().describe('Target a specific tab by title or ID'),
+      batch: z.string().optional().describe('Append this mutation to a persisted batch (from gog_batch_begin) instead of applying it — nothing changes in the doc until gog_batch_end submits the batch.'),
       account: accountParam,
     },
-  }, async ({ docId, date, format, index, atEnd, tab, account }) => {
+  }, async ({ docId, date, format, index, atEnd, tab, batch, account }) => {
     const args = ['docs', 'insert-date-chip', docId];
     if (date) args.push(`--date=${date}`);
     if (format) args.push(`--format=${format}`);
     if (index !== undefined) args.push(`--index=${index}`);
     if (atEnd) args.push('--at-end');
     if (tab) args.push(`--tab=${tab}`);
+    if (batch) args.push(`--batch=${batch}`);
     return runOrDiagnose(args, { account });
   });
 

package/tests/tools/docs-extra.test.ts

@@ -1482,3 +1482,163 @@ describe('gog_docs_read json tab targeting', () => {
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', 'd1', '--pretty', '--all-tabs'], { account: undefined });
   });
 });
+
+// --- gog 0.25.0: persisted Docs request batches ---
+
+describe('batch lifecycle tools', () => {
+  it('gog_batch_begin opens a batch for a doc', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_batch_begin')!({ docId: 'd1', name: 'big-edit' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['batch', 'begin', '--doc=d1', '--name=big-edit'],
+      { account: undefined },
+    );
+  });
+
+  it('gog_batch_begin opens a batch without a name', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_batch_begin')!({ docId: 'd1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['batch', 'begin', '--doc=d1'],
+      { account: undefined },
+    );
+  });
+
+  it('gog_batch_end submits with split/recovery modes', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_batch_end')!({ batchId: 'b1', autoSplit: true, continueOnError: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['batch', 'end', 'b1', '--auto-split', '--continue-on-error'],
+      { account: undefined },
+    );
+  });
+
+  it('gog_batch_end submits atomically with no options', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_batch_end')!({ batchId: 'b1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['batch', 'end', 'b1'],
+      { account: undefined },
+    );
+  });
+
+  it('gog_batch_abort discards a batch', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_batch_abort')!({ batchId: 'b1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'abort', 'b1'], { account: undefined });
+  });
+
+  it('gog_batch_list / gog_batch_show read batch state', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_batch_list')!({});
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'list'], { account: undefined });
+    await handlers.get('gog_batch_show')!({ batchId: 'b1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'show', 'b1'], { account: undefined });
+  });
+
+  it('gog_batch_prune deletes stale batches', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_batch_prune')!({ olderThan: '72h' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'prune', '--older-than=72h'], { account: undefined });
+  });
+
+  it('gog_batch_prune without a duration prunes with no filter', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_batch_prune')!({});
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'prune'], { account: undefined });
+  });
+});
+
+describe('batch param on docs mutation tools (gog 0.25.0)', () => {
+  // Each wrapped docs command that gained --batch appends to a persisted
+  // batch instead of submitting when batch is supplied.
+  const cases: Array<{ tool: string; input: Record<string, unknown>; expected: string[] }> = [
+    { tool: 'gog_docs_insert', input: { docId: 'd1', content: 'X', batch: 'b1' },
+      expected: ['docs', 'insert', 'd1', 'X', '--batch=b1'] },
+    { tool: 'gog_docs_delete', input: { docId: 'd1', start: 1, end: 5, batch: 'b1' },
+      expected: ['docs', 'delete', '--start=1', '--end=5', 'd1', '--batch=b1'] },
+    { tool: 'gog_docs_update', input: { docId: 'd1', text: 'T', batch: 'b1' },
+      expected: ['docs', 'update', 'd1', '--text=T', '--batch=b1'] },
+    { tool: 'gog_docs_format', input: { docId: 'd1', match: 'm', bold: true, batch: 'b1' },
+      expected: ['docs', 'format', 'd1', '--match=m', '--bold', '--batch=b1'] },
+    { tool: 'gog_docs_insert_page_break', input: { docId: 'd1', atEnd: true, batch: 'b1' },
+      expected: ['docs', 'insert-page-break', 'd1', '--at-end', '--batch=b1'] },
+    { tool: 'gog_docs_insert_person', input: { docId: 'd1', email: 'a@b.com', batch: 'b1' },
+      expected: ['docs', 'insert-person', 'd1', '--email=a@b.com', '--batch=b1'] },
+    { tool: 'gog_docs_insert_date_chip', input: { docId: 'd1', batch: 'b1' },
+      expected: ['docs', 'insert-date-chip', 'd1', '--batch=b1'] },
+    { tool: 'gog_docs_table_column_width', input: { docId: 'd1', col: 1, width: 80, batch: 'b1' },
+      expected: ['docs', 'table-column-width', 'd1', '--col=1', '--width=80', '--batch=b1'] },
+    { tool: 'gog_docs_cell_style', input: { docId: 'd1', row: 0, col: 0, bold: true, batch: 'b1' },
+      expected: ['docs', 'cell-style', 'd1', '--row=0', '--col=0', '--bold', '--batch=b1'] },
+  ];
+
+  for (const { tool, input, expected } of cases) {
+    it(`${tool} appends to a batch via --batch`, async () => {
+      vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+      const handlers = setupHandlers();
+      await handlers.get(tool)!(input);
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(expected, { account: undefined });
+    });
+  }
+});
+
+// Truthy --tab/--table branches the original tests missed (exposed by the
+// vitest 4.1.8 V8 remapping change — these flags were untested on these tools).
+describe('tab/table selector branch coverage', () => {
+  const cases: Array<{ tool: string; input: Record<string, unknown>; expected: string[] }> = [
+    { tool: 'gog_docs_table_row_delete', input: { docId: 'd1', row: 1, tab: 'T' },
+      expected: ['docs', 'table-row', 'delete', 'd1', '--row=1', '--tab=T'] },
+    { tool: 'gog_docs_table_column_delete', input: { docId: 'd1', col: 1, table: '2', tab: 'T' },
+      expected: ['docs', 'table-column', 'delete', 'd1', '--col=1', '--table=2', '--tab=T'] },
+    { tool: 'gog_docs_table_merge', input: { docId: 'd1', range: '1,1:2,2', tab: 'T' },
+      expected: ['docs', 'table-merge', 'd1', '--range=1,1:2,2', '--tab=T'] },
+    { tool: 'gog_docs_table_unmerge', input: { docId: 'd1', cell: '1,1', table: 'Budget' },
+      expected: ['docs', 'table-unmerge', 'd1', '--cell=1,1', '--table=Budget'] },
+    { tool: 'gog_docs_named_range_list', input: { docId: 'd1', tab: 'T' },
+      expected: ['docs', 'named-range', 'list', 'd1', '--tab=T'] },
+    { tool: 'gog_docs_named_range_delete', input: { docId: 'd1', nameOrId: 'nr', tab: 'T' },
+      expected: ['docs', 'named-range', 'delete', 'd1', 'nr', '--tab=T'] },
+    { tool: 'gog_docs_images_list', input: { docId: 'd1', tab: 'T' },
+      expected: ['docs', 'images', 'list', 'd1', '--tab=T'] },
+    { tool: 'gog_docs_headings_list', input: { docId: 'd1', tab: 'T' },
+      expected: ['docs', 'headings', 'list', 'd1', '--tab=T'] },
+    { tool: 'gog_docs_insert_date_chip', input: { docId: 'd1', tab: 'T' },
+      expected: ['docs', 'insert-date-chip', 'd1', '--tab=T'] },
+  ];
+  for (const { tool, input, expected } of cases) {
+    it(`${tool} passes its tab/table selectors`, async () => {
+      vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+      const handlers = setupHandlers();
+      await handlers.get(tool)!(input);
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(expected, { account: undefined });
+    });
+  }
+});
+
+describe('bare-call branch coverage (no optional flags)', () => {
+  const cases: Array<{ tool: string; input: Record<string, unknown>; expected: string[] }> = [
+    { tool: 'gog_docs_table_column_insert', input: { docId: 'd1' },
+      expected: ['docs', 'table-column', 'insert', 'd1'] },
+    { tool: 'gog_docs_tables_list', input: { docId: 'd1' },
+      expected: ['docs', 'tables', 'list', 'd1'] },
+    { tool: 'gog_docs_paragraphs_list', input: { docId: 'd1' },
+      expected: ['docs', 'paragraphs', 'list', 'd1'] },
+  ];
+  for (const { tool, input, expected } of cases) {
+    it(`${tool} with no optional flags`, async () => {
+      vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+      const handlers = setupHandlers();
+      await handlers.get(tool)!(input);
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(expected, { account: undefined });
+    });
+  }
+});