gogcli-mcp-docs 2.0.9 → 2.0.11

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.0.9"
+    "version": "2.0.11"
   },
   "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.0.9",
+      "version": "2.0.11",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/README.md

@@ -3,11 +3,11 @@
 > [!WARNING]
 > **AI-developed project.** This codebase was built and is actively maintained by [Claude Code](https://www.anthropic.com/claude). Review all code and tool permissions before use.
 
-Extended Google Docs [MCP](https://modelcontextprotocol.io) server via [gogcli](https://github.com/steipete/gogcli). Includes auth tools plus 14 additional dedicated Docs tools for editing, exporting, comments, and more.
+Extended Google Docs [MCP](https://modelcontextprotocol.io) server via [gogcli](https://github.com/openclaw/gogcli). Includes auth tools plus 18 additional dedicated Docs tools for editing, exporting, comments, and more.
 
 ## Requirements
 
-- [gogcli](https://github.com/steipete/gogcli) installed and authenticated
+- [gogcli](https://github.com/openclaw/gogcli) installed and authenticated
 - Node.js 18+
 
 ```bash
@@ -44,19 +44,23 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 claude mcp add gogcli-docs -- gogcli-mcp-docs
 ```
 
-## Extra Docs Tools (14)
+## Extra Docs Tools (18)
 
 Plus 5 auth tools and 7 base Docs tools (info, cat, create, write, find-replace, structure, run).
 
 | Tool | Description |
 |------|-------------|
+| `gog_docs_append` | Append text or markdown to the end of a doc |
 | `gog_docs_copy` | Copy a document |
 | `gog_docs_delete` | Delete content by character index range |
 | `gog_docs_edit` | Find and replace with case-sensitivity control |
 | `gog_docs_export` | Export as PDF, TXT, HTML, DOCX, RTF, ODT, or EPUB |
+| `gog_docs_format` | Apply character / paragraph formatting (bold, color, alignment, …) |
 | `gog_docs_insert` | Insert text at a specific position |
 | `gog_docs_list_tabs` | List all document tabs |
+| `gog_docs_read` | Read doc as plain text or raw JSON |
 | `gog_docs_sed` | Stream-edit with sed-like regex expressions |
+| `gog_docs_trash` | Move a doc to Drive trash |
 | `gog_docs_update` | Update document content at a specific position |
 | `gog_docs_comments_list` | List comments (open or resolved) |
 | `gog_docs_comments_get` | Get a comment with its replies |
@@ -65,6 +69,16 @@ Plus 5 auth tools and 7 base Docs tools (info, cat, create, write, find-replace,
 | `gog_docs_comments_resolve` | Resolve a comment |
 | `gog_docs_comments_delete` | Delete a comment |
 
+## Known limitations: `gog_docs_append` with `markdown: true`
+
+These bugs live in gogcli's upstream markdown → Docs converter; the wrapper just passes `--markdown` through. Tracked upstream:
+
+| Symptom | Workaround | Upstream |
+|---------|-----------|----------|
+| 3+ tables in one call reorders the trailing punctuation of the paragraph before the 3rd table | Split into multiple calls with ≤2 tables each | [openclaw/gogcli#607](https://github.com/openclaw/gogcli/issues/607) |
+| Inline `**bold**` / `*italic*` / `` `code` `` inside table cells renders as literal characters | Insert plain cell text, then apply formatting via `gog_docs_format` | [openclaw/gogcli#608](https://github.com/openclaw/gogcli/issues/608) |
+| Tables with an empty header row leak the last data row as literal pipe text | Always supply a non-empty header row | [openclaw/gogcli#609](https://github.com/openclaw/gogcli/issues/609) |
+
 ## License
 
 MIT

package/SKILL.md

@@ -5,13 +5,13 @@ description: Use when the user asks to read, write, edit, export, or comment on
 
 # gogcli-mcp-docs
 
-Extended Google Docs MCP server via [gogcli](https://github.com/steipete/gogcli) — 26 tools: auth + 7 base Docs + 14 extra dedicated Docs tools.
+Extended Google Docs MCP server via [gogcli](https://github.com/openclaw/gogcli) — 30 tools: auth + 7 base Docs + 18 extra dedicated Docs tools.
 
 - **Source:** [github.com/chrischall/gogcli-mcp](https://github.com/chrischall/gogcli-mcp)
 
 ## Requirements
 
-- [gogcli](https://github.com/steipete/gogcli) installed and authenticated
+- [gogcli](https://github.com/openclaw/gogcli) installed and authenticated
 - Node.js 18 or later
 
 ## Setup
@@ -34,13 +34,17 @@ Extended Google Docs MCP server via [gogcli](https://github.com/steipete/gogcli)
 
 | Tool | What it does |
 |------|-------------|
+| `gog_docs_append` | Append text or markdown to the end of a doc |
 | `gog_docs_copy` | Copy a document |
 | `gog_docs_delete` | Delete content by character index range |
 | `gog_docs_edit` | Find and replace with case-sensitivity |
 | `gog_docs_export` | Export as PDF, TXT, HTML, DOCX, RTF, ODT, or EPUB |
+| `gog_docs_format` | Apply character / paragraph formatting |
 | `gog_docs_insert` | Insert text at a specific position |
 | `gog_docs_list_tabs` | List all document tabs |
+| `gog_docs_read` | Read doc as plain text or raw JSON |
 | `gog_docs_sed` | Stream-edit with sed-like regex |
+| `gog_docs_trash` | Move a doc to Drive trash |
 | `gog_docs_update` | Update content at a specific position |
 | `gog_docs_comments_list` | List comments (open or resolved) |
 | `gog_docs_comments_get` | Get a comment with replies |
@@ -50,3 +54,11 @@ Extended Google Docs MCP server via [gogcli](https://github.com/steipete/gogcli)
 | `gog_docs_comments_delete` | Delete a comment |
 
 Plus 5 auth tools and 7 base Docs tools.
+
+### `gog_docs_append` with `markdown: true` — known limitations
+
+Three bugs in gogcli's upstream markdown→Docs converter to be aware of:
+
+- **3+ tables in one call** reorders the trailing punctuation of the paragraph before the 3rd table — split into multiple calls with ≤2 tables each ([openclaw/gogcli#607](https://github.com/openclaw/gogcli/issues/607)).
+- **Inline `**bold**` / `*italic*` / `` `code` `` inside table cells** renders as literal characters — insert plain cell text, then apply formatting via `gog_docs_format` ([openclaw/gogcli#608](https://github.com/openclaw/gogcli/issues/608)).
+- **Empty-header tables** leak the last data row as literal pipe text — always supply a non-empty header row ([openclaw/gogcli#609](https://github.com/openclaw/gogcli/issues/609)).

package/dist/index.js

@@ -31063,7 +31063,7 @@ async function run(args, options = {}) {
       settled = true;
       if (err.code === "ENOENT") {
         reject(new Error(
-          "gog executable not found. Install gogcli (https://github.com/steipete/gogcli) or set GOG_PATH in your MCP client config to the absolute binary path (run `which gog` in a terminal to find it)."
+          "gog executable not found. Install gogcli (https://github.com/openclaw/gogcli) or set GOG_PATH in your MCP client config to the absolute binary path (run `which gog` in a terminal to find it)."
         ));
         return;
       }
@@ -31288,8 +31288,11 @@ function registerDocsTools(server2) {
   registerRunTool(server2, { service: "docs", examples: '"copy", "clear", "insert", "sed", "export"' });
 }
 
+// ../gogcli-mcp/src/tools/sheets.ts
+var cellValueParam = external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]);
+
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.0.9" : "0.0.0";
+var VERSION = true ? "2.0.11" : "0.0.0";
 function createServer(options) {
   return new McpServer({
     name: options?.name ?? "gogcli",
@@ -31313,7 +31316,7 @@ function registerExtraDocsTools(server2) {
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_delete", {
-    description: "Delete content within a Google Doc by character index range.",
+    description: "Delete content within a Google Doc by character index range. To remove the entire document (move to Drive trash), use gog_docs_trash.",
     annotations: { destructiveHint: true },
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
@@ -31327,6 +31330,16 @@ function registerExtraDocsTools(server2) {
     if (tabId) args.push(`--tab-id=${tabId}`);
     return runOrDiagnose(args, { account });
   });
+  server2.registerTool("gog_docs_trash", {
+    description: "Move an entire Google Doc to Drive trash. Convenience wrapper around `gog drive delete` so docs-only users can clean up without installing gogcli-mcp-drive. The doc remains recoverable from Drive trash for ~30 days.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: external_exports.string().describe("Doc ID to move to trash"),
+      account: accountParam
+    }
+  }, async ({ docId, account }) => {
+    return runOrDiagnose(["drive", "delete", docId], { account });
+  });
   server2.registerTool("gog_docs_edit", {
     description: "Edit a Google Doc by finding and replacing text (stream-edit style).",
     annotations: { destructiveHint: true },
@@ -31342,6 +31355,75 @@ function registerExtraDocsTools(server2) {
     if (matchCase) args.push("--match-case");
     return runOrDiagnose(args, { account });
   });
+  server2.registerTool("gog_docs_read", {
+    description: 'Read the content of a Google Doc. Default: plain text body. Use format="json" for the raw Google Docs API response (lossless, includes character indices needed for index-based gog_docs_insert / gog_docs_delete calls). For markdown output, use gog_docs_export with format="md" \u2014 it writes to a file. Use gog_docs_structure to see paragraph-by-paragraph layout with indices.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: external_exports.string().describe("Doc ID (from the URL)"),
+      format: external_exports.enum(["text", "json"]).optional().describe("Output format (default: text)"),
+      tab: external_exports.string().optional().describe("Target tab title or ID (text mode only)"),
+      allTabs: external_exports.boolean().optional().describe("Show all tabs with headers (text mode only)"),
+      maxBytes: external_exports.number().optional().describe("Max bytes to read in text mode (0 = unlimited; default 2000000)"),
+      account: accountParam
+    }
+  }, async ({ docId, format, tab, allTabs, maxBytes, account }) => {
+    if (format === "json") {
+      return runOrDiagnose(["docs", "raw", docId, "--pretty"], { account });
+    }
+    const args = ["docs", "cat", docId];
+    if (tab) args.push(`--tab=${tab}`);
+    if (allTabs) args.push("--all-tabs");
+    if (maxBytes !== void 0) args.push(`--max-bytes=${maxBytes}`);
+    return runOrDiagnose(args, { account });
+  });
+  server2.registerTool("gog_docs_format", {
+    description: "Apply text or paragraph formatting to a Google Doc. Use `match` to format a specific text occurrence, `matchAll` to format every occurrence, or omit both to format the whole doc. Boolean flags (bold/italic/etc.) set the attribute; negated flags (noBold/noItalic/etc.) clear it.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: external_exports.string().describe("Doc ID (from the URL)"),
+      match: external_exports.string().optional().describe("Format only the first text match"),
+      matchAll: external_exports.boolean().optional().describe("Format all matches instead of only the first"),
+      matchCase: external_exports.boolean().optional().describe("Case-sensitive matching"),
+      tab: external_exports.string().optional().describe("Target tab title or ID"),
+      fontFamily: external_exports.string().optional().describe("Font family (e.g. Arial, Georgia)"),
+      fontSize: external_exports.number().optional().describe("Font size in points"),
+      textColor: external_exports.string().optional().describe("Text color as #RRGGBB or #RGB"),
+      bgColor: external_exports.string().optional().describe("Text background color as #RRGGBB or #RGB"),
+      bold: external_exports.boolean().optional().describe("Set bold"),
+      noBold: external_exports.boolean().optional().describe("Clear bold"),
+      italic: external_exports.boolean().optional().describe("Set italic"),
+      noItalic: external_exports.boolean().optional().describe("Clear italic"),
+      underline: external_exports.boolean().optional().describe("Set underline"),
+      noUnderline: external_exports.boolean().optional().describe("Clear underline"),
+      strikethrough: external_exports.boolean().optional().describe("Set strikethrough"),
+      noStrikethrough: external_exports.boolean().optional().describe("Clear strikethrough"),
+      alignment: external_exports.enum(["left", "center", "right", "justify", "start", "end", "justified"]).optional().describe("Paragraph alignment"),
+      lineSpacing: external_exports.number().optional().describe("Line spacing percentage (e.g. 100 for single, 150 for 1.5x, 200 for double)"),
+      account: accountParam
+    }
+  }, async (args) => {
+    const a = args;
+    const argv = ["docs", "format", a.docId];
+    if (a.match) argv.push(`--match=${a.match}`);
+    if (a.matchAll) argv.push("--match-all");
+    if (a.matchCase) argv.push("--match-case");
+    if (a.tab) argv.push(`--tab=${a.tab}`);
+    if (a.fontFamily) argv.push(`--font-family=${a.fontFamily}`);
+    if (a.fontSize !== void 0) argv.push(`--font-size=${a.fontSize}`);
+    if (a.textColor) argv.push(`--text-color=${a.textColor}`);
+    if (a.bgColor) argv.push(`--bg-color=${a.bgColor}`);
+    if (a.bold) argv.push("--bold");
+    if (a.noBold) argv.push("--no-bold");
+    if (a.italic) argv.push("--italic");
+    if (a.noItalic) argv.push("--no-italic");
+    if (a.underline) argv.push("--underline");
+    if (a.noUnderline) argv.push("--no-underline");
+    if (a.strikethrough) argv.push("--strikethrough");
+    if (a.noStrikethrough) argv.push("--no-strikethrough");
+    if (a.alignment) argv.push(`--alignment=${a.alignment}`);
+    if (a.lineSpacing !== void 0) argv.push(`--line-spacing=${a.lineSpacing}`);
+    return runOrDiagnose(argv, { account: a.account });
+  });
   server2.registerTool("gog_docs_export", {
     description: "Export a Google Doc as PDF, plain text, HTML, DOCX, or other format.",
     annotations: { readOnlyHint: true },
@@ -31358,12 +31440,12 @@ function registerExtraDocsTools(server2) {
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_insert", {
-    description: "Insert text at a specific position in a Google Doc.",
+    description: "Insert text at a specific character index in a Google Doc. When `index` is omitted, gog defaults to 1 (the very beginning), NOT the end \u2014 sequential inserts without an explicit index produce reversed output. To append at the end of the doc, use gog_docs_append (which uses `gog docs write --append` and is the right tool for iterative document construction). To find a valid index for mid-document inserts, call gog_docs_structure or gog_docs_read first.",
     annotations: { destructiveHint: true },
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       content: external_exports.string().optional().describe("Text content to insert"),
-      index: external_exports.number().optional().describe("Character index to insert at (default: end of document)"),
+      index: external_exports.number().optional().describe("Character index to insert at (1-based; default: 1 = start of doc). Prefer gog_docs_append when you want to add at the end."),
       file: external_exports.string().optional().describe("Path to a file whose content to insert"),
       tabId: external_exports.string().optional().describe("Tab ID to insert into (for multi-tab docs)"),
       account: accountParam
@@ -31376,6 +31458,25 @@ function registerExtraDocsTools(server2) {
     if (tabId) args.push(`--tab-id=${tabId}`);
     return runOrDiagnose(args, { account });
   });
+  server2.registerTool("gog_docs_append", {
+    description: "Append text to the end of a Google Doc. This is the right tool for iterative document construction \u2014 multiple sequential calls produce content in the order they were called. Use gog_docs_insert only when you need to insert at a specific character position. Known markdown=true limitations (tracked upstream): (a) 3+ tables in one call reorders the trailing punctuation of the paragraph before the 3rd table \u2014 split into multiple calls with \u22642 tables each (openclaw/gogcli#607); (b) inline **bold** / *italic* / `code` inside table cells renders as literal characters \u2014 pre-format cell text separately or apply formatting after the append via gog_docs_format (openclaw/gogcli#608); (c) tables with an empty header row leak the last data row as literal pipe text \u2014 always supply a non-empty header (openclaw/gogcli#609).",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: external_exports.string().describe("Doc ID (from the URL)"),
+      text: external_exports.string().optional().describe("Text content to append"),
+      file: external_exports.string().optional().describe('Path to a text file to append (use "-" for stdin)'),
+      markdown: external_exports.boolean().optional().describe("Convert markdown to Google Docs formatting (headings, bold, lists, etc.). See the tool description for known upstream limitations around tables."),
+      tab: external_exports.string().optional().describe("Target tab title or ID (for multi-tab docs)"),
+      account: accountParam
+    }
+  }, async ({ docId, text, file: file2, markdown, tab, account }) => {
+    const args = ["docs", "write", docId, "--append"];
+    if (text) args.push(`--text=${text}`);
+    if (file2) args.push(`--file=${file2}`);
+    if (markdown) args.push("--markdown");
+    if (tab) args.push(`--tab=${tab}`);
+    return runOrDiagnose(args, { account });
+  });
   server2.registerTool("gog_docs_list_tabs", {
     description: "List all tabs in a Google Doc.",
     annotations: { readOnlyHint: true },

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",
@@ -158,6 +158,22 @@
     {
       "name": "gog_docs_comments_delete",
       "description": "Delete a comment from a Google Doc. This action is permanent."
+    },
+    {
+      "name": "gog_docs_append",
+      "description": "Append text to the end of a Google Doc (the right tool for iterative construction). markdown=true known limitations (upstream): 3+ tables/call reorders trailing punctuation (split calls); inline bold/italic/code in cells renders literally (format after); empty-header tables leak literal pipes (use non-empty header)."
+    },
+    {
+      "name": "gog_docs_read",
+      "description": "Read a Google Doc as plain text or as raw Docs API JSON"
+    },
+    {
+      "name": "gog_docs_format",
+      "description": "Apply text/paragraph formatting (bold, italic, font size, color, alignment, line spacing) — supports match, matchAll, matchCase"
+    },
+    {
+      "name": "gog_docs_trash",
+      "description": "Move an entire Google Doc to Drive trash (convenience wrapper around gog drive delete)"
     }
   ],
   "compatibility": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-docs",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "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.0.9",
+  "version": "2.0.11",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp-docs",
-      "version": "2.0.9",
+      "version": "2.0.11",
       "transport": {
         "type": "stdio"
       },

package/src/tools/docs-extra.ts

@@ -18,7 +18,7 @@ export function registerExtraDocsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_docs_delete', {
-    description: 'Delete content within a Google Doc by character index range.',
+    description: 'Delete content within a Google Doc by character index range. To remove the entire document (move to Drive trash), use gog_docs_trash.',
     annotations: { destructiveHint: true },
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
@@ -33,6 +33,17 @@ export function registerExtraDocsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+  server.registerTool('gog_docs_trash', {
+    description: 'Move an entire Google Doc to Drive trash. Convenience wrapper around `gog drive delete` so docs-only users can clean up without installing gogcli-mcp-drive. The doc remains recoverable from Drive trash for ~30 days.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID to move to trash'),
+      account: accountParam,
+    },
+  }, async ({ docId, account }) => {
+    return runOrDiagnose(['drive', 'delete', docId], { account });
+  });
+
   server.registerTool('gog_docs_edit', {
     description: 'Edit a Google Doc by finding and replacing text (stream-edit style).',
     annotations: { destructiveHint: true },
@@ -49,6 +60,94 @@ export function registerExtraDocsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+  server.registerTool('gog_docs_read', {
+    description: 'Read the content of a Google Doc. Default: plain text body. Use format="json" for the raw Google Docs API response (lossless, includes character indices needed for index-based gog_docs_insert / gog_docs_delete calls). For markdown output, use gog_docs_export with format="md" — it writes to a file. Use gog_docs_structure to see paragraph-by-paragraph layout with indices.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      format: z.enum(['text', 'json']).optional().describe('Output format (default: text)'),
+      tab: z.string().optional().describe('Target tab title or ID (text mode only)'),
+      allTabs: z.boolean().optional().describe('Show all tabs with headers (text mode only)'),
+      maxBytes: z.number().optional().describe('Max bytes to read in text mode (0 = unlimited; default 2000000)'),
+      account: accountParam,
+    },
+  }, async ({ docId, format, tab, allTabs, maxBytes, account }) => {
+    if (format === 'json') {
+      return runOrDiagnose(['docs', 'raw', docId, '--pretty'], { account });
+    }
+    const args = ['docs', 'cat', docId];
+    if (tab) args.push(`--tab=${tab}`);
+    if (allTabs) args.push('--all-tabs');
+    if (maxBytes !== undefined) args.push(`--max-bytes=${maxBytes}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_docs_format', {
+    description: 'Apply text or paragraph formatting to a Google Doc. Use `match` to format a specific text occurrence, `matchAll` to format every occurrence, or omit both to format the whole doc. Boolean flags (bold/italic/etc.) set the attribute; negated flags (noBold/noItalic/etc.) clear it.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      match: z.string().optional().describe('Format only the first text match'),
+      matchAll: z.boolean().optional().describe('Format all matches instead of only the first'),
+      matchCase: z.boolean().optional().describe('Case-sensitive matching'),
+      tab: z.string().optional().describe('Target tab title or ID'),
+      fontFamily: z.string().optional().describe('Font family (e.g. Arial, Georgia)'),
+      fontSize: z.number().optional().describe('Font size in points'),
+      textColor: z.string().optional().describe('Text color as #RRGGBB or #RGB'),
+      bgColor: z.string().optional().describe('Text background color as #RRGGBB or #RGB'),
+      bold: z.boolean().optional().describe('Set bold'),
+      noBold: z.boolean().optional().describe('Clear bold'),
+      italic: z.boolean().optional().describe('Set italic'),
+      noItalic: z.boolean().optional().describe('Clear italic'),
+      underline: z.boolean().optional().describe('Set underline'),
+      noUnderline: z.boolean().optional().describe('Clear underline'),
+      strikethrough: z.boolean().optional().describe('Set strikethrough'),
+      noStrikethrough: z.boolean().optional().describe('Clear strikethrough'),
+      alignment: z.enum(['left', 'center', 'right', 'justify', 'start', 'end', 'justified']).optional().describe('Paragraph alignment'),
+      lineSpacing: z.number().optional().describe('Line spacing percentage (e.g. 100 for single, 150 for 1.5x, 200 for double)'),
+      account: accountParam,
+    },
+  }, async (args) => {
+    const a = args as {
+      docId: string;
+      match?: string;
+      matchAll?: boolean;
+      matchCase?: boolean;
+      tab?: string;
+      fontFamily?: string;
+      fontSize?: number;
+      textColor?: string;
+      bgColor?: string;
+      bold?: boolean; noBold?: boolean;
+      italic?: boolean; noItalic?: boolean;
+      underline?: boolean; noUnderline?: boolean;
+      strikethrough?: boolean; noStrikethrough?: boolean;
+      alignment?: string;
+      lineSpacing?: number;
+      account?: string;
+    };
+    const argv = ['docs', 'format', a.docId];
+    if (a.match) argv.push(`--match=${a.match}`);
+    if (a.matchAll) argv.push('--match-all');
+    if (a.matchCase) argv.push('--match-case');
+    if (a.tab) argv.push(`--tab=${a.tab}`);
+    if (a.fontFamily) argv.push(`--font-family=${a.fontFamily}`);
+    if (a.fontSize !== undefined) argv.push(`--font-size=${a.fontSize}`);
+    if (a.textColor) argv.push(`--text-color=${a.textColor}`);
+    if (a.bgColor) argv.push(`--bg-color=${a.bgColor}`);
+    if (a.bold) argv.push('--bold');
+    if (a.noBold) argv.push('--no-bold');
+    if (a.italic) argv.push('--italic');
+    if (a.noItalic) argv.push('--no-italic');
+    if (a.underline) argv.push('--underline');
+    if (a.noUnderline) argv.push('--no-underline');
+    if (a.strikethrough) argv.push('--strikethrough');
+    if (a.noStrikethrough) argv.push('--no-strikethrough');
+    if (a.alignment) argv.push(`--alignment=${a.alignment}`);
+    if (a.lineSpacing !== undefined) argv.push(`--line-spacing=${a.lineSpacing}`);
+    return runOrDiagnose(argv, { account: a.account });
+  });
+
   server.registerTool('gog_docs_export', {
     description: 'Export a Google Doc as PDF, plain text, HTML, DOCX, or other format.',
     annotations: { readOnlyHint: true },
@@ -66,12 +165,12 @@ export function registerExtraDocsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_docs_insert', {
-    description: 'Insert text at a specific position in a Google Doc.',
+    description: 'Insert text at a specific character index in a Google Doc. When `index` is omitted, gog defaults to 1 (the very beginning), NOT the end — sequential inserts without an explicit index produce reversed output. To append at the end of the doc, use gog_docs_append (which uses `gog docs write --append` and is the right tool for iterative document construction). To find a valid index for mid-document inserts, call gog_docs_structure or gog_docs_read first.',
     annotations: { destructiveHint: true },
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       content: z.string().optional().describe('Text content to insert'),
-      index: z.number().optional().describe('Character index to insert at (default: end of document)'),
+      index: z.number().optional().describe('Character index to insert at (1-based; default: 1 = start of doc). Prefer gog_docs_append when you want to add at the end.'),
       file: z.string().optional().describe('Path to a file whose content to insert'),
       tabId: z.string().optional().describe('Tab ID to insert into (for multi-tab docs)'),
       account: accountParam,
@@ -85,6 +184,26 @@ export function registerExtraDocsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+  server.registerTool('gog_docs_append', {
+    description: 'Append text to the end of a Google Doc. This is the right tool for iterative document construction — multiple sequential calls produce content in the order they were called. Use gog_docs_insert only when you need to insert at a specific character position. Known markdown=true limitations (tracked upstream): (a) 3+ tables in one call reorders the trailing punctuation of the paragraph before the 3rd table — split into multiple calls with ≤2 tables each (openclaw/gogcli#607); (b) inline **bold** / *italic* / `code` inside table cells renders as literal characters — pre-format cell text separately or apply formatting after the append via gog_docs_format (openclaw/gogcli#608); (c) tables with an empty header row leak the last data row as literal pipe text — always supply a non-empty header (openclaw/gogcli#609).',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      text: z.string().optional().describe('Text content to append'),
+      file: z.string().optional().describe('Path to a text file to append (use "-" for stdin)'),
+      markdown: z.boolean().optional().describe('Convert markdown to Google Docs formatting (headings, bold, lists, etc.). See the tool description for known upstream limitations around tables.'),
+      tab: z.string().optional().describe('Target tab title or ID (for multi-tab docs)'),
+      account: accountParam,
+    },
+  }, async ({ docId, text, file, markdown, tab, account }) => {
+    const args = ['docs', 'write', docId, '--append'];
+    if (text) args.push(`--text=${text}`);
+    if (file) args.push(`--file=${file}`);
+    if (markdown) args.push('--markdown');
+    if (tab) args.push(`--tab=${tab}`);
+    return runOrDiagnose(args, { account });
+  });
+
   server.registerTool('gog_docs_list_tabs', {
     description: 'List all tabs in a Google Doc.',
     annotations: { readOnlyHint: true },

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

@@ -518,3 +518,151 @@ describe('gog_docs_comments_delete', () => {
     );
   });
 });
+
+describe('gog_docs_trash', () => {
+  it('routes to gog drive delete <docId>', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_trash')!({ docId: 'd1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['drive', 'delete', 'd1'], { account: undefined });
+  });
+});
+
+describe('gog_docs_append', () => {
+  it('uses gog docs write --append', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_append')!({ docId: 'd1', text: 'Hello' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'write', 'd1', '--append', '--text=Hello'],
+      { account: undefined },
+    );
+  });
+
+  it('passes file, markdown, and tab flags', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_append')!({
+      docId: 'd1', file: '/tmp/section.md', markdown: true, tab: 'Notes',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'write', 'd1', '--append', '--file=/tmp/section.md', '--markdown', '--tab=Notes'],
+      { account: undefined },
+    );
+  });
+
+  // Regression: the tool description must warn about the 3 known upstream
+  // markdown converter bugs (openclaw/gogcli#607, #608, #609). If upstream
+  // fixes any of these and the warning is removed, this test fails as a
+  // prompt to revisit + reopen the README/SKILL/TODO sections too.
+  it('description warns about all 3 known upstream markdown limitations', async () => {
+    // Local mock to capture the registration config (the shared harness only
+    // captures the handler callback).
+    const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+    const server = new McpServer({ name: 'test', version: '0.0.0' });
+    const configs = new Map<string, { description?: string }>();
+    vi.spyOn(server, 'registerTool').mockImplementation((name, config) => {
+      configs.set(name, config as { description?: string });
+      return undefined as never;
+    });
+    const { registerExtraDocsTools } = await import('../../src/tools/docs-extra.js');
+    registerExtraDocsTools(server);
+    const desc = configs.get('gog_docs_append')?.description ?? '';
+    expect(desc).toMatch(/openclaw\/gogcli#607/);
+    expect(desc).toMatch(/openclaw\/gogcli#608/);
+    expect(desc).toMatch(/openclaw\/gogcli#609/);
+  });
+});
+
+describe('gog_docs_read', () => {
+  it('defaults to plain text via gog docs cat', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('hello'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_read')!({ docId: 'd1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'cat', 'd1'], { account: undefined });
+  });
+
+  it('routes json format to gog docs raw --pretty', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_read')!({ docId: 'd1', format: 'json' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', 'd1', '--pretty'], { account: undefined });
+  });
+
+  it('passes tab, allTabs, maxBytes in text mode', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText(''));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_read')!({ docId: 'd1', tab: 'Section A', allTabs: true, maxBytes: 0 });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'cat', 'd1', '--tab=Section A', '--all-tabs', '--max-bytes=0'],
+      { account: undefined },
+    );
+  });
+});
+
+describe('gog_docs_format', () => {
+  it('passes all text/paragraph attribute flags', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_format')!({
+      docId: 'd1',
+      match: 'Title',
+      matchAll: true,
+      matchCase: true,
+      tab: 'Body',
+      fontFamily: 'Arial',
+      fontSize: 18,
+      textColor: '#333333',
+      bgColor: '#FFF5D9',
+      bold: true,
+      italic: true,
+      underline: true,
+      strikethrough: true,
+      alignment: 'center',
+      lineSpacing: 150,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      [
+        'docs', 'format', 'd1',
+        '--match=Title',
+        '--match-all',
+        '--match-case',
+        '--tab=Body',
+        '--font-family=Arial',
+        '--font-size=18',
+        '--text-color=#333333',
+        '--bg-color=#FFF5D9',
+        '--bold',
+        '--italic',
+        '--underline',
+        '--strikethrough',
+        '--alignment=center',
+        '--line-spacing=150',
+      ],
+      { account: undefined },
+    );
+  });
+
+  it('emits clear-style flags (noBold/noItalic/...) without the set variants', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_format')!({
+      docId: 'd1',
+      noBold: true,
+      noItalic: true,
+      noUnderline: true,
+      noStrikethrough: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'format', 'd1', '--no-bold', '--no-italic', '--no-underline', '--no-strikethrough'],
+      { account: undefined },
+    );
+  });
+
+  it('omits all flags when not provided (whole-doc no-op call passes through)', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_format')!({ docId: 'd1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'format', 'd1'], { account: undefined });
+  });
+});