mcp-gee-sweet 0.9.2.dev306__tar.gz → 0.9.2.dev313__tar.gz

{mcp_gee_sweet-0.9.2.dev306 → mcp_gee_sweet-0.9.2.dev313}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-gee-sweet
-Version: 0.9.2.dev306
+Version: 0.9.2.dev313
 Summary: MCP server for Google Workspace — Sheets, Drive, Docs (HTML or Markdown), and Calendar.
 Project-URL: Homepage, https://github.com/khuisman/mcp-gee-sweet
 Project-URL: Bug Tracker, https://github.com/khuisman/mcp-gee-sweet/issues

mcp_gee_sweet-0.9.2.dev313/docs/design/doc-revision-export.md

@@ -0,0 +1,126 @@
+# Design: Google Doc Revisions as Markdown (`export_revision`)
+
+**Status:** Implemented. Issue #959. Live-verified against real Drive/Docs API calls via scratch
+scripts per `CLAUDE.md`'s "Verify a ticket's API premise live" convention (2026-10-11).
+
+## Problem
+
+`export_revision` handled only Sheets (XLSX export → cell values). `list_revisions` already
+listed Doc revisions, but nothing could read one, so "what changed in this Doc since revision N"
+couldn't be answered through the server. The issue asked for a Doc revision as Markdown "through
+the same converter `get_doc_as_markdown` uses", so that diffing two revisions' exports shows only
+the edit.
+
+## The constraint
+
+`get_doc_as_markdown` walks `documents().get()` into the AST (`doc-to-markdown.md`). The Docs API
+reads only a document's **current** state; it has no revision parameter. Drive is the only source
+of an old revision, and only as a file from the revision's `exportLinks`. Measured on a Doc
+revision: `text/markdown`, `text/x-markdown`, `text/html`, `text/plain`, DOCX, ODT, RTF, PDF, EPUB,
+and a zipped HTML.
+
+## Options measured
+
+Each option was run against the same Doc, written through `write_doc_content` with headings, bold
+and italic, inline code, a fenced code block, a blockquote, nested ordered/bulleted lists, task
+items, a table, an image, and heading links.
+
+1. **Drive's own `text/markdown` export.** Lossy: inline code became plain text, the fenced code
+   block became soft-broken plain lines, the blockquote became a plain paragraph, a nested bullet
+   inside a numbered list became a separate numbered item with a literal `\-`, and the image was
+   inlined as a base64 `data:` URI (10KB for one small logo). It's a different dialect from
+   `get_doc_as_markdown`, and a much less faithful one.
+2. **`text/html` export → this project's `html_parser` → AST.** Google's export carries styling in
+   CSS classes (`.c3{font-weight:700}`), which `html_parser` doesn't read, so bold, italic and code
+   fonts would be lost without a CSS resolver. Importing that HTML back into a Doc (to reuse the
+   Docs-side converter) was also measured: it split the code block into one fence per line and
+   turned every list item after the blockquote into a quote.
+3. **DOCX export → import as a temporary Google Doc → `document_to_ast` → `ast_to_markdown`.**
+   The output was **identical** to `get_doc_as_markdown` on the live Doc, except for the two
+   import-specific values below. The zipped-HTML export can't be imported (400).
+
+**Chosen: (3).** It is the same converter, not an equivalent one, so everything
+`get_doc_as_markdown` supports and documents carries over unchanged.
+
+## What differs on every import, and how it's made stable
+
+Measured across two imports of the same DOCX:
+
+- **Inline image `contentUri`.** A new URL each import; the image bytes are identical (same
+  SHA-256). `_stabilize_images` fetches each image (concurrency 8) while the temporary Doc still
+  exists and replaces its `contentUri` with `image:sha256-<first 16 hex digits>`, so an unchanged
+  image doesn't show in a diff and a changed one does. A failed fetch renders
+  `image:unavailable`. No viewable URL is returned: PR #988's QA round found the temporary Doc's
+  image URLs 404 (anonymously and authenticated) once it's deleted, so a returned URL would be
+  dead on arrival. (One earlier probe got a 200 right after deletion; it doesn't hold.)
+- **Heading IDs and the document ID.** Every heading gets a new `headingId`, and
+  `doc_to_ast._link_url` rebuilds an ID-only heading link (the kind the Docs UI creates) as a URL
+  containing the temporary Doc's ID. That changes on every export and points at a deleted Doc.
+  `_stabilize_internal_links` rewrites a heading link to `#<slug>`, using anchors.py's GitHub-style
+  slug with `-1`/`-2` duplicate suffixes, so the link survives a round trip through the write
+  side's anchor resolver. The slug list holds only paragraphs that render as Markdown headings,
+  classified by `doc_to_ast._paragraph_to_node` itself (`Heading`, or a TITLE/SUBTITLE
+  `NamedBlock`): a bulleted heading renders as a list item and a heading in a table cell as cell
+  text, and counting them shifted every later duplicate's suffix onto the wrong heading (PR #988
+  QA round 1). A link to a heading that doesn't render as one is dropped, following the project's
+  rule that a wrong link is worse than none.
+- **Bookmark links are dropped.** A bookmark has no text to name it, and any `#fragment` made up
+  for one can be fuzzy-matched by `anchors.py` to a heading when the Markdown is written back
+  (`#bookmark-1` → the second heading titled "Bookmark"; PR #988 QA round 1).
+- URL links written by this project's own write side are already absolute URLs and pass through
+  unchanged.
+
+## The temporary Doc
+
+- Created in the default folder (`lc.folder_id`), like every other create path, so a service
+  account works when a Shared Drive is configured. A storageQuotaExceeded error renders with the
+  shared `_SA_QUOTA_ERROR` text. Who can see it there, and its 30 days in the trash when the
+  identity can only trash, is tracked in #989.
+- Uploaded resumable: Drive takes a multipart upload only up to 5 MB, and a revision with
+  embedded images can exceed it.
+- Named `export_revision temp (<file_id> r<revision_id>)`, so an orphan is identifiable.
+- Created inside `anyio.CancelScope(shield=True)`, per `CLAUDE.md`'s cancellation rule: a
+  cancellation can't land after Drive created the Doc but before its ID is recorded.
+- Removed in a shielded `finally`: deleted when `capabilities.canDelete` allows it, else trashed
+  (a Content manager on a Shared Drive can only trash, #876). The removal retries a 5xx or 429
+  (`num_retries=3`), since a failed removal leaves a copy of the revision in Drive. A failed removal
+  never hides the export: the result gets a `warning` naming the Doc's ID.
+- Because it writes to Drive, `export_revision` is no longer annotated `readOnlyHint`; it's
+  `destructiveHint=False`, since it changes nothing of the caller's.
+- About 5–6 seconds per call, measured, on top of the image fetches.
+
+## Errors found while measuring
+
+- The export endpoint answers rapid calls with HTTP 429 and an HTML page, without raising. The
+  Sheets path handed that page straight to openpyxl. `_fetch_revision_export` checks the status
+  for both paths.
+- Docs folds the latest revision into the next one while editing continues: revision 18 was
+  listed, an edit 90 seconds later produced 19, and 18 then returned 404. A second run with a
+  5-minute gap merged 19 into 20 the same way. `export_revision` turns a "Revision not found" 404
+  into an error telling the caller to call `list_revisions` again. Any other 404, such as a bad
+  file ID ("File not found"), is re-raised unchanged. A Doc created by Drive import keeps its
+  import revision separate (as #814 measured).
+- `revisions.list` returns at most 200 revisions per page by default (discovery document), and
+  `list_revisions` read only the first page. It now pages through every revision via the same
+  `_list_revisions` helper `sync_folder` uses.
+- A Doc `local_path` is checked with `_validate_local_destination` before the export, so a bad
+  destination fails before the temporary Doc round trip.
+
+## Live verification
+
+Against a Doc imported through `upload_file(convert_to_doc=True)`, then edited by inserting one
+word: exporting revision 1 (the import) and revision 2 and diffing the two `markdown` values gave
+exactly one changed line, the edited paragraph. On a `write_doc_content` Doc with every construct
+above plus two `Setup` headings linked by ID, the export matched `get_doc_as_markdown` except the
+image line and the two links (`#setup`, `#setup-1`). With the first `Setup` bulleted, it rendered
+as `- Setup`, the link to it was dropped, and the link to the second rendered as `#setup`.
+
+## What this does NOT do
+
+- **Comments.** They aren't part of a revision, so there's no `include_comments`.
+- **Match `get_doc_as_markdown` byte for byte.** Heading links and images differ by design (above).
+  Diff a revision against another revision's export, not against the live Doc's
+  `get_doc_as_markdown`.
+- **Show an old revision's images.** Only their hashes; see above.
+- **Multi-tab documents: not measured.** How Drive's DOCX export handles a Doc's extra tabs
+  wasn't checked; `document_to_ast` reads only the imported Doc's body.

{mcp_gee_sweet-0.9.2.dev306 → mcp_gee_sweet-0.9.2.dev313}/docs/design/index.md

@@ -15,3 +15,4 @@ These are more granular than the [decision records](../decisions/index.md), whic
 | [SSE OAuth Consent Off the Event Loop](sse-consent-off-event-loop.md) | 2026-10-01 | #833: the SSE consent wait on a daemon thread with a stoppable callback server, shared across connections, ended by sse_starlette's shutdown flag on SIGTERM |
 | [Re-authorizing OAuth from the Failing Tool Call](oauth-reauthorize-from-tool-call.md) | 2026-10-06 | #873/#906: a revoked or missing token offers the consent link from the failing call (URL elicitation, or the link in the `ToolError`), detected at `thread_http`'s transport so tools that catch errors are covered, adopted in place on every connection |
 | [Local-File Access Policy](local-file-access-policy.md) | 2026-10-10 | #796: `LOCAL_FILE_ACCESS=full\|roots\|off` resolved at import from argv (plus an HTTP-request tripwire for launches argv can't see), one `check_read`/`check_write` at each choke point and per entry in folder walks, an identity-based (`samefile`) deny-list of the server's own credential/config/cache/log files, `@tool(local_only=True)` unregistering nine tools in `off` mode, mode and roots reported in `server://auth-status` and the refusal |
+| [Google Doc Revisions as Markdown](doc-revision-export.md) | 2026-10-11 | #959: `export_revision` on a Doc via DOCX export → temporary Doc → `get_doc_as_markdown`'s own converter (Drive's Markdown and HTML exports measured lossy), heading links and image URLs rewritten so two exports diff cleanly, shielded temp-Doc cleanup |

{mcp_gee_sweet-0.9.2.dev306 → mcp_gee_sweet-0.9.2.dev313}/docs/known-limitations.md

@@ -120,6 +120,37 @@ raw Docs API via `batch_update` passthrough) instead. Related: docs/design/doc-t
 
 ---
 
+### `export_revision` on a Google Doc — links, images, and vanishing revision IDs
+
+**What:** `export_revision` (#959) returns a Doc revision as Markdown through the same converter
+as `get_doc_as_markdown`, with these differences and gaps:
+
+1. A link to a heading renders as a GitHub-style `#slug` anchor, not as a docs.google.com URL.
+   A link to a bookmark, or to a heading that doesn't render as one (a bulleted heading, or one
+   in a table cell), is dropped and leaves its text. An image renders as
+   `image:sha256-<hash>`, with no viewable URL: the temporary Doc's image URLs stop working
+   once it's deleted, so an old revision's images can't be viewed this way.
+2. The export doesn't include comments, which aren't part of a revision.
+3. A revision ID from `list_revisions` can stop existing: Docs folds a recent revision into the
+   next one while editing continues (measured: edits 90 seconds and 5 minutes later both merged it).
+   The export then fails with an error saying to list revisions again.
+4. Each call creates and removes a temporary Google Doc in the default folder, which takes
+   several seconds and needs storage there (a service account needs a Shared Drive default
+   folder). If removal fails, the result's `warning` names the Doc to delete by hand.
+
+**Why:** The Docs API reads only a document's current state, so the revision is exported as DOCX
+and imported into a temporary Doc to be read. That Doc's ID, heading IDs, and image URLs are new
+on every import, so (1) replaces them with values that stay the same between exports and keep
+diffs clean. A bookmark has no text to make a stable anchor from, and an invented one could be
+matched to the wrong heading if the Markdown is written back. (3) is how Drive keeps Docs
+revision history.
+
+**Workaround:** For (1), diff one revision's export against another's, not against
+`get_doc_as_markdown` output. For (3), export a revision only after editing has settled.
+Related: docs/design/doc-revision-export.md.
+
+---
+
 ## Google Drive
 
 ### Service account cannot create files in personal Drive

{mcp_gee_sweet-0.9.2.dev306 → mcp_gee_sweet-0.9.2.dev313}/docs/qa/tests/drive_transfer.md

@@ -1933,11 +1933,202 @@ export_revision(rev 6, no range) → sheet="Sheet1", range=null, values = full 5
 - Returns a clear error: "No XLSX export available for this revision"
 - Does not crash
 
+**Superseded by #959:** a Google Doc revision now exports as Markdown (TC-D280), so this case
+checks a file that is neither a Sheet nor a Doc. Run it as:
+
+**Setup:** Create a scratch Google Slides file named `qa-959-slides` in `DRIVE_FOLDER_ID`, and
+type one word on its first slide in the Slides UI (Playwright) so it has a revision.
+
+**Tool calls**
+1. `list_revisions(file_id="<slides-id>")`, then
+   `export_revision(file_id="<slides-id>", revision_id="<last revisionId>")`
+
+**Checks**
+- Raises a clear error: "No XLSX or DOCX export available for revision <id>. export_revision
+  supports Google Sheets and Google Docs files only."
+- Does not crash
+
+**Teardown:** `delete_file(file_id="<slides-id>")`.
+
+The 2026-09-04 Result below predates #959 and tested a Google Doc.
+
+**Result (2026-10-11, PR #988 round 1, `8b223c5`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth). The Slides file was created blank by a scratch-script `files().create(mimeType=presentation)` rather than through the Slides UI; `list_revisions` still listed revision 1. `export_revision` raised exactly "No XLSX or DOCX export available for revision 1. export_revision supports Google Sheets and Google Docs files only." Slides file trashed.
+
 **Result (2026-09-04) ✅ PASS**
 export_revision({DOC_ID}, rev 3) → error "No XLSX export available for revision 3. The file may not be a Google Sheets file." Clear error, no crash.
 
 ---
 
+### TC-D280: Export two Google Doc revisions as Markdown; the diff shows only the edit (issue #959) ⚠️ requires-oauth
+
+**Background:** The Docs API can't read an old revision, so `export_revision` exports it as DOCX,
+imports that into a temporary Doc, and converts it with `get_doc_as_markdown`'s own converter.
+Docs folds the latest revision into the next one while editing continues: during #959, edits 90
+seconds and 5 minutes later both merged it. A Doc created by Drive import keeps its import
+revision separate (#814), so the diff below uses one.
+
+**Setup**
+1. `create_doc(title="qa-959-rev", content_format="markdown", content=<below>)` with:
+   ````
+   # Release Notes
+
+   Intro with **bold**, *italic*, `inline code`, and [external](https://example.com).
+
+   ## Setup
+
+   ```
+   pip install thing
+   thing --init
+   ```
+
+   > A quoted note.
+
+   1. First step
+   2. Second step
+
+   - [ ] open task
+   - [x] done task
+
+   | Key | Value |
+   |-----|-------|
+   | a   | 1     |
+
+   ![logo](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)
+   ````
+   Then `list_revisions(file_id="<rev-id>")` and take the last `revisionId` as R.
+2. `upload_file(name="qa-959-diff.md", source_format="markdown", convert_to_doc=True,
+   content="# Notes\n\nIntro with **bold** text.\n\n## Next\n\nClosing paragraph.\n")`.
+   Then `find_in_doc(doc_id="<diff-id>", query="Intro with")` and
+   `insert_doc_text(doc_id="<diff-id>", insertions=[{"index": <start_index + 6>, "text": "EDITED "}])`.
+3. Wait about a minute, then `list_revisions(file_id="<diff-id>")`: A is the first revision
+   (the import), B the last. If only one revision is listed, wait another minute and re-list.
+
+**Tool calls**
+1. `export_revision(file_id="<rev-id>", revision_id="<R>")`
+2. `get_doc_as_markdown(doc_id="<rev-id>")`
+3. `export_revision(file_id="<diff-id>", revision_id="<A>")`
+4. `export_revision(file_id="<diff-id>", revision_id="<B>")`
+5. `search_files(query="export_revision temp")`
+
+**Checks**
+- Call 1's `markdown` has the heading, bold/italic, `` `inline code` ``, a fenced code block, a
+  `> ` blockquote, the numbered list, both task items, the table, and the image as
+  `![](image:sha256-<16 hex>)`. The result has no `images` key: the temporary Doc's image URLs
+  stop serving once it's deleted, so none is returned (PR #988 round 1).
+- Call 2's `markdown` equals call 1's except the image line (call 2 has a URL).
+- Diffing call 3's `markdown` against call 4's shows exactly one changed line: `Intro with` →
+  `Intro EDITED with`.
+- Call 5 returns no temporary Doc for `<rev-id>` or `<diff-id>`: each was removed. `search_files`
+  also lists trashed files, so a hit from an earlier run is fine if `get_file_metadata` shows
+  `trashed: true`.
+
+**Teardown:** `delete_file` on both `<rev-id>` and `<diff-id>`.
+
+**Result (2026-10-11, PR #988 round 1, `8b223c5`) ❌ FAIL (sent back)** — Ran via `mcp-gee-sweet-kit` (OAuth). `qa-959-rev` listed revisions 1 and 5; R=5. `qa-959-diff.md` listed revisions 1 and 2 about 10 seconds after the edit (no wait needed). Call 1's `markdown` had every listed construct and the image as `![](image:sha256-9237fdb37f9592f6)`. Call 2's `markdown` matched it byte for byte except the image line. Calls 3 and 4 differed in exactly one line, `Intro with` → `Intro EDITED with`. Call 5 returned `[]`. **Failed check:** the `images[0].url` from call 1 returned **HTTP 404** both to an anonymous `curl` and to an OAuth-authenticated `AuthorizedSession.get`, while the live Doc's own image URL from call 2 returned 200 `image/png` anonymously. A repeat export, fetched within seconds of the call returning, also returned 404. The temporary Doc's `contentUri` stops serving once that Doc is deleted, so every `images` URL is already dead when the tool returns (contradicts `docs/design/doc-revision-export.md`'s "the URL still serves after the temporary Doc is deleted"). Both Docs trashed.
+
+**Result (2026-10-11, PR #988 round 2, `15d778d`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth). `qa-959-rev` listed revisions 1 and 5; R=5. `qa-959-diff.md` listed 1 and 2 about 10 seconds after the edit. Call 1 returned `revisionId`, `modifiedTime`, `markdown` and no `images` key; `markdown` had every listed construct and the image as `![](image:sha256-9237fdb37f9592f6)` (same hash as round 1). Call 2 matched call 1 byte for byte except the image line. Calls 3 and 4 differed in exactly one line, `Intro with` → `Intro EDITED with`. Call 5 listed no temporary Doc from this pass; its one hit was a temporary Doc from the Dev's 15:15 probe of another Doc, already `trashed: true` (the trash branch working; `search_files` lists trashed files, so the check now says so). Both Docs trashed.
+
+---
+
+### TC-D281: Doc revision heading links render as `#slug` and stay stable (issue #959) ⚠️ requires-oauth
+
+**Setup**
+1. `create_doc(title="qa-959-links", content_format="markdown", content="# Top\n\n## Setup\n\nFirst.\n\n## Setup\n\nJump here and back here.\n")`
+2. Link text to the headings by ID, the way the Docs UI does. No tool sets an ID-only link
+   (`style_doc_range`'s `link_url` sets a URL), so use the Docs UI in Playwright (select "Jump",
+   Insert link → Headings → the first `Setup`; "back" → the second `Setup`), or a scratch script
+   per `CLAUDE.md`'s "MCP restart" note sending `updateTextStyle` with
+   `textStyle: {"link": {"headingId": "<id>"}}`. `get_doc_structure(doc_id="<id>")` gives both
+   headings' `headingId`s.
+3. `list_revisions(file_id="<id>")` and take the last `revisionId`.
+4. Make a second Doc, `qa-959-bullet`, the same way (steps 1–2), then turn its first `## Setup`
+   into a bulleted list item: `create_paragraph_bullets` over that heading's range (indices from
+   `get_doc_structure`). `list_revisions` on it and take the last `revisionId`.
+
+**Tool calls**
+1. `export_revision(file_id="<id>", revision_id="<last>")`
+2. The same call again.
+3. `export_revision(file_id="<bullet-id>", revision_id="<bullet last>")`
+
+**Checks**
+- Call 1's `markdown` contains `[Jump](#setup)` and `[back](#setup-1)`, and no
+  `docs.google.com` URL.
+- Call 2's `markdown` is identical to call 1's.
+- Call 3's `markdown` renders the first `Setup` as a list item (`- Setup`), leaves "Jump" as
+  plain text (its target doesn't render as a heading), and contains `[back](#setup)`: the
+  bulleted heading takes no slug (PR #988 round 1).
+
+**Teardown:** `delete_file` on both Docs.
+
+**Result (2026-10-11, PR #988 round 1, `8b223c5`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth). Links set by a scratch script (`updateTextStyle` with `link: {headingId}`). Revision 4: both calls returned `[Jump](#setup) here and [back](#setup-1) here.` with no `docs.google.com` URL, byte-identical. **Extra probe (sent back as a review finding):** a second Doc with the first `## Setup` turned into a bulleted list item (`createParagraphBullets`) and the same two links exported as `- Setup\n\n## Setup\n\n[Jump](#setup) here and [back](#setup-1) here.` The bulleted heading renders as a list item, not a heading, but still takes a slug. `#setup` now names the wrong heading and `#setup-1` names none. Both Docs trashed.
+
+**Result (2026-10-11, PR #988 round 2, `15d778d`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth). Links set by a scratch script (`updateTextStyle` with `link: {headingId}`). Calls 1 and 2 (revision 4) both returned `[Jump](#setup) here and [back](#setup-1) here.`, byte-identical, no `docs.google.com` URL. Call 3 (`qa-959-bullet`, revision 5) returned `# Top\n\n- Setup\n\nFirst.\n\n## Setup\n\nJump here and [back](#setup) here.`: the bulleted heading takes no slug and the link to it is dropped. **Extra probe:** a Doc with `## Setup`, then a table whose first cell is a HEADING_2 `Setup`, then a second body `## Setup`; "Jump" linked to the last body heading and "here" to the cell heading. The export was `[Jump](#setup-1) here.`: the cell heading is skipped when counting duplicates (it was `#setup-2` before the fix), and the link to it is dropped. All three Docs trashed.
+
+---
+
+### TC-D282: Doc revision `local_path`, and arguments that don't apply to the file's type (issue #959) ⚠️ local-filesystem ⚠️ requires-oauth
+
+**Setup:** `mkdir -p /tmp/qa-959` (the directory must exist: a `local_path` naming a missing
+directory, even with a trailing `/`, is written as a file of that name).
+`create_doc(title="qa-959-args", content="<p>Saved to disk</p>")`, then
+`list_revisions` on it and on `TEST_SPREADSHEET_ID`, taking each one's last `revisionId`.
+
+**Tool calls**
+1. `export_revision(file_id="<doc-id>", revision_id="<doc rev>", local_path="/tmp/qa-959/")`
+2. `export_revision(file_id="<doc-id>", revision_id="<doc rev>", range="A1:B2")`
+3. `export_revision(file_id="<TEST_SPREADSHEET_ID>", revision_id="<sheet rev>", local_path="/tmp/qa-959/")`
+4. `export_revision(file_id="<TEST_SPREADSHEET_ID>", revision_id="<sheet rev>", range="A1:B2")`
+5. `export_revision(file_id="<doc-id>", revision_id="999999")`
+6. `export_revision(file_id="<doc-id>_WRONG", revision_id="<doc rev>")`
+7. `export_revision(file_id="<doc-id>", revision_id="<doc rev>", local_path="/etc/hosts/x.md")`,
+   then `search_files(query="export_revision temp")`
+
+**Checks**
+- Call 1 returns `local_path` ending `/tmp/qa-959/<doc-id>-r<doc rev>.md`, `bytes_written`,
+  `revisionId`, `modifiedTime`, and no `markdown` or `images`. The file holds raw Markdown
+  (`Saved to disk`), not JSON.
+- Call 2 raises "…is a Google Doc; range and sheet apply only to Google Sheets."
+- Call 3 raises "…is a Google Sheet; local_path applies only to Google Docs."
+- Call 4 returns `sheet`, `range`, and `values` exactly as before #959.
+- Call 5 raises "Revision 999999 of <doc-id> not found…call list_revisions again…".
+- Call 6 raises Drive's own 404 ("File not found: <doc-id>_WRONG"), not the merged-revision
+  message (PR #988 round 1).
+- Call 7 raises "local_path '/etc/hosts/x.md' has a non-directory path component at
+  '/etc/hosts'", and `search_files` finds no temporary Doc for `<doc-id>`: the destination is checked
+  before the export (PR #988 round 1).
+
+**Teardown:** remove `/tmp/qa-959/`; `delete_file(file_id="<doc-id>")`.
+
+**Result (2026-10-11, PR #988 round 1, `8b223c5`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth). The first attempt at call 1 ran without `/tmp/qa-959` existing and wrote a 15-byte *file* named `/tmp/qa-959` (`local_path: "/tmp/qa-959"`); that comes from the shared `write_capped_result_to_disk`, which this PR doesn't touch, so it's ticketed separately and the setup now creates the directory. Rerun with the directory present: call 1 returned `local_path` `/tmp/qa-959/<doc-id>-r3.md`, `bytes_written: 15`, `revisionId`, `modifiedTime`, `images: []`, no `markdown`; the file held `Saved to disk\n\n`, raw Markdown. Calls 2, 3, and 5 raised the expected messages. Call 4 returned `sheet: "Sales"`, `range: "A1:B2"`, `values: [["Product", null], ["Widget", 100]]`. **Extra probe (sent back as a review finding):** `file_id="<doc-id>_WRONG"` raised the same "Revision 3 of … not found. Drive merges a recent revision…" message, misdiagnosing a bad file ID as a merged revision.
+
+**Result (2026-10-11, PR #988 round 2, `15d778d`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth), `/tmp/qa-959` created first. Call 1 returned `local_path` `/tmp/qa-959/<doc-id>-r3.md`, `bytes_written: 15`, `revisionId`, `modifiedTime`, and no `markdown` or `images`; the file held `Saved to disk\n\n`. Calls 2, 3, and 5 raised the expected messages. Call 4 returned `sheet: "Sales"`, `range: "A1:B2"`, `values: [["Product", null], ["Widget", 100]]` (revision 342). Call 6 raised Drive's own `HttpError 404 … "File not found: <doc-id>_WRONG."`, not the merged-revision message. Call 7 raised `local_path '/etc/hosts/x.md' has a non-directory path component at '/etc/hosts'`, and `search_files` found no temporary Doc for `<doc-id>` (only the earlier trashed one noted in TC-D280). Doc trashed, `/tmp/qa-959` removed.
+
+---
+
+### TC-D283: A service account (Content manager) exports a Doc revision; the temporary Doc is trashed (issue #959)
+
+**Background:** A Content manager on a Shared Drive can trash but not permanently delete (#876),
+so the temporary Doc is trashed instead. Use the `mcp-gee-sweet-sa` server, whose default folder
+is the Shared Drive.
+
+**Setup:** On the SA server, `create_doc(title="qa-959-sa", content="<p>SA revision</p>")`, then
+`list_revisions(file_id="<id>")` and take the last `revisionId`.
+
+**Tool calls**
+1. `export_revision(file_id="<id>", revision_id="<last>")` on the SA server
+2. `search_files(query="export_revision temp")` on the SA server
+
+**Checks**
+- Call 1 returns `markdown` containing `SA revision` and no `warning`.
+- Call 2 finds no live file. If the client can show trashed files, the temporary Doc is in the
+  Shared Drive's trash.
+
+**Teardown:** `delete_file(file_id="<id>")` on the SA server.
+
+**Result (2026-10-11, PR #988 round 1, `8b223c5`) ⏭️ SKIP** — Not run: a lane QA session may call only its own `mcp-gee-sweet-kit` server, and the case needs `mcp-gee-sweet-sa`. Pending for a release pass (Aziz may use the `-sa` slot). The trash branch is unit-tested only so far.
+
+---
+
 ### TC-D256: `download_folder`'s `progress_unit='bytes'` feeds byte totals into the structured progress fields, with a file-count fallback when sizes aren't fully known (issue #741) ⚠️ local-filesystem
 
 **Background:** TC-D255 (#352) confirmed the message text carries bytes-transferred-so-far as supplementary context, but the structured `progress`/`total` fields passed to `ctx.report_progress()` stayed file-count-based unconditionally — a client rendering a progress bar from those fields alone (not parsing message text) sees the same one-tick-per-file granularity regardless of individual file size. #741's maintainer decision: keep file-count as the default (`progress_unit='files'`), but add an opt-in `progress_unit='bytes'` so a caller can request byte-based structured fields when every candidate's size is known upfront (same `bytes_total_known` gate TC-D255's message-fallback logic already uses) — falling back to file-count when it isn't, since there's no reliable byte total to report against then. `sync_folder` is explicitly out of scope for this decision (recursive descent never has a full upfront size list). Unit-tested deterministically against a mocked `ctx` in `tests/drive/test_transfer.py::TestDownloadFolder::test_progress_unit_bytes_reports_byte_totals_when_sizes_known`/`test_progress_unit_bytes_falls_back_to_files_when_sizes_unknown`; this live check confirms both branches against a real API call.

{mcp_gee_sweet-0.9.2.dev306 → mcp_gee_sweet-0.9.2.dev313}/docs/qa/tests/sheets_mgmt.md

@@ -1594,12 +1594,12 @@ add_data_validation(sheet="NoSuchSheet") → {"error":"Sheet 'NoSuchSheet' not f
 
 ### TC-S122: add_data_validation — values count/shape mismatch per condition_type returns a local error (unit test)
 
-**Background:** Issue #366 — before this, a mismatched `values` count reached the real Sheets API and got a clean 400 back (e.g. `NUMBER_BETWEEN` with 1 value: `"requires exactly two ConditionValues, but 1 value was supplied"`), which was already safe, just a round-trip later than necessary. Now caught locally via `_condition_value_count_error` before any API call, covering all five value-count shapes: zero-only (`NOT_BLANK`, `BLANK`, `DATE_IS_VALID`, `TEXT_IS_EMAIL`, `TEXT_IS_URL`), zero-or-two (`BOOLEAN`), exactly-one (`NUMBER_GREATER`, `CUSTOM_FORMULA`, `ONE_OF_RANGE`, and the other single-value TEXT_*/DATE_*/NUMBER_* types), exactly-two (`NUMBER_BETWEEN`, `NUMBER_NOT_BETWEEN`, `DATE_BETWEEN`, `DATE_NOT_BETWEEN`), and at-least-one (`ONE_OF_LIST`).
+**Background:** Issue #366 — before this, a mismatched `values` count reached the real Sheets API and got a clean 400 back (e.g. `NUMBER_BETWEEN` with 1 value: `"requires exactly two ConditionValues, but 1 value was supplied"`), which was already safe, just a round-trip later than necessary. Now caught locally via `_condition_value_count_error` before any API call, covering all five value-count shapes: zero-only (`DATE_IS_VALID`, `TEXT_IS_EMAIL`, `TEXT_IS_URL`; `BLANK`/`NOT_BLANK` were removed in PR #986 as unsupported by data validation, see TC-S134), zero-or-two (`BOOLEAN`), exactly-one (`NUMBER_GREATER`, `CUSTOM_FORMULA`, `ONE_OF_RANGE`, and the other single-value TEXT_*/DATE_*/NUMBER_* types), exactly-two (`NUMBER_BETWEEN`, `NUMBER_NOT_BETWEEN`, `DATE_BETWEEN`, `DATE_NOT_BETWEEN`), and at-least-one (`ONE_OF_LIST`).
 
 **Checks (unit test)**
 - `NUMBER_BETWEEN` with 1 value → `{"error": ...}`, before any API call (the issue's own example)
 - `BOOLEAN` accepts 0 or 2 values (a plain checkbox or custom checked/unchecked labels), rejects exactly 1
-- A zero-value type (`NOT_BLANK`) rejects any supplied value
+- A zero-value type (`DATE_IS_VALID`) rejects any supplied value
 - `ONE_OF_LIST` rejects an empty/omitted `values`
 - Exactly-one types (`NUMBER_GREATER`, `CUSTOM_FORMULA`, `ONE_OF_RANGE`) reject 0 or 2 values
 - Exactly-two types (`NUMBER_BETWEEN`, `DATE_BETWEEN`) reject 1 or 3 values
@@ -1689,7 +1689,7 @@ Same as TC-S100 — re-confirms clean-error fix (duplicate coverage in test file
 ### TC-S126: add_data_validation — invalid A1 notation range returns a clean error (issue #747, unit test)
 
 **Checks (unit test)**
-- `add_data_validation(spreadsheet_id, sheet="Sheet1", range="Sheet1!A1", condition_type="NOT_BLANK")` → `{"error": "Invalid A1 notation: Sheet1!A1"}`, not an uncaught `ValueError`
+- `add_data_validation(spreadsheet_id, sheet="Sheet1", range="Sheet1!A1", condition_type="DATE_IS_VALID")` → `{"error": "Invalid A1 notation: Sheet1!A1"}`, not an uncaught `ValueError`
 - No `batchUpdate` API call is made
 - Covered by `test_invalid_range_returns_error_without_api_call` in `TestAddDataValidation` — exercises the shared `_apply_data_validation` helper's `_grid_range` call
 
@@ -2083,3 +2083,94 @@ Separately, `update_cells`'s two `_parse_a1_notation` call sites (mixed-cell bra
 - All TC-S123–TC-S130/TC-W40 error-path unit tests still pass through the shared helpers
 - `uv run python -m pytest tests/sheets/` passes in full
 
+
+---
+
+### TC-S133: GridRange tools reject an out-of-bounds or malformed range before any API call (issue #955)
+
+**Background:** `_parse_a1_notation` had no upper limit on column letters or row numbers, so `ZZZZZZZZ1` or `A99999999999` reached the Sheets API and came back as a raw `HttpError`, and a row string over 4300 digits made `int()` raise without the `Invalid A1 notation` prefix. Separately, `sort_range`, `merge_cells`, `unmerge_cells`, `format_cells`, `update_borders`, `add_data_validation` and `clear_data_validation` resolved the sheet ID, which is an API call on a cold cache, before parsing the range. #955 rejects columns past `ZZZ` and rows past 10,000,000 (Sheets' grid limits) locally, and parses the range before the sheet lookup. The nonexistent spreadsheet ID and sheet name below prove the ordering: a build that looks up the sheet first returns a 404 or `Sheet 'NoSuchSheet' not found`, not the A1 error.
+
+**Fixture:** none. `spreadsheet_id="tc-s133-no-such-spreadsheet"`, `sheet="NoSuchSheet"`.
+
+**Prompt**
+> "Call each of these with `spreadsheet_id=\"tc-s133-no-such-spreadsheet\"` and `sheet=\"NoSuchSheet\"`, and report each raw result:
+> 1. `sort_range(range=\"ZZZZZZZZ1\")`
+> 2. `merge_cells(range=\"A99999999999\")`
+> 3. `unmerge_cells(range=\"A1:AAAA2\")`
+> 4. `format_cells(range=\"A:5\", bold=True)`
+> 5. `update_borders(range=\"A:B5\", top={\"style\": \"SOLID\"})`
+> 6. `add_data_validation(range=\"\\u212a1\", condition_type=\"DATE_IS_VALID\")` (the Kelvin sign U+212A, then `1`)
+> 7. `clear_data_validation(range=\"A10000001\")`
+> 8. `sort_range(range=\"ZZZ10000000\")`"
+
+**Checks**
+- 1 → `{"error": "Invalid A1 notation: column is beyond ZZZ: 'ZZZZZZZZ1'"}`
+- 2 → `{"error": "Invalid A1 notation: row is beyond 10,000,000: 'A99999999999'"}`
+- 3 → `{"error": "Invalid A1 notation: column is beyond ZZZ: 'A1:AAAA2'"}`
+- 4 → `{"error": "Invalid A1 notation: 'A:5'"}`
+- 5 → `{"error": "Invalid A1 notation: 'A:B5'"}`
+- 6 → `{"error": "Invalid A1 notation: 'K1'"}` (the error repr shows the Kelvin sign, not an ASCII `K`)
+- 7 → `{"error": "Invalid A1 notation: row is beyond 10,000,000: 'A10000001'"}`
+- 8 (control: the largest valid cell) → **not** an `Invalid A1 notation` error. It reaches the sheet lookup, so it fails on the fake spreadsheet ID instead (an `HttpError` 404 or a `Sheet ... not found` error)
+- None of calls 1–7 returns a 404 or a `Sheet 'NoSuchSheet' not found` error
+
+**Unit coverage:** `TestGridRangeToolsRejectMalformedRange` (`tests/sheets/test_structure.py`) runs every malformed case against all seven tools and asserts neither `spreadsheets().get()` nor `batchUpdate()` is called. `test_column_beyond_zzz_raises`, `test_row_beyond_limit_raises`, `test_row_over_int_digit_limit_keeps_prefix` and `test_last_column_and_row_accepted` in `TestParseA1Notation` (`tests/sheets/test_helpers.py`) cover the bounds.
+
+**Result (2026-10-11, PR #986 round 1, `6d180ec`) ✅ PASS.** Live via `mcp-gee-sweet-sky` after `/mcp reconnect`:
+- 1 → `{"error":"Invalid A1 notation: column is beyond ZZZ: 'ZZZZZZZZ1'"}`
+- 2 → `{"error":"Invalid A1 notation: row is beyond 10,000,000: 'A99999999999'"}`
+- 3 → `{"error":"Invalid A1 notation: column is beyond ZZZ: 'A1:AAAA2'"}`
+- 4 → `{"error":"Invalid A1 notation: 'A:5'"}`
+- 5 → `{"error":"Invalid A1 notation: 'A:B5'"}`
+- 6 → twice returned the `HttpError 404` from the sheet lookup. The Kelvin sign didn't survive the agent's own tool-call input: the call went out as ASCII `K1`, a valid cell. A fresh interpreter on this PR's code confirms `_parse_a1_notation("K1")` raises `Invalid A1 notation: 'K1'` while ASCII `K1` parses (and `"ff1"` raises). When an agent drives this case, verify step 6 that way, not through the tool call.
+- 7 → `{"error":"Invalid A1 notation: row is beyond 10,000,000: 'A10000001'"}`
+- 8 (control) → `HttpError 404` from the sheet lookup, as expected
+- None of calls 1–5 or 7 returned a 404 or `Sheet ... not found` error.
+
+**#953 checks (folded into #955's pass), same round.**
+- **Bogus-ID preflight:** `format_cells(range="A1")` → `HttpError 404` (control). `A1:`, `1:B`, `ß1`, `A١` → `{"error":"Invalid A1 notation: '<range>'"}` each, no 404.
+- **No write on a real sheet** (temporary `sky-pr986-scratch` tab in `mcp-gee-sweet-qa-fixtures`, seeded A1:B6 with unsorted values, deleted afterward): `sort_range(range="A1:")` and `merge_cells(range="5:")` each returned the A1 error; a grid-data read afterward showed the original order and no merges.
+- **`format_cells` regression** (bold applied, bold cells read back with a fresh interpreter, reset between ranges, 1000×26 grid): `A1` → A1 only; `A1:B2` → rows 1–2, cols A–B (4); `A:A` → rows 1–1000, col A; `1:2` → rows 1–2, cols A–Z; `B2:D` → rows 2–1000, cols B–D; `B2:5` → rows 2–5, cols B–Z; `b2:d3` → rows 2–3, cols B–D (6). All exact.
+- **API contract:** `get_sheet_data(range="A:B5")` is accepted by the Sheets values API, which reads it as `A5:B` (returned rows 5–6 of the seeded A:B data). The GridRange tools' rejection of `A:B5` is therefore stricter than Sheets; filed as #987.
+
+**Result (2026-10-11, PR #986 round 2, `da34415`) ✅ PASS (sent back for the BLANK/NOT_BLANK finding below).** Live via `mcp-gee-sweet-sky` after `/mcp reconnect`, verifying fix commit `da34415` (`_resolve_grid_range`):
+- TC-S133 calls 1–5, 7 → same `Invalid A1 notation` errors as round 1; `add_data_validation(range="A1:")` → `Invalid A1 notation: 'A1:'`; call 8 (control) → `HttpError 404` from the sheet lookup.
+- **sheetId lands on the named tab, not sheet 0:** on a temporary non-first tab (`sky-pr986-r2`, index 3, deleted afterward), `format_cells("B1:C2", bold)`, `merge_cells("E1:F2")`, `add_data_validation("H1:H3", ONE_OF_LIST)` and `update_borders("J1:J2", top SOLID)` each landed exactly there, and the `Sales` tab (sheet 0) showed no bold, merges, borders or validation. `unmerge_cells("E1:F2")` removed the merge; `clear_data_validation("H1:H2")` left only H3.
+- **`sort_range`'s rebuilt sort specs:** `sort_range("B1:C4", [{"column_index": 1, "order": "DESCENDING"}])` sorted by column C (`dimensionIndex` = start column B + 1), giving c/4, a/3, d/2, b/1.
+- Side note (pre-existing, sent back to the Dev in round 2): `add_data_validation` with `condition_type="BLANK"` or `"NOT_BLANK"` reaches the API and fails with `HttpError 400 … ConditionType 'NOT_BLANK' is not supported in data validation`. TC-S133 step 6 still works because the range is rejected before the request is built.
+
+**Result (2026-10-11, PR #986 round 3, `44f9360`) ✅ PASS.** Live via `mcp-gee-sweet-sky` after `/mcp reconnect`:
+- 1–5, 7 → the same `Invalid A1 notation` errors as round 1, word for word.
+- 6 (now `DATE_IS_VALID`): the Kelvin sign again can't be sent through an agent's tool call, so it was checked in a fresh interpreter: `_parse_a1_notation("K1")` raises `Invalid A1 notation: 'K1'`. Live, `add_data_validation(range="A1:", condition_type="DATE_IS_VALID")` → `{"error":"Invalid A1 notation: 'A1:'"}`, so the new condition type passes the enum check and the range is still rejected before the sheet lookup.
+- 8 (control) → `HttpError 404` from the sheet lookup.
+- None of calls 1–5 or 7 returned a 404 or `Sheet ... not found` error.
+
+---
+
+### TC-S134: add_data_validation rejects condition types data validation doesn't support, before any API call (PR #986 QA round 2)
+
+**Background:** `add_data_validation` accepted `BLANK`, `NOT_BLANK`, `TEXT_STARTS_WITH` and `TEXT_ENDS_WITH`, but the Sheets API supports these only for conditional formatting and filters (each one's `BooleanCondition.type` enum description in the discovery doc omits data validation). Every call came back as `HttpError 400 … ConditionType '<type>' is not supported in data validation`. A fresh-interpreter probe of `setDataValidation` confirmed all four are rejected and `ONE_OF_LIST` is accepted. All four are now removed from `_VALID_CONDITION_TYPES` and `_CONDITION_SPECS`, so `_enum_value_error` rejects them locally. The nonexistent spreadsheet ID below shows the rejection is local: a build that still accepts them fails at the sheet lookup with a 404.
+
+**Fixture:** none. `spreadsheet_id="tc-s134-no-such-spreadsheet"`, `sheet="NoSuchSheet"`, `range="A1"`.
+
+**Prompt**
+> "Call `add_data_validation(spreadsheet_id=\"tc-s134-no-such-spreadsheet\", sheet=\"NoSuchSheet\", range=\"A1\", condition_type=<type>)` for each `<type>` below, with `values=[\"ab\"]` for the two TEXT_ types and no `values` for the others, and report each raw result:
+> 1. `BLANK`
+> 2. `NOT_BLANK`
+> 3. `TEXT_STARTS_WITH`
+> 4. `TEXT_ENDS_WITH`
+> 5. `DATE_IS_VALID` (control)"
+
+**Checks**
+- 1–4 → `{"error": "Invalid condition_type '<type>'. Must be one of: …"}`, and the listed valid types don't include any of the four
+- 5 (control: a supported zero-value type) → **not** an `Invalid condition_type` error. It reaches the sheet lookup and fails on the fake spreadsheet ID (an `HttpError` 404 or a `Sheet ... not found` error)
+- None of calls 1–4 returns a 404 or a `Sheet ... not found` error
+- The `add_data_validation` tool description served by the MCP server (its `condition_type` list) no longer names any of the four types
+
+**Unit coverage:** `TestAddDataValidation::test_condition_type_unsupported_by_data_validation_rejected_locally` (`tests/sheets/test_structure.py`) asserts the local error and that neither `spreadsheets().get()` nor `batchUpdate()` is called.
+
+**Result (2026-10-11, PR #986 round 3, `44f9360`) ✅ PASS.** Live via `mcp-gee-sweet-sky` after `/mcp reconnect`:
+- 1 `BLANK`, 2 `NOT_BLANK`, 3 `TEXT_STARTS_WITH` (`values=["ab"]`), 4 `TEXT_ENDS_WITH` (`values=["ab"]`) → `{"error":"Invalid condition_type '<type>'. Must be one of: BOOLEAN, TEXT_CONTAINS, TEXT_NOT_CONTAINS, TEXT_EQ, TEXT_IS_EMAIL, TEXT_IS_URL, DATE_EQ, … ONE_OF_RANGE, ONE_OF_LIST, CUSTOM_FORMULA"}` each. The valid-type list names none of the four.
+- 5 `DATE_IS_VALID` (control) → `HttpError 404` from the sheet lookup on the fake ID.
+- None of calls 1–4 returned a 404.
+- The served `add_data_validation` description (re-fetched after the reconnect) lists `DATE_IS_VALID`, `TEXT_CONTAINS`/`TEXT_NOT_CONTAINS`/`TEXT_EQ`, `TEXT_IS_EMAIL`/`TEXT_IS_URL` and the rest, and none of the four removed types.

{mcp_gee_sweet-0.9.2.dev306 → mcp_gee_sweet-0.9.2.dev313}/docs/roadmap.md

@@ -220,10 +220,13 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [x] SIGTERM with an open streamable-http `GET /mcp` stream truncates it ("ASGI callable returned without completing response"); sibling of #868 — lane A, after #894 (PR #975) ([#917](https://github.com/khuisman/mcp-gee-sweet/issues/917))
 - [x] `get_doc_as_markdown`: a paragraph exported as a fenced code block drops links on its code runs and images (`_render_code_block` keeps only run text). Found reviewing #940 — lane B, after #938 (same file), ahead of #958 (PR #976) ([#951](https://github.com/khuisman/mcp-gee-sweet/issues/951))
 - [x] `get_doc_as_markdown`: plain text ending in `!` right before a linked run exports as `![…](…)`, which renders as an image. Affects every link, not just code; fix belongs in `_escape`'s cross-run handling. Found in PR #968 — lane B, after #951 (same file), ahead of #958 (PR #981) ([#969](https://github.com/khuisman/mcp-gee-sweet/issues/969))
-- [ ] `get_doc_as_markdown(local_path=…)` writes the JSON result envelope, not the markdown: `markdown_export.py` routes through the generic JSON-to-disk helper — lane B, after #938 (same read-side area) ([#958](https://github.com/khuisman/mcp-gee-sweet/issues/958))
-- [ ] `add_chart`: a cell-to-row (`B2:5`) or row-only (`1:5`) range silently charts one column — `_per_column_ranges` defaults `endColumnIndex` to start+1. Found reviewing #931 — lane A, after #917 ([#954](https://github.com/khuisman/mcp-gee-sweet/issues/954))
-- [ ] `_parse_a1_notation` hardening: one compiled grammar, index bounds, validate before the sheet-ID fetch. #931 review follow-ups, no behavior change for valid input — lane A, after #954 (same A1 area) ([#955](https://github.com/khuisman/mcp-gee-sweet/issues/955))
+- [x] `get_doc_as_markdown(local_path=…)` writes the JSON result envelope, not the markdown: `markdown_export.py` routes through the generic JSON-to-disk helper — lane B, after #938 (same read-side area) (PR #982) ([#958](https://github.com/khuisman/mcp-gee-sweet/issues/958))
+- [x] `add_chart`: a cell-to-row (`B2:5`) or row-only (`1:5`) range silently charts one column — `_per_column_ranges` defaults `endColumnIndex` to start+1. Found reviewing #931 — lane A, after #917 (PR #983) ([#954](https://github.com/khuisman/mcp-gee-sweet/issues/954))
+- [x] `_parse_a1_notation` hardening: one compiled grammar, index bounds, validate before the sheet-ID fetch. #931 review follow-ups, no behavior change for valid input — lane A, after #954 (same A1 area); its QA also runs #953's live checks for #931 (folded in) (PR #986) ([#955](https://github.com/khuisman/mcp-gee-sweet/issues/955))
 - [ ] Write side drops image links: `[![alt](src)](url)` (or `<a href><img></a>`) imports through `create_doc`/`create_doc_from_file`/`write_doc_content` without its URL, so it doesn't round-trip with #951's export. Found in PR #976 — lane A, after #955 ([#977](https://github.com/khuisman/mcp-gee-sweet/issues/977))
+- [ ] `_parse_a1_notation` rejects `A:B5`, which the Sheets values API accepts as `A5:B` — decided 2026-10-11: keep rejecting (a destructive GridRange tool acting on "row 5 onward" is worse than an error); document in the docstring that this is deliberately stricter than Sheets. Found in PR #986 — lane A, after #977 ([#987](https://github.com/khuisman/mcp-gee-sweet/issues/987))
+- [ ] Comment quoted text comes back HTML-escaped (`Caf&#233;`) from `add_doc_comment`, `list_doc_comments`, and `get_doc_as_markdown(include_comments=True)`: `comments.py` passes Drive's escaped `quotedFileContent.value` through unchanged. Found reviewing #958 — lane B, after #959 (defect, next pick) ([#984](https://github.com/khuisman/mcp-gee-sweet/issues/984))
+- [ ] `write_capped_result_to_disk` writes `dir/` as a file when the directory doesn't exist: a trailing separator should mean "directory" (create it, append `default_filename`). Shared by every `local_path` writer. Found in PR #988 — lane B, after #984 (defect) ([#990](https://github.com/khuisman/mcp-gee-sweet/issues/990))
 
 **Sheets hardening** _(triaged out of `backlog` 2026-09-11 — see the "Backlog triage" note below)_
 - [x] `update_sheet_properties`/dimension-tool hardening + dedup follow-ups from PR #321's review ([#323](https://github.com/khuisman/mcp-gee-sweet/issues/323)) (PR #734)
@@ -247,12 +250,12 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [x] `content.py`: duplicated image upload/share/revoke logic across `create_doc` and `insert_local_images`, plus an avoidable extra Drive round trip ([#511](https://github.com/khuisman/mcp-gee-sweet/issues/511)) (PR #842)
 - [x] `docs/images.py` oversized-image handling: duplicated logic + unneeded full pixel decode (#400 follow-up) ([#560](https://github.com/khuisman/mcp-gee-sweet/issues/560)) (PR #801)
 - [ ] **Bundle:** Docs read side (`doc_to_ast`/`ast_to_markdown`), one PR closing [#596](https://github.com/khuisman/mcp-gee-sweet/issues/596), [#600](https://github.com/khuisman/mcp-gee-sweet/issues/600), [#732](https://github.com/khuisman/mcp-gee-sweet/issues/732) — lane B ([#893](https://github.com/khuisman/mcp-gee-sweet/issues/893))
-- [ ] Docs image-sharing failure paths: unrevocable `anyone:reader` grant + missing folder-cache invalidation in `_replace_doc_content` ([#666](https://github.com/khuisman/mcp-gee-sweet/issues/666))
 - [ ] `write_doc_content`/`update_doc_from_file` leave the doc empty when the replacement fails after the clear — decided 2026-10-04: record the pre-clear revision ID and name it in the error so the caller can recover via `export_revision` ([#878](https://github.com/khuisman/mcp-gee-sweet/issues/878))
 - [ ] `update_doc_from_file`: opt-in incremental (`mode="patch"`) update that diffs block by block and rewrites only changed blocks, so comment anchors and revision history survive — lane A, after #894 (same write-path files) ([#957](https://github.com/khuisman/mcp-gee-sweet/issues/957))
 - [ ] `export_revision`: support Google Docs revisions (returned as markdown), and fix `list_revisions`' docstring claim that native-file revisions are pruned after 30 days. Also what #878's recovery path points callers at — lane B, after #958 ([#959](https://github.com/khuisman/mcp-gee-sweet/issues/959))
+- [ ] `export_revision`'s temporary Doc exposes an old revision's content to the default folder's audience (a whole Shared Drive) — decided 2026-10-11: under OAuth create it in My Drive root; a service account keeps the default folder, and that remaining exposure goes in `docs/known-limitations.md`. Found in PR #988 — lane B, after #990 ([#989](https://github.com/khuisman/mcp-gee-sweet/issues/989))
 - [x] `insert_local_images`: temporary `anyone:reader` image shares aren't revoked when the call is cancelled — apply PR #877's shielded-cleanup pattern — lane B ([#883](https://github.com/khuisman/mcp-gee-sweet/issues/883)) (PR #903)
-- [ ] **Bundle:** Docs image-share cancellation follow-ups (from PR #903), one PR closing [#904](https://github.com/khuisman/mcp-gee-sweet/issues/904), [#907](https://github.com/khuisman/mcp-gee-sweet/issues/907), [#908](https://github.com/khuisman/mcp-gee-sweet/issues/908) ([#909](https://github.com/khuisman/mcp-gee-sweet/issues/909))
+- [ ] **Bundle:** Docs image-share cancellation follow-ups (from PR #903), one PR closing [#904](https://github.com/khuisman/mcp-gee-sweet/issues/904), [#907](https://github.com/khuisman/mcp-gee-sweet/issues/907), [#908](https://github.com/khuisman/mcp-gee-sweet/issues/908), [#666](https://github.com/khuisman/mcp-gee-sweet/issues/666) — lane A ([#909](https://github.com/khuisman/mcp-gee-sweet/issues/909))
 - [x] `_apply_doc_content`: temporary `anyone:reader` image shares aren't revoked when the doc edit raises — revoke pass should run in a `finally`. Same share/revoke surface as #666 and #511 ([#789](https://github.com/khuisman/mcp-gee-sweet/issues/789)) (PR #877)
 - [ ] Docstrings: `create_paragraph_bullets` carries internal API-quirk mechanics plus residual bare issue refs in `style.py` tool docstrings ([#683](https://github.com/khuisman/mcp-gee-sweet/issues/683))
 - [ ] `style_doc_range` has no `font_family` parameter — can't apply monospace to an existing range ([#720](https://github.com/khuisman/mcp-gee-sweet/issues/720))
@@ -284,15 +287,13 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [ ] Share one HttpError reason-check helper across the `storageQuotaExceeded` sites. Lane A, after #930; community PR #921 closed unmerged 2026-10-10 ([#916](https://github.com/khuisman/mcp-gee-sweet/issues/916))
 
 **Calendar hardening** _(triaged out of `backlog` 2026-09-11)_
-- [ ] `_get_cached_calendar_list` ignores `nextPageToken` (calendarList truncated past 100). Lane B, after #892; community PR #919 closed unmerged 2026-10-10 ([#915](https://github.com/khuisman/mcp-gee-sweet/issues/915))
-- [ ] `list_all_events`: fan-out semaphore permit released on cancel while the HTTP call is still in flight. Lane B, after #915 (same `calendar.py`); community PR #920 closed unmerged 2026-10-10 ([#918](https://github.com/khuisman/mcp-gee-sweet/issues/918))
+- [ ] **Bundle:** Calendar follow-ups from PR #912, one PR closing [#915](https://github.com/khuisman/mcp-gee-sweet/issues/915), [#918](https://github.com/khuisman/mcp-gee-sweet/issues/918) — lane B, after #892 ([#985](https://github.com/khuisman/mcp-gee-sweet/issues/985))
 
 **Testing** _(triaged out of `backlog` 2026-09-11)_
 - [x] **Bundle:** test-suite tightening, one PR closing [#392](https://github.com/khuisman/mcp-gee-sweet/issues/392), [#526](https://github.com/khuisman/mcp-gee-sweet/issues/526), [#551](https://github.com/khuisman/mcp-gee-sweet/issues/551), [#561](https://github.com/khuisman/mcp-gee-sweet/issues/561), [#574](https://github.com/khuisman/mcp-gee-sweet/issues/574) — lane B (PR #924) ([#891](https://github.com/khuisman/mcp-gee-sweet/issues/891))
 - [ ] `qa`: `search_files` has no unit test coverage for the error-dict path ([#573](https://github.com/khuisman/mcp-gee-sweet/issues/573))
 - [x] Live verification for PR #922 (reject unbounded A1 ranges); coverage in PR #929 (PR #929) ([#927](https://github.com/khuisman/mcp-gee-sweet/issues/927))
 - [ ] Live verification for community PR #940 (literal fences in code-block exports) ([#952](https://github.com/khuisman/mcp-gee-sweet/issues/952))
-- [ ] Live verification for community PR #931 (reject missing and incompatible A1 bounds) ([#953](https://github.com/khuisman/mcp-gee-sweet/issues/953))
 
 **Infrastructure**
 - [ ] Interaction-log middleware for tool calls — structured, append-only JSONL log per call (inputs, duration, cache hit, error), opt-in ID redaction, swappable backend ([#646](https://github.com/khuisman/mcp-gee-sweet/issues/646))

{mcp_gee_sweet-0.9.2.dev306 → mcp_gee_sweet-0.9.2.dev313}/docs/tools.md

@@ -94,7 +94,7 @@
 |---|---|---|
 | `export_file` | Export or download a file from Google Drive. | `file_id`, `export_format` |
 | `list_revisions` | List available revisions for a Google Drive file (Sheets, Docs, or any file). | `file_id` |
-| `export_revision` | Export a historical revision of a Google Sheets file and return its cell data. | `file_id`, `revision_id`, `range?`, `sheet?` |
+| `export_revision` | Export a historical revision of a Google Sheets file (cell data) or a Google Doc (Markdown). Use list_revisions to find the revision_id. | `file_id`, `revision_id`, `range?`, `sheet?`, `local_path?` |
 | `upload_file` | Upload a text file to Google Drive, optionally converting it to a Google Doc. | `name`, `content`, `source_format?`, `folder_id?`, `convert_to_doc?` |
 | `upload_local_file` | Upload a file from the local filesystem to a Google Drive folder. Handles binary and text files (images, PDFs, DOCX, XLSX, scripts, etc.). | `local_path`, `parent_folder_id`, `name?`, `skip_if_exists?`, `convert?` |
 | `upload_local_folder` | Upload all files in a local directory (non-recursive) to a Google Drive folder. | `local_path`, `parent_folder_id`, `skip_if_exists?`, `skip_system_files?`, `convert?` |