gogcli-mcp-docs 2.21.1 → 2.23.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.21.1"
+    "version": "2.23.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.21.1",
+      "version": "2.23.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/README.md

@@ -62,7 +62,7 @@ Plus 5 auth tools and 7 base Docs tools (info, cat, create, write, find-replace,
 | `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_list` | List comments (open or resolved), optionally with each comment's tab and index ranges |
 | `gog_docs_comments_get` | Get a comment with its replies |
 | `gog_docs_comments_add` | Add a comment with optional quoted text |
 | `gog_docs_comments_reply` | Reply to a comment |

package/SKILL.md

@@ -46,7 +46,7 @@ Extended Google Docs MCP server via [gogcli](https://github.com/openclaw/gogcli)
 | `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_list` | List comments (open or resolved), optionally with each comment's tab and index ranges |
 | `gog_docs_comments_get` | Get a comment with replies |
 | `gog_docs_comments_add` | Add a comment with optional quoted text |
 | `gog_docs_comments_reply` | Reply to a comment |

package/dist/index.js

@@ -31430,6 +31430,13 @@ var TIMESTAMP_KEYS = /* @__PURE__ */ new Set([
   // Calendar event start/end
   "internalDate",
   // Gmail, epoch milliseconds (authoritative)
+  // gog >= 0.35.0 Gmail message AND thread listings. Already offset-bearing
+  // (RFC3339 from internalDate), so it needs no offset repair — it is
+  // allowlisted purely to gain a Display sibling, and to be re-rendered in
+  // DISPLAY_TZ like every other instant. Separately sourced from the sibling
+  // `date`, which is a naive re-format of the sender's Date header; the two may
+  // legitimately disagree. See docs/timestamps.md.
+  "internalDateIso",
   "modifiedTime",
   // Drive
   "createdTime",
@@ -31671,8 +31678,8 @@ function formatOneAccountHealth(a, now) {
   const age = ageInDays(a.created_at, now);
   const ageStr = age === null ? "" : ` Authorized ${age.toFixed(1)} day(s) ago.`;
   if (a.valid === false) {
-    const cause = INVALID_GRANT_PATTERN.test(a.error ?? "") ? 'refresh token expired or revoked \u2014 commonly the 7-day limit on OAuth consent screens still in "Testing" mode' : a.error?.trim() || "unknown error";
-    return `\u2717 ${email3}: NEEDS RE-AUTH \u2014 ${cause}.${ageStr} Re-authorize with gog_auth_add (browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless).`;
+    const cause2 = INVALID_GRANT_PATTERN.test(a.error ?? "") ? 'refresh token expired or revoked \u2014 commonly the 7-day limit on OAuth consent screens still in "Testing" mode' : a.error?.trim() || "unknown error";
+    return `\u2717 ${email3}: NEEDS RE-AUTH \u2014 ${cause2}.${ageStr} Re-authorize with gog_auth_add (browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless).`;
   }
   if (a.valid === true) {
     let line = `\u2713 ${email3}: token valid.${ageStr}`;
@@ -31714,7 +31721,7 @@ function registerAuthToolsWith(server, defaultServices) {
     }
   });
   server.registerTool("gog_auth_status", {
-    description: "Show gogcli auth configuration: keyring backend, credential files, and auth setup.",
+    description: "Show gogcli auth CONFIGURATION: keyring backend, credential files, and auth setup. Despite the name this is not a health check \u2014 it reads local setup and does not contact Google, so it says nothing about whether an account can still authenticate. Use gog_auth_health for that.",
     annotations: { readOnlyHint: true },
     inputSchema: {}
   }, async () => {
@@ -31725,7 +31732,7 @@ function registerAuthToolsWith(server, defaultServices) {
     }
   });
   server.registerTool("gog_auth_health", {
-    description: 'Check the LIVE health of each stored Google account. Unlike gog_auth_status (which only reports keyring/config setup), this performs a real token refresh against Google, so it detects expired or revoked (invalid_grant) refresh tokens \u2014 the account-wide sign-out that blocks every service. Reports per account: whether the token is currently valid, the mapped cause when it is not, how long ago it was authorized, and a warning as it approaches the 7-day refresh-token limit that applies to OAuth apps whose consent screen is still in "Testing" mode. Run it proactively to re-authorize on your own schedule instead of mid-task.',
+    description: 'Check the LIVE health of each stored Google account. Unlike gog_auth_status (which only reports keyring/config setup), this performs a real token refresh against Google, so it detects expired or revoked (invalid_grant) refresh tokens \u2014 the account-wide sign-out that blocks every service. Reports per account: whether the token is currently valid, the mapped cause when it is not, how long ago it was authorized, and a warning as it approaches the 7-day refresh-token limit that applies to OAuth apps whose consent screen is still in "Testing" mode. Run it proactively to re-authorize on your own schedule instead of mid-task. On the hosted connector this is the ONLY check that measures Google: a connector showing "connected" or "refreshed" has verified the connector key that reaches the gog machine, and nothing else \u2014 the Google credential lives on that machine and can be dead while the connection looks perfectly healthy.',
     annotations: { readOnlyHint: true },
     inputSchema: {}
   }, async () => {
@@ -31932,14 +31939,29 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.21.1" : "0.0.0";
+var VERSION = true ? "2.23.0" : "0.0.0";
 
 // ../gogcli-mcp/src/auth-log.ts
 var FAILURES = /* @__PURE__ */ new Set([
   "token.mint-failed",
   "grant.dead",
   "replay.failed",
-  "runner.auth-failed"
+  "runner.auth-failed",
+  "connect.key-rejected",
+  // An enrolment that could not proceed is a failure even though nobody is at
+  // fault: it is the only trace a half-enrolled connector leaves behind, and
+  // the absence of exactly this record is why DEFECT 4 could not be explained.
+  "connect.runner-unreachable",
+  "connect.google-unhealthy",
+  "refusal.google-unhealthy",
+  // The loudest record on this branch, and the only one that means "we cannot
+  // explain this". Google refused a real call while a live check of the same
+  // credential, taken seconds later, succeeded — so neither the 7-day cliff nor
+  // a revoked grant accounts for it. It is filed as a failure precisely because
+  // it is the record nobody may scroll past: it is the only evidence that could
+  // ever justify building something on the hosted path, and its absence over
+  // time is what retires that theory for good.
+  "refusal.google-ok"
 ]);
 var PREFIX = "gog-auth ";
 var TAG_CHARS = 12;
@@ -32086,10 +32108,39 @@ async function exchange(refreshToken, clientId, clientSecret) {
   return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
 }
 
+// ../gogcli-mcp/src/google-probe.ts
+var bool = (value) => typeof value === "boolean" ? value : void 0;
+var cause = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
+function readGoogleProbe(body) {
+  const record2 = typeof body === "object" && body !== null ? body : {};
+  const measured = bool(record2.measured);
+  const reported = cause(record2.error);
+  if (measured === false) {
+    return {
+      kind: "unmeasured",
+      reason: reported ?? "the runner reported it could not measure the Google layer"
+    };
+  }
+  if (measured === true) {
+    if (bool(record2.ok) === true) return { kind: "ok" };
+    return {
+      kind: "unhealthy",
+      reason: reported ?? "the runner reported the Google layer unhealthy with no cause"
+    };
+  }
+  return {
+    kind: "unmeasured",
+    reason: reported ? `the runner did not report whether it measured the Google layer; it said: ${reported}` : "the runner did not report whether it measured the Google layer"
+  };
+}
+
 // ../gogcli-mcp/src/connector-runtime.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEADLINE_GRACE_MS = 5e3;
 var MIN_REPLAY_BUDGET_MS = 1e3;
+var REFUSAL_PROBE_TIMEOUT_MS = 4e3;
+var MIN_PROBE_BUDGET_MS = 1e3;
+var PROBE_INTERVAL_MS = 6e4;
 var RUNNER_GOG_FAILED = 422;
 var RUNNER_DRAINING = 503;
 var RUNNER_BAD_REQUEST = 400;
@@ -32136,7 +32187,7 @@ function gogTarget(args) {
   }
   return { service };
 }
-async function remintAfterGoogleRejection(err, used, args, readAccessToken, deadlineAt) {
+async function remintAfterGoogleRejection(err, used, args, readAccessToken, deadlineAt, probeGoogle) {
   if (!(err instanceof GogFailedError)) return void 0;
   const grantDead = REFRESH_TOKEN_DEAD_PATTERN.test(err.stderr);
   if (!grantDead && !GOOGLE_TOKEN_REJECTED_PATTERN.test(err.stderr)) return void 0;
@@ -32151,6 +32202,7 @@ async function remintAfterGoogleRejection(err, used, args, readAccessToken, dead
     return void 0;
   }
   if (!used) {
+    await probeGoogle(where);
     logAuthTransition("replay.declined", {
       ...where,
       reason: "no access token was supplied with the call, so gog acted as the backend volume\u2019s own identity"
@@ -32198,6 +32250,64 @@ async function remintAfterGoogleRejection(err, used, args, readAccessToken, dead
   return { token: fresh, budgetMs, invalidate: readAccessToken.invalidate, ...where };
 }
 function makeFlyExecutor(endpoint, key, readAccessToken) {
+  let lastProbeAt = Number.NEGATIVE_INFINITY;
+  const probeGoogleAfterRefusal = async (where, deadlineAt) => {
+    const record2 = { ...where, endpoint };
+    const now = Date.now();
+    const remainingMs = deadlineAt - now;
+    if (remainingMs < MIN_PROBE_BUDGET_MS) {
+      logAuthTransition("refusal.google-unmeasured", {
+        ...record2,
+        reason: `only ${remainingMs}ms of the call\u2019s deadline remained, so the Google layer was not measured rather than delay the caller\u2019s own error`
+      });
+      return;
+    }
+    if (now - lastProbeAt < PROBE_INTERVAL_MS) {
+      logAuthTransition("refusal.google-unmeasured", {
+        ...record2,
+        // "attempted", not "measured". `lastProbeAt` is stamped before the
+        // fetch and is deliberately NOT reset when the probe comes back with no
+        // verdict (a 404 from a runner too old to have the endpoint, a timeout,
+        // a dead socket) — the backend cost this throttle exists to bound was
+        // paid either way, and resetting it would let a retry loop storm a
+        // runner that is already unwell. So the timestamp stays and the sentence
+        // has to be the true one: on this branch a log line may not assert a
+        // measurement that never happened, and the previous probe may well have
+        // measured nothing at all.
+        reason: "a Google probe was attempted recently, so another was not sent: this probe spawns gog on the backend and takes the keyring\u2019s exclusive lock"
+      });
+      return;
+    }
+    lastProbeAt = now;
+    let event;
+    let reason;
+    try {
+      const res = await fetch(`${endpoint}/health/google`, {
+        headers: { Authorization: `Bearer ${key}` },
+        // Never more than the probe's own budget, never more than the call has
+        // left. `Math.min` rather than a plain constant because the second
+        // bound is the caller's, and it outranks ours.
+        signal: AbortSignal.timeout(Math.min(REFUSAL_PROBE_TIMEOUT_MS, remainingMs))
+      });
+      if (!res.ok) {
+        event = "refusal.google-unmeasured";
+        reason = `the runner did not answer the Google probe (HTTP ${res.status})`;
+      } else {
+        const verdict = readGoogleProbe(await res.json());
+        if (verdict.kind === "ok") {
+          event = "refusal.google-ok";
+          reason = "Google refused this call, yet a live token check on the same volume succeeded \u2014 so a dead or expired refresh token does not explain this refusal";
+        } else {
+          event = verdict.kind === "unhealthy" ? "refusal.google-unhealthy" : "refusal.google-unmeasured";
+          reason = verdict.reason;
+        }
+      }
+    } catch (err) {
+      event = "refusal.google-unmeasured";
+      reason = err instanceof Error ? err.message : String(err);
+    }
+    logAuthTransition(event, { ...record2, reason });
+  };
   return async (args, opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
     const accessToken = await readAccessToken?.();
@@ -32210,7 +32320,8 @@ function makeFlyExecutor(endpoint, key, readAccessToken) {
         accessToken,
         args,
         readAccessToken,
-        deadlineAt
+        deadlineAt,
+        (where2) => probeGoogleAfterRefusal(where2, deadlineAt)
       );
       if (replay === void 0) throw err;
       const where = { credential: replay.credential, service: replay.service, endpoint };
@@ -32559,7 +32670,7 @@ function registerExtraDocsTools(server) {
     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)'),
+      file: external_exports.string().optional().describe(`Path to a text file to append, read on the gog server. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out.`),
       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
@@ -32641,19 +32752,23 @@ function registerExtraDocsTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_docs_comments_list", {
-    description: "List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments.",
+    description: "List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments. Set locate=true (or pass tab) to attach each comment's tab and Docs index ranges as location.matches[] plus location.orphaned \u2014 that costs one extra document fetch, but only one for the whole listing, where gog_docs_comments_locate costs one per comment. Either flag additionally requires the Docs scope; the plain listing needs only Drive. matches[] always spans every tab, so a quote appearing in two tabs is visible as an ambiguity rather than silently resolved. tab keeps only comments with a match in that tab, which drops orphaned comments and comments that quote nothing.",
     annotations: { readOnlyHint: true },
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       includeResolved: external_exports.boolean().optional().describe("Include resolved comments (default: false, open only)"),
       since: external_exports.string().optional().describe("Only return comments modified at or after this RFC3339 timestamp (e.g. 2026-06-01T00:00:00Z)"),
+      locate: external_exports.boolean().optional().describe("Attach each comment's tab and Docs index ranges (location.matches[] + location.orphaned) using one extra document fetch shared across the whole listing"),
+      tab: external_exports.string().optional().describe("Only return comments whose quoted text resolves inside this tab (title or ID). Implies locate, and drops orphaned and unquoted comments."),
       ...paginationParams,
       account: accountParam
     }
-  }, async ({ docId, includeResolved, since, max, page, all, account }) => {
+  }, async ({ docId, includeResolved, since, locate, tab, max, page, all, account }) => {
     const args = ["docs", "comments", "list", docId];
     if (includeResolved) args.push("--include-resolved");
     if (since) args.push(`--since=${since}`);
+    if (locate) args.push("--locate");
+    if (tab) args.push(`--tab=${tab}`);
     pushPaginationFlags(args, { max, page, all });
     return runOrDiagnose(args, { account });
   });
@@ -33386,7 +33501,7 @@ function registerExtraDocsTools(server) {
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       text: external_exports.string().optional().describe("Footnote text"),
-      file: external_exports.string().optional().describe('Read footnote text from a file ("-" for stdin)'),
+      file: external_exports.string().optional().describe(`Read footnote text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out.`),
       index: external_exports.number().int().optional().describe("Character index to place the reference mark at (1 = beginning). Omit or use atEnd for end-of-doc."),
       atEnd: external_exports.boolean().optional().describe("Target end-of-doc/tab (mutually exclusive with index and at)"),
       at: external_exports.string().optional().describe("Anchor by literal text and place the reference mark at the start of the matched range"),
@@ -33505,7 +33620,7 @@ function registerExtraDocsTools(server) {
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       text: external_exports.string().optional().describe("Initial header text"),
-      file: external_exports.string().optional().describe('Read initial header text from a file ("-" for stdin)'),
+      file: external_exports.string().optional().describe(`Read initial header text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out.`),
       index: external_exports.number().int().optional().describe("Character index identifying the section the header belongs to (1 = beginning). Omit or use atEnd for end-of-doc."),
       atEnd: external_exports.boolean().optional().describe("Target end-of-doc/tab (mutually exclusive with index and at)"),
       at: external_exports.string().optional().describe("Anchor by literal text and target the section at the start of the matched range"),
@@ -33559,7 +33674,7 @@ function registerExtraDocsTools(server) {
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       text: external_exports.string().optional().describe("Initial footer text"),
-      file: external_exports.string().optional().describe('Read initial footer text from a file ("-" for stdin)'),
+      file: external_exports.string().optional().describe(`Read initial footer text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out.`),
       index: external_exports.number().int().optional().describe("Character index identifying the section the footer belongs to (1 = beginning). Omit or use atEnd for end-of-doc."),
       atEnd: external_exports.boolean().optional().describe("Target end-of-doc/tab (mutually exclusive with index and at)"),
       at: external_exports.string().optional().describe("Anchor by literal text and target the section at the start of the matched range"),

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "2.21.1",
+  "version": "2.23.0",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",
@@ -165,7 +165,7 @@
     },
     {
       "name": "gog_docs_comments_list",
-      "description": "List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments."
+      "description": "List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments, or locate/tab to attach each comment's tab and index ranges in one extra fetch."
     },
     {
       "name": "gog_docs_comments_get",

package/package.json

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

package/src/tools/docs-extra.ts

@@ -284,7 +284,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     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)'),
+      file: z.string().optional().describe('Path to a text file to append, read on the gog server. gog also accepts "-" for stdin, but this server never writes to gog\'s stdin, so "-" would hang until the call times out.'),
       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,
@@ -372,19 +372,28 @@ export function registerExtraDocsTools(server: McpServer): void {
   // Comment-thread tools
   server.registerTool('gog_docs_comments_list', {
     description:
-      'List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments.',
+      'List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments. ' +
+      'Set locate=true (or pass tab) to attach each comment\'s tab and Docs index ranges as location.matches[] plus location.orphaned — ' +
+      'that costs one extra document fetch, but only one for the whole listing, where gog_docs_comments_locate costs one per comment. ' +
+      'Either flag additionally requires the Docs scope; the plain listing needs only Drive. ' +
+      'matches[] always spans every tab, so a quote appearing in two tabs is visible as an ambiguity rather than silently resolved. ' +
+      'tab keeps only comments with a match in that tab, which drops orphaned comments and comments that quote nothing.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       includeResolved: z.boolean().optional().describe('Include resolved comments (default: false, open only)'),
       since: z.string().optional().describe('Only return comments modified at or after this RFC3339 timestamp (e.g. 2026-06-01T00:00:00Z)'),
+      locate: z.boolean().optional().describe('Attach each comment\'s tab and Docs index ranges (location.matches[] + location.orphaned) using one extra document fetch shared across the whole listing'),
+      tab: z.string().optional().describe('Only return comments whose quoted text resolves inside this tab (title or ID). Implies locate, and drops orphaned and unquoted comments.'),
       ...paginationParams,
       account: accountParam,
     },
-  }, async ({ docId, includeResolved, since, max, page, all, account }) => {
+  }, async ({ docId, includeResolved, since, locate, tab, max, page, all, account }) => {
     const args = ['docs', 'comments', 'list', docId];
     if (includeResolved) args.push('--include-resolved');
     if (since) args.push(`--since=${since}`);
+    if (locate) args.push('--locate');
+    if (tab) args.push(`--tab=${tab}`);
     pushPaginationFlags(args, { max, page, all });
     return runOrDiagnose(args, { account });
   });
@@ -1177,7 +1186,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       text: z.string().optional().describe('Footnote text'),
-      file: z.string().optional().describe('Read footnote text from a file ("-" for stdin)'),
+      file: z.string().optional().describe('Read footnote text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog\'s stdin, so "-" would hang until the call times out.'),
       index: z.number().int().optional().describe('Character index to place the reference mark at (1 = beginning). Omit or use atEnd for end-of-doc.'),
       atEnd: z.boolean().optional().describe('Target end-of-doc/tab (mutually exclusive with index and at)'),
       at: z.string().optional().describe('Anchor by literal text and place the reference mark at the start of the matched range'),
@@ -1304,7 +1313,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       text: z.string().optional().describe('Initial header text'),
-      file: z.string().optional().describe('Read initial header text from a file ("-" for stdin)'),
+      file: z.string().optional().describe('Read initial header text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog\'s stdin, so "-" would hang until the call times out.'),
       index: z.number().int().optional().describe('Character index identifying the section the header belongs to (1 = beginning). Omit or use atEnd for end-of-doc.'),
       atEnd: z.boolean().optional().describe('Target end-of-doc/tab (mutually exclusive with index and at)'),
       at: z.string().optional().describe('Anchor by literal text and target the section at the start of the matched range'),
@@ -1361,7 +1370,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       text: z.string().optional().describe('Initial footer text'),
-      file: z.string().optional().describe('Read initial footer text from a file ("-" for stdin)'),
+      file: z.string().optional().describe('Read initial footer text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog\'s stdin, so "-" would hang until the call times out.'),
       index: z.number().int().optional().describe('Character index identifying the section the footer belongs to (1 = beginning). Omit or use atEnd for end-of-doc.'),
       atEnd: z.boolean().optional().describe('Target end-of-doc/tab (mutually exclusive with index and at)'),
       at: z.string().optional().describe('Anchor by literal text and target the section at the start of the matched range'),

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

@@ -503,6 +503,82 @@ describe('gog_docs_comments_list', () => {
       { account: undefined },
     );
   });
+
+  // gog 0.35.0 (openclaw/gogcli#965) adds --locate/--tab, which share ONE
+  // documents.get(includeTabsContent=true) across every comment on the page.
+  // The pre-0.35.0 way to answer "which tab is this comment in?" was one
+  // `docs comments locate` per comment — 30 fetches for a 30-comment doc.
+  it('includes --locate when requested', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_docs_comments_list', { docId: 'abc', locate: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'comments', 'list', 'abc', '--locate'],
+      { account: undefined },
+    );
+  });
+
+  it('omits --locate when false', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_docs_comments_list', { docId: 'abc', locate: false });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', 'abc'], { account: undefined });
+  });
+
+  it('includes --tab, which gog treats as implying --locate', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_docs_comments_list', { docId: 'abc', tab: 'Notes' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'comments', 'list', 'abc', '--tab=Notes'],
+      { account: undefined },
+    );
+  });
+
+  // gog rejects an explicitly empty --tab (`--tab requires a non-empty tab
+  // title or ID`), so an empty string must never reach the arg array.
+  it('never emits an empty --tab', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_docs_comments_list', { docId: 'abc', tab: '' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', 'abc'], { account: undefined });
+  });
+
+  it('combines --locate and --tab with the existing filters and pagination', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_docs_comments_list', {
+      docId: 'abc', includeResolved: true, since: '2026-06-01T00:00:00Z',
+      locate: true, tab: 'Notes', max: 10, page: 'tok', all: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      [
+        'docs', 'comments', 'list', 'abc',
+        '--include-resolved',
+        '--since=2026-06-01T00:00:00Z',
+        '--locate',
+        '--tab=Notes',
+        '--max=10', '--page=tok', '--all',
+      ],
+      { account: undefined },
+    );
+  });
+
+  it('description states the extra fetch, the Docs scope, and that --tab drops orphans', async () => {
+    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_comments_list')?.description ?? '';
+    expect(desc).toMatch(/one extra/i);
+    expect(desc).toMatch(/Docs scope/);
+    expect(desc).toMatch(/orphan/i);
+  });
 });
 
 describe('gog_docs_table_column_width', () => {
@@ -2156,3 +2232,35 @@ describe('gog_docs_format spacingMode', () => {
     );
   });
 });
+
+// Same trap the gmail package documents: gog resolves a "-" path through
+// io.ReadAll(stdinReader(ctx)) (docs_helpers.go resolveContentInput:26 and
+// readTextInput:83 at upstream-v0.35.0 — os.Stdin, unaffected by --no-input),
+// but runner.ts spawns with default stdio and never writes to or ends
+// child.stdin, so the call blocks until the 30s timeout fires. Reproduced
+// against a live gog v0.35.0: the child was still running with zero output
+// after 5s. These descriptions must warn, not offer.
+describe('server-side file params never advertise stdin as usable', () => {
+  const STDIN_PARAMS: Array<[tool: string, param: string]> = [
+    ['gog_docs_append', 'file'],
+    ['gog_docs_insert_footnote', 'file'],
+    ['gog_docs_header_create', 'file'],
+    ['gog_docs_footer_create', 'file'],
+  ];
+
+  it.each(STDIN_PARAMS)('%s.%s warns that stdin hangs instead of offering it', async (tool, param) => {
+    const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+    const server = new McpServer({ name: 'test', version: '0.0.0' });
+    const schemas = new Map<string, Record<string, { description?: string }>>();
+    vi.spyOn(server, 'registerTool').mockImplementation((name, config) => {
+      schemas.set(name, (config as { inputSchema: Record<string, { description?: string }> }).inputSchema);
+      return undefined as never;
+    });
+    registerExtraDocsTools(server);
+    const desc = schemas.get(tool)?.[param]?.description ?? '';
+    expect(desc).not.toBe('');
+    expect(desc).not.toMatch(/(?:use|or)\s+"?-"?\s*(?:for|to read)/i);
+    expect(desc).toMatch(/stdin/i);
+    expect(desc).toMatch(/hang|never writes/i);
+  });
+});