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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-gee-sweet
-Version: 0.9.2.dev313
+Version: 0.9.2.dev319
 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 → mcp_gee_sweet-0.9.2.dev319}/docs/design/doc-to-markdown.md

@@ -128,8 +128,9 @@ Three gaps were kept **as documented limitations, not implementation shortcuts**
 - **Linked images** (#951): Docs puts an image's link on its `inlineObjectElement`'s own
   `textStyle.link`, the same as a text run (confirmed live). `doc_to_ast` reads it into
   `Image.link_url`, and every image renders through `_render_image` as `[![alt](src)](url)`, in
-  ordinary text, a code paragraph, and a table cell alike. The write side doesn't set
-  `Image.link_url` yet (#977).
+  ordinary text, a code paragraph, and a table cell alike. The write side sets it too (#977;
+  see [image-conversion.md](image-conversion.md#linked-images-977)), so a linked image
+  round-trips.
 - **Same-document links** (PR #976 QA round 1): Docs reports a link to a heading or bookmark by
   ID with no `url` (confirmed live for a heading: `{"headingId": "h.x"}`, on a text run and an
   image alike). `doc_to_ast._link_url`, shared by both, rebuilds it as

{mcp_gee_sweet-0.9.2.dev313 → mcp_gee_sweet-0.9.2.dev319}/docs/design/image-conversion.md

@@ -103,6 +103,39 @@ need K retries. Resending the whole document each time would be K+1 full-size ro
 Confirmed live that the split produces a document structurally identical to the old
 whole-list retry (text, bullets, table, and the surviving image all in place).
 
+## Linked images (#977)
+
+An `<img>` inside `<a href>` (markdown `[![alt](src)](url)`) keeps its link: `html_parser.py`
+copies the open `<a>`'s href onto `Image.link_url`. That includes raw HTML with no enclosing
+block: a top-level `<img>` gets an implicit paragraph even when it's wrapped in inline tags (unlike
+bare text or `<hr>` in that position), and reads its link from `_bare_link_url`, a stack separate
+from `_link_url` so text handling and an unclosed top-level `<a>` are unaffected. Each open `<a>`
+records which of the two stacks it pushed onto, or that it pushed nothing (`_anchor_pushes`), and
+its `</a>` pops only that: an href-less `<a name>` nested in a linked anchor used to pop the outer
+link (#994, PR #992 QA round 2). Docs stores an image's link on its
+`inlineObjectElement`'s own `textStyle.link`, so `emitter.py` follows the image's
+`insertInlineImage` with an `updateTextStyle` over its one-character range
+`[position, position + 1)`. The link has to come right after its own insert, inside the
+descending-position tail: at that point nothing before `position` has shifted yet. An inserted
+image never inherits a neighboring run's link (confirmed live, both directions), so an unlinked
+image gets no clearing request.
+
+Inserts that share a position, such as adjacent images with nothing between them, each land in
+front of whatever is already there, so the later one in the document has to be inserted first.
+The descending pass sorts on `(position, node order, item order)`, all descending; sorting by
+position alone kept source order within a tie and wrote adjacent images reversed (PR #992 QA
+round 1). A table and the image right after it share a position the same way, and still come out
+table first.
+
+The retry treats the pair as one unit. `ast_to_requests(image_links=...)` records each
+`id(insert request) -> link request` as it builds them, and `_apply_doc_content` uses that record
+rather than matching request shapes. `_drop_failed_image` pops the link request with its failed
+insert, since a stranded link would land on whatever character now sits at that position.
+`_positional_insert_tail_start` counts a recorded link request as part of the tail, so the K≥2
+split still applies. A `#slug` image link goes
+through the heading-anchor pass like a text link: `_walk_headings_and_anchor_runs` reads the
+`inlineObjectElement`'s link too, so it's resolved or stripped.
+
 ## Known, deliberate gap: table-cell images
 
 `html_parser.py`'s img-handling only fires when a block context is open at the body level

{mcp_gee_sweet-0.9.2.dev313 → mcp_gee_sweet-0.9.2.dev319}/docs/design/markdown-support.md

@@ -173,6 +173,7 @@ another registered tool), passing `content_format` through to `_to_doc_requests`
 | `~~strikethrough~~` | `<del>` | `Run(strikethrough=True)` | strikethrough |
 | `[text](url)` | `<a href=...>` | `Run(link_url=...)` | hyperlink |
 | bare `https://url` | `<a href=...>` (autolink extension) | `Run(link_url=...)` | hyperlink — disable via `autolink_urls=False` |
+| `[![alt](src)](url)` | `<a href=...><img ...></a>` | `Image(link_url=...)` | linked inline image (#977) |
 | `- item` | `<ul><li>` | `BulletItem(ordered=False)` | disc bullet list |
 | `1. item` | `<ol><li>` | `BulletItem(ordered=True)` | numbered list |
 | `- [x] item` | `<input type="checkbox" checked>` | `BulletItem(checked=True)` | bullet with a `☑`/`☐` glyph prefix |

{mcp_gee_sweet-0.9.2.dev313 → mcp_gee_sweet-0.9.2.dev319}/docs/qa/tests/docs_content.md

@@ -3716,6 +3716,64 @@ Not covered live: a soft break (Shift+Enter) inside an inline code run in a para
 
 **Result (2026-10-10) ✅ PASS — Kit, PR #981 round 2 (`b2bfafe`).** Ran on a scratch doc (created with `create_doc` from the step 1 HTML, trashed afterwards) instead of `{DOC_ID}`. Step 2 used one `find_in_doc(regex=True)` call for all three queries: matches at 4–11, 15–20 and 26–39. After step 3, `get_doc_structure` showed each of the first three paragraphs as two runs split at the `<`/`&` (`a <` | `b> text`, `AT&` | `amp;T`, `see <` | `https://x.io>`). `get_doc_as_markdown` returned `a \<b> text`, `AT\&amp;T`, `see \<https://x.io>`, and `a < b and AT&T` unchanged. markdown-it-py `commonmark` rendered `a &lt;b&gt; text`, `AT&amp;amp;T`, `see &lt;https://x.io&gt;`, and `a &lt; b and AT&amp;T`, with no `<b>` and no `<a>`. Round 1 got `a <b> text` and `AT&amp;T` unescaped from the same kind of split, on pre-fix code (`307e47c`).
 
+
+### TC-DOC216: A linked image written as Markdown or HTML keeps its link and round-trips (#977) ⚠️ requires-oauth
+**Background:** the write side built a linked image with no link, so `[![alt](src)](url)` and `<a href><img></a>` imported as a plain image and didn't round-trip with TC-DOC209's export. The image now gets its link through an `updateTextStyle` over its one-character range, right after its insert. That request has to stay paired with the image when an unreachable image is dropped and retried, and a `#slug` image link goes through the heading-anchor pass.
+
+**Setup:** none. Each step uses a scratch doc.
+
+**Prompt**
+**Playwright: required** (each linked image is clickable to its URL in the rendered doc; the unlinked one isn't)
+1. `create_doc(title="TC-DOC216 md", folder_id={FOLDER_ID}, content_format='markdown', content=...)` with:
+   ```markdown
+   # Overview
+
+   Before [![Logo](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)](https://example.com/one) and [linked text](https://example.com/t)![Plain](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)
+
+   Jump: [![A](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)](#overview) and [![B](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)](#missing)
+
+   | a | b |
+   |---|---|
+   | 1 | 2 |
+
+   [![C](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)](https://example.com/after-table)
+   ```
+2. `get_doc_as_markdown(doc_id=<step 1 docId>)`
+3. `create_doc(title="TC-DOC216 retry", folder_id={FOLDER_ID}, content_format='html', content=...)` with:
+   ```html
+   <p><a href="https://example.com/b1"><img src="https://example.invalid/nope.png?1"></a></p><p>x <a href="https://example.com/good"><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"></a> y</p><p><a href="https://example.com/b2"><img src="https://example.invalid/nope.png?2"></a></p>
+   ```
+4. `get_doc_as_markdown(doc_id=<step 3 docId>)`
+5. `create_doc(title="TC-DOC216 adjacent", folder_id={FOLDER_ID}, content_format='html', content=...)` with (raw HTML, the first image wrapped in a top-level `<a>` with no `<p>`):
+   ```html
+   <a href="https://example.com/top"><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png" width="100"></a><p>x <a href="https://example.com/first"><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png" width="40"></a><a href="https://example.com/second"><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png" width="80"></a><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png" width="120"> y</p>
+   ```
+6. `get_doc_as_markdown(doc_id=<step 5 docId>)`
+7. `create_doc(title="TC-DOC216 nested anchor", folder_id={FOLDER_ID}, content_format='html', content=...)` with an href-less `<a name>` nested inside each linked anchor (#994):
+   ```html
+   <a href="https://example.com/bare"><a name="n1"></a><img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"></a><p><a href="https://example.com/block"><a name="n2"></a>tail<img src="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"></a> after</p>
+   ```
+8. `get_doc_as_markdown(doc_id=<step 7 docId>)`
+
+**Checks**
+- Step 2: `[![](<contentUri>)](https://example.com/one)`
+- Step 2: `[linked text](https://example.com/t)` is followed by an unlinked `![](<contentUri>)`, not one inside the link
+- Step 2: image `A` links to `https://docs.google.com/document/d/<docId>/edit?tab=t.0#heading=<headingId>`, the `Overview` heading. Image `B` is unlinked, its `#missing` link stripped
+- Step 2: the image after the table is `[![](<contentUri>)](https://example.com/after-table)`
+- Step 3: `images` reports an `error` for both `example.invalid` sources and none for the Google logo
+- Step 4: the only image is `[![](<contentUri>)](https://example.com/good)`, between `x` and `y`. No text character carries `b1`'s or `b2`'s link
+- Step 6: the first paragraph is the top-level image alone, as `[![](<contentUri>)](https://example.com/top)`
+- Step 6: the second paragraph is `x `, `[![](<contentUri>)](https://example.com/first)`, `[![](<contentUri>)](https://example.com/second)`, an unlinked `![](<contentUri>)`, then ` y`, in that order. Playwright: in the step 5 doc's editor the three inline images get wider left to right (40, 80, 120px source widths), which confirms the order independently of the links
+- Step 8: the first paragraph is `[![](<contentUri>)](https://example.com/bare)`. The second is `[tail](https://example.com/block)`, then `[![](<contentUri>)](https://example.com/block)`, then an unlinked ` after`: the nested `<a name>` doesn't end the outer link
+
+**Cleanup:** `delete_file` all four scratch docs
+
+**Result (2026-10-11) ✅ PASS — Sky, PR #992 round 1 (`6aa4dac`).** Step 2: `Logo` came back as `[![](<contentUri>)](https://example.com/one)`. `[linked text](https://example.com/t)` was followed by an unlinked `![](<contentUri>)`. `A` linked to `.../edit?tab=t.0#heading=h.…` (the `Overview` heading), and `B` was unlinked. The image after the table kept `https://example.com/after-table`. Step 3: `images` reported an `error` for both `example.invalid` sources and none for the logo. Step 4: the only image was `[![](<contentUri>)](https://example.com/good)` between `x` and `y`, and no text carried `b1`'s or `b2`'s link. Playwright, clicking each image in the step 1 doc's editor: `Logo` and the after-table image each showed a link chip for `https://example.com/…`, and `A`'s chip showed `Overview`. The unlinked image and `B` showed no link chip. The `/mobilebasic` HTML view isn't a substitute: it renders the text link but never wraps an image in `<a>`. A separate probe, `[![first](…)](https://example.com/first)[![second](…)](https://example.com/second)`, exported as `second` then `first`: adjacent images are written in reverse order. Each kept its own link.
+
+**Result (2026-10-11) ✅ PASS — Sky, PR #992 round 2 (`3a506f4`).** Re-ran step 3 (the retry, now pairing each image with its link by identity) and the new step 5. Step 4: the only image was `[![](<contentUri>)](https://example.com/good)` between `x` and `y`, and no text carried `b1`'s or `b2`'s link. Step 6: the first paragraph was the top-level image alone, as `[![](<contentUri>)](https://example.com/top)`. The second paragraph was `x `, `…(https://example.com/first)`, `…(https://example.com/second)`, an unlinked image, then ` y`. Playwright: in the step 5 doc's editor the three inline images got wider left to right, and the top image's link chip showed `https://example.com/…`. Steps 1–2 weren't re-run: the fix commit doesn't change that path beyond the sort, which step 5 covers.
+
+**Result (2026-10-11) ✅ PASS — Sky, PR #992 round 3 (`9271dfe`).** Ran the new step 7. Step 8: the first paragraph was `[![](<contentUri>)](https://example.com/bare)`, and the second was `[tail](https://example.com/block)`, then `[![](<contentUri>)](https://example.com/block)`, then an unlinked ` after`. The fix commit only touches `html_parser.py`'s anchor handling, so steps 1–6 weren't re-run.
+
 ---
 
 ## Orphan fileId on inline-image sharing failure (#649)
@@ -4167,3 +4225,56 @@ Both tools read the local file through the shared `_read_doc_source_file` helper
 **Cleanup:** `rm -rf /tmp/tc-doc213`
 
 **Result (2026-10-10) ✅ PASS — Sky, PR #961 round 2 (`849f0bb`).** Ran with the fixtures under this job's scratch dir instead of `/tmp/tc-doc213`. Steps 1 and 3 returned `{"error": "Not a regular file: <path>/dir.md"}`; steps 2 and 4 returned `{"error": "File is not valid UTF-8: <path>/latin1.html (invalid continuation byte at byte 6)"}`. No call surfaced as `Error executing tool`. `list_files({FOLDER_ID})` showed only the three standing fixtures. After `refresh_cache`, `get_doc_content({DOC_ID})` matched the Setup snapshot. Round 1 reproduced both raises on the pre-fix code (`075ce99`).
+
+## Comment quoted text is plain text, not HTML-escaped (#984)
+
+Drive returns a comment's `quotedFileContent.value` HTML-escaped (`Caf&#233;`, `&amp;`, `&lt;`, `&quot;`, `&#39;`), and a literal `&amp;` in the anchor as `&amp;amp;`. `add_doc_comment`, `list_doc_comments`, and `get_doc_as_markdown(include_comments=True)` unescape it once. The Markdown export then escapes the quote only as Markdown needs, with `"> "` on every line, and escapes comment authors, text, and replies the same way.
+
+### TC-DOC215: Non-ASCII, `&`/`<`/`"`, literal-entity, and multi-line anchors round-trip as plain text ⚠️ destructive ⚠️ requires-oauth
+**Setup:** `create_doc(title="QA TC-DOC215", folder_id={FOLDER_ID}, content="<p>Café and Tom &amp; Jerry, a &lt; b, say \"hi\" it's &amp;amp; literal</p><p>line one</p><p>line *two* &lt;x&gt;</p>")`, note the returned `docId` as `{SCRATCH_DOC_ID}`
+
+**Steps**
+1. `add_doc_comment(doc_id={SCRATCH_DOC_ID}, content="QA TC-DOC215 a <b> *x*", quoted_text="Café and Tom & Jerry, a < b, say \"hi\" it's")`
+2. `add_doc_comment(doc_id={SCRATCH_DOC_ID}, content="QA TC-DOC215 b", quoted_text="&amp; literal")`
+3. `add_doc_comment(doc_id={SCRATCH_DOC_ID}, content="QA TC-DOC215 c", quoted_text="line one\nline *two* <x>")`
+4. `list_doc_comments(doc_id={SCRATCH_DOC_ID})`
+5. `get_doc_as_markdown(doc_id={SCRATCH_DOC_ID}, include_comments=True)`
+
+**Checks**
+- Steps 1–3 each return `quoted_text` equal to the `quoted_text` passed in, character for character: `Café`, not `Caf&#233;`; `&`, `<`, `"`, `'` unescaped; step 2 returns `&amp; literal`, not `&amp;amp; literal` or `& literal`
+- Step 4's three comments carry the same `quoted_text` values as steps 1–3
+- Step 5's `## Comments` section contains these quote blocks, each followed by a blank line before the comment text:
+  - `> Café and Tom & Jerry, a < b, say "hi" it's`
+  - `> \&amp; literal`
+  - `> line one\` (ending in a hard-break backslash, since PR #991 round 2) then `> line \*two\* \<x>` on the next line
+- Step 5 renders step 1's comment text as `QA TC-DOC215 a \<b> \*x\*` (plain text, escaped only as Markdown needs), and step 1 itself returns `content` unchanged
+- No `&#233;`, `&quot;`, `&#39;`, or `&lt;` appears anywhere in step 5's comments section
+
+**Cleanup:** `delete_file(file_id={SCRATCH_DOC_ID})`
+
+**Result (2026-10-11) ✅ PASS — Kit, PR #991 round 1 (`9953a83`).** Steps 1–3 echoed each `quoted_text` exactly (`Café and Tom & Jerry, a < b, say "hi" it's`, `&amp; literal`, `line one\nline *two* <x>`); step 4 returned the same three values. Step 5's comments section had `> Café and Tom & Jerry, a < b, say "hi" it's`, `> \&amp; literal`, and `> line one` / `> line \*two\* \<x>`, each followed by a blank line, and comment text `QA TC-DOC215 a \<b> \*x\*`; no `&#233;`/`&quot;`/`&#39;`/`&lt;` in the section. Extra probe: a comment created in the Docs UI (Playwright) on the doc's literal `&amp; literal` text also came back from `list_doc_comments` as `&amp; literal`, so Drive escapes UI-created anchors too and a single unescape is correct for them. The case passes, but the round was sent back for Markdown-escaping gaps in comment text that this case doesn't exercise (see the PR comment).
+
+### TC-DOC217: Multi-line comment text and indented/rule body paragraphs stay plain text in the Markdown export ⚠️ destructive ⚠️ requires-oauth
+Comment text is plain text, so no line of it may render as Markdown structure, and each line keeps its own line (a hard break, not a soft wrap). Body paragraphs that start with spaces or a tab before a marker, or that are a `---` rule line, stay plain paragraphs too (#993). Replies are covered by unit tests only: the one tool that posts a reply, `resolve_doc_comment`, also resolves the comment, and `include_comments` exports only open ones.
+
+**Setup:**
+- `create_doc(title="QA TC-DOC217", folder_id={FOLDER_ID}, content="<p>anchor</p>")`, note the returned `docId` as `{SCRATCH_DOC_ID}`
+- `insert_doc_text(doc_id={SCRATCH_DOC_ID}, insertions=[{"index": 1, "text": " - a\n  # h\n---\n\ttab indent\n## Notes\n"}])`
+
+**Steps**
+1. `add_doc_comment(doc_id={SCRATCH_DOC_ID}, quoted_text="anchor", content="Summary\n---\nPoints:\n - a\n   - b\na | b\n-|-\nc | d\n## Notes\n\n    indented *x*")`
+1a. `add_doc_comment(doc_id={SCRATCH_DOC_ID}, quoted_text="Summary\n===  ", content="QA TC-DOC217 setext")` (the trailing spaces after `===` are part of the anchor; Drive keeps them in `quoted_text`)
+2. `get_doc_as_markdown(doc_id={SCRATCH_DOC_ID}, include_comments=True, local_path="/tmp/tc-doc217.md")`
+3. `uv run python -c "from markdown_it import MarkdownIt; print(MarkdownIt('commonmark').enable('table').render(open('/tmp/tc-doc217.md').read()))"`
+
+**Checks**
+- Step 3's HTML has no `<ul>`, `<ol>`, `<h1>`, `<table>`, or `<pre>`. It has exactly one `<h2>` (`Comments`) and one `<hr />`: the comments section's own heading and separator
+- The body renders `<p>- a</p>`, `<p># h</p>`, `<p>---</p>`, `<p>tab indent</p>`, and `<p>## Notes</p>`
+- Step 1's comment renders `Summary`, `---`, `Points:`, `- a`, `- b`, `a | b`, `-|-`, `c | d`, and `## Notes` as separate lines joined by `<br />` in one paragraph, with no literal `\` at any line end, then `<p>indented *x*</p>` as its own paragraph
+- Step 1a's quote renders as `<blockquote>` holding `<p>Summary<br />` and `===</p>`, with no `<h1>`
+
+**Cleanup:** `delete_file(file_id={SCRATCH_DOC_ID})`, `rm /tmp/tc-doc217.md`
+
+**Result (2026-10-11) ✅ PASS (case as written), ❌ sent back on probes — Kit, PR #991 round 2 (`de8143e`).** Ran with the export under this job's scratch dir instead of `/tmp`. Every check passed for the case's own content: body `<p>- a</p>`, `<p># h</p>`, `<p>---</p>`, `<p>tab indent</p>`; the comment's eight lines joined by `<br />` in one paragraph, then `<p>indented *x*</p>`; no `<ul>`/`<ol>`/`<table>`/`<pre>`. Extra probes on the same doc failed: (1) a body paragraph `## Notes` and a comment line `## Notes` each rendered as `<h2>`, and the comment line before it kept a literal `\`, because `_LEADING_SIMPLE_MARKER` matches only a single `#`; (2) `add_doc_comment(quoted_text="Summary\n===  ")` exported `> Summary\` / `> ===  `, which renders as `<h1>Summary\</h1>` inside the blockquote, because `_LEADING_RULE_LINE` doesn't allow trailing whitespace after `=`. Drive trims trailing whitespace from the end of comment `content` (not from `quoted_text`), and a mid-content `===  ` line is safe because the hard break before it blocks the setext.
+
+**Result (2026-10-11) ✅ PASS — Kit, PR #991 round 3 (`95ba882`).** Ran with the export under this job's scratch dir instead of `/tmp`. Step 3's HTML had no `<ul>`/`<ol>`/`<h1>`/`<table>`/`<pre>`, exactly one `<h2>` (`Comments`) and one `<hr />`. Body: `<p>- a</p>`, `<p># h</p>`, `<p>---</p>`, `<p>tab indent</p>`, `<p>## Notes</p>`. Step 1's comment rendered its nine lines through `## Notes` joined by `<br />` with no literal `\`, then `<p>indented *x*</p>`. Step 1a's `quoted_text` came back as `Summary\n===  ` (trailing spaces kept) and rendered as `<blockquote><p>Summary<br />===</p></blockquote>`, no `<h1>`.

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

@@ -224,8 +224,7 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [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))
+- [x] 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) (PR #991) ([#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)_
@@ -252,7 +251,7 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [ ] **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))
 - [ ] `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))
+- [x] `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 (PR #988) ([#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), [#666](https://github.com/khuisman/mcp-gee-sweet/issues/666) — lane A ([#909](https://github.com/khuisman/mcp-gee-sweet/issues/909))
@@ -380,6 +379,8 @@ Follows the design in [`docs/decisions/decision-comments-first-class.md`](decisi
 
 - [ ] `sync_folder(export_format=...)`: converted Sheets/Slides probably have #814's `modifiedTime` lag and restamp race too. Suspected, not yet observed ([#818](https://github.com/khuisman/mcp-gee-sweet/issues/818))
 - [ ] Add a tool to set (and read back) Google Docs table column widths — `tableColumnProperties` isn't reachable through any tool today ([#809](https://github.com/khuisman/mcp-gee-sweet/issues/809))
+- [ ] `_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; moved from v0.9.2 2026-10-11 (docstring only, current behavior is the safe one) ([#987](https://github.com/khuisman/mcp-gee-sweet/issues/987))
+- [ ] `html_parser`: the `</a>` of an href-less anchor nested in a linked one pops the outer link, so text or an image after it is written unlinked. Found in PR #992's QA, which sent back the same bug in its new `_bare_link_url` stack; may close with PR #992 — lane A; moved from v0.9.2 2026-10-11 (pre-existing, invalid nested HTML only) ([#994](https://github.com/khuisman/mcp-gee-sweet/issues/994))
 
 **Code structure & typing (Joy)** _(slotted into v0.9.2 (now v0.9.3) 2026-09-09 so Joy's architecture initiative carries release deadlines instead of staying open-ended)_
 

{mcp_gee_sweet-0.9.2.dev313 → mcp_gee_sweet-0.9.2.dev319}/src/mcp_gee_sweet/tools/docs/ast.py

@@ -49,8 +49,8 @@ class Image:
     alt: str | None = None
     width: float | None = None  # pt
     height: float | None = None  # pt
-    # Read side only (doc_to_ast.py): the image element's own textStyle.link.
-    # The write side doesn't set it yet.
+    # The image element's own textStyle.link: read by doc_to_ast.py, and written
+    # by emitter.py as an updateTextStyle over the image's one-character range (#977).
     link_url: str | None = None
 
 

{mcp_gee_sweet-0.9.2.dev313 → mcp_gee_sweet-0.9.2.dev319}/src/mcp_gee_sweet/tools/docs/ast_to_markdown.py

@@ -57,8 +57,12 @@ _BACKTICK_RUN = re.compile(r"`+")
 # Paragraph rendering only: Heading/NamedBlock/BulletItem already have their
 # own legitimate prefix on the same line, so content following it is never
 # re-parsed as a new block starting mid-line.
-_LEADING_SIMPLE_MARKER = re.compile(r"^([#>]|[-*+])(?=[ \t]|$)")
+_LEADING_SIMPLE_MARKER = re.compile(r"^(#{1,6}|[>*+-])(?=[ \t]|$)")
 _LEADING_ORDERED_MARKER = re.compile(r"^(\d{1,9})([.)])(?=[ \t]|$)")
+# A line of only "-" (spaces allowed) is a thematic break, or a setext
+# underline under a preceding line, and so is a line of only "=". "*" and "_"
+# rules can't occur: _escape has already escaped both (#993).
+_LEADING_RULE_LINE = re.compile(r"^(?:=+[ \t]*|-[- \t]*)$")
 
 _NESTED_TABLE_PLACEHOLDER = (
     "*(nested table omitted — Markdown tables can't contain a table; "
@@ -162,14 +166,24 @@ def _render_block(node: Heading | Paragraph | BulletItem | NamedBlock) -> str:
 
     depth = getattr(node, "blockquote_depth", 0)
     if depth:
-        prefix = "> " * depth
-        body = "\n".join(
-            f"{prefix}{line}" if line else prefix.rstrip() for line in body.split("\n")
-        )
+        body = _blockquote(body, depth)
     return body
 
 
+def _blockquote(body: str, depth: int) -> str:
+    prefix = "> " * depth
+    return "\n".join(f"{prefix}{line}" if line else prefix.rstrip() for line in body.split("\n"))
+
+
 def _escape_leading_block_marker(text: str) -> str:
+    """Make one line that starts a block read as paragraph text. Leading
+    spaces and tabs are dropped first: CommonMark strips a paragraph's
+    leading whitespace anyway, so the rendered text is unchanged, while
+    keeping them lets " - a" parse as a list and four spaces or a tab as an
+    indented code block (#993)."""
+    text = text.lstrip(" \t")
+    if _LEADING_RULE_LINE.match(text):
+        return "\\" + text
     m = _LEADING_SIMPLE_MARKER.match(text)
     if m:
         return "\\" + text
@@ -463,12 +477,51 @@ def _table_safe(text: str) -> str:
 
 
 def _render_comment(comment: dict) -> str:
-    author = (comment.get("author") or {}).get("display_name") or "Unknown"
+    """Comment authors, anchors, and text are all plain text (Drive's
+    `content`, not `htmlContent`), so none of it may render as Markdown
+    structure (#984). See _comment_text for how each line is kept literal.
+
+    The quote is a blockquote ended by a blank line, since the comment text
+    after it would otherwise be a lazy continuation of the quote. Without a
+    quote, the author line ends in a hard break so the text starts on its own
+    line. A reply's continuation lines are indented to the list item's
+    content column, so they stay in the item instead of ending the list."""
+    author = _comment_inline((comment.get("author") or {}).get("display_name") or "Unknown")
+    content = _comment_text(comment.get("content") or "")
     lines = [f"**{author}**"]
     if comment.get("quoted_text"):
-        lines.append(f"> {comment['quoted_text']}")
-    lines.append(comment.get("content") or "")
+        lines.append(_blockquote(_comment_text(comment["quoted_text"]), 1) + "\n")
+    elif content.split("\n", 1)[0]:
+        lines[0] += "\\"
+    lines.append(content)
     for reply in comment.get("replies", []):
-        r_author = (reply.get("author") or {}).get("display_name") or "Unknown"
-        lines.append(f"  - **{r_author}**: {reply.get('content') or ''}")
+        r_author = _comment_inline((reply.get("author") or {}).get("display_name") or "Unknown")
+        first, *rest = _comment_text(reply.get("content") or "", starts_block=False).split("\n")
+        lines.append(
+            "\n".join(
+                [f"  - **{r_author}**: {first}"] + [f"    {line}" if line else "" for line in rest]
+            )
+        )
     return "\n".join(lines) + "\n"
+
+
+def _comment_inline(text: str) -> str:
+    # "|" too: consecutive comment lines like "a | b" and "-|-" form a table.
+    return _escape(text).replace("|", "\\|")
+
+
+def _comment_text(text: str, starts_block: bool = True) -> str:
+    """Multi-line plain text as Markdown that renders as the same lines. Each
+    line is escaped inline, and block markers are escaped on every line that
+    can start a block: all of them, except a first line that follows other
+    text on its own line (a reply's, after "**author**: "). Every line
+    followed by a non-empty one ends in a hard break ("\\"); a soft break
+    would join them into one line. An empty line stays a paragraph break."""
+    lines = [_comment_inline(line) for line in text.split("\n")]
+    for i in range(len(lines)):
+        if i or starts_block:
+            lines[i] = _escape_leading_block_marker(lines[i])
+    for i in range(len(lines) - 1):
+        if lines[i] and lines[i + 1]:
+            lines[i] += "\\"
+    return "\n".join(lines)

{mcp_gee_sweet-0.9.2.dev313 → mcp_gee_sweet-0.9.2.dev319}/src/mcp_gee_sweet/tools/docs/comments.py

@@ -1,3 +1,4 @@
+import html
 import logging
 from typing import Any
 
@@ -38,8 +39,18 @@ def _map_reply(reply: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+def _quoted_text(resource: dict[str, Any]) -> str | None:
+    """The plain text a comment is anchored to. Drive returns
+    quotedFileContent.value HTML-escaped ("Café", "&") even though
+    it was written as plain text, and escapes a literal "&" in the
+    anchor as "&", so unescaping once restores it exactly (#984)."""
+    quoted = resource.get("quotedFileContent")
+    if not quoted or quoted.get("value") is None:
+        return None
+    return html.unescape(quoted["value"])
+
+
 def _map_comment(comment: dict[str, Any]) -> dict[str, Any]:
-    quoted = comment.get("quotedFileContent")
     return {
         "id": comment.get("id"),
         "content": comment.get("content"),
@@ -48,7 +59,7 @@ def _map_comment(comment: dict[str, Any]) -> dict[str, Any]:
         "modified_time": comment.get("modifiedTime"),
         "resolved": comment.get("resolved", False),
         "deleted": comment.get("deleted", False),
-        "quoted_text": quoted.get("value") if quoted else None,
+        "quoted_text": _quoted_text(comment),
         "replies": [_map_reply(r) for r in comment.get("replies", [])],
     }
 
@@ -155,14 +166,13 @@ def register(tool):
             drive_service,
         )
 
-        quoted = result.get("quotedFileContent")
         logger.debug("Added comment %s to doc %s", result.get("id"), doc_id)
         return {
             "id": result.get("id"),
             "content": result.get("content"),
             "author": _map_author(result.get("author")),
             "created_time": result.get("createdTime"),
-            "quoted_text": quoted.get("value") if quoted else None,
+            "quoted_text": _quoted_text(result),
         }
 
     @tool(annotations=ToolAnnotations(title="Resolve Document Comment", destructiveHint=True))

{mcp_gee_sweet-0.9.2.dev313 → mcp_gee_sweet-0.9.2.dev319}/src/mcp_gee_sweet/tools/docs/content.py

@@ -162,12 +162,20 @@ def _failed_insert_image_message(error: HttpError) -> str:
 _POSITIONAL_INSERT_KEYS = ("insertTable", "insertInlineImage")
 
 
-def _positional_insert_tail_start(requests: list[dict]) -> int:
+def _positional_insert_tail_start(
+    requests: list[dict], image_links: dict[int, dict] | None = None
+) -> int:
     """Index where ast_to_requests's trailing stage-3 pass (the descending-position
     insertTable + insertInlineImage requests — see its docstring) begins: the start
-    of the maximal suffix made up only of those two request kinds."""
+    of the maximal suffix made up only of those two request kinds, plus each linked
+    image's own link request (#977). `image_links` is the id(insert) -> link
+    request map ast_to_requests filled; a link request counts by identity."""
+    link_ids = {id(link) for link in (image_links or {}).values()}
     start = len(requests)
-    while start > 0 and any(key in requests[start - 1] for key in _POSITIONAL_INSERT_KEYS):
+    while start > 0 and (
+        id(requests[start - 1]) in link_ids
+        or any(key in requests[start - 1] for key in _POSITIONAL_INSERT_KEYS)
+    ):
         start -= 1
     return start
 
@@ -553,8 +561,9 @@ async def _apply_doc_content(
     # (#789): revoking after a failed edit is harmless, since a doc that did embed
     # an image holds its own copy and one that didn't never needed the share.
     try:
+        image_links: dict[int, dict] = {}
         content_requests, tables = ast_to_requests(
-            nodes, start_index=1, image_uris=placeholder_uris
+            nodes, start_index=1, image_uris=placeholder_uris, image_links=image_links
         )
 
         # Swap each request's placeholder URI for the real one, recording which
@@ -626,13 +635,21 @@ async def _apply_doc_content(
 
             def _drop_failed_image(requests: list[dict], e: HttpError) -> bool:
                 """Pop the insertInlineImage request `e` names from `requests` (the
-                batch that raised `e`), recording the failure on its image's outcome
+                batch that raised `e`), plus its link request if the image was
+                linked (#977), recording the failure on its image's outcome
                 entry. False if `e` isn't an image-fetch failure, so the caller
                 re-raises."""
                 bad_index = _failed_insert_image_request_index(e)
                 if bad_index is None or bad_index >= len(requests):
                     return False
                 bad_request = requests.pop(bad_index)
+                # Left in place, the link would land on whatever character now
+                # sits at the image's position. Matched by identity: the list
+                # holds the same dict objects ast_to_requests recorded.
+                link = image_links.get(id(bad_request))
+                if link is not None:
+                    link_index = next(i for i, r in enumerate(requests) if r is link)
+                    requests.pop(link_index)
                 img_id = request_id_to_img_id.get(id(bad_request))
                 entry = entry_by_id.get(img_id) if img_id is not None else None
                 if entry is not None:
@@ -660,7 +677,7 @@ async def _apply_doc_content(
                     image_failures += 1
                     if image_failures != 2:
                         continue
-                    tail_start = _positional_insert_tail_start(remaining)
+                    tail_start = _positional_insert_tail_start(remaining, image_links)
                     # Fail-safe: split only if every image request really is in the
                     # tail. If ast_to_requests ever emits something after its
                     # positional-insert pass, the boundary scan comes up short —
@@ -728,7 +745,7 @@ def _walk_headings_and_anchor_runs(
 ) -> tuple[list[tuple[str, str]], list[tuple[str, int, int]]]:
     """Recursively walk document body content, including table cells,
     collecting (heading_text, heading_id) pairs and (anchor_url, start, end)
-    runs for any run whose link_url starts with '#'.
+    runs for any run or inline image whose link_url starts with '#'.
 
     Mirrors _collect_doc_paragraphs's two correctness properties: it recurses
     into table cells (a heading or an anchor link living inside a table cell
@@ -767,6 +784,16 @@ def _walk_headings_and_anchor_runs(
                     end = pe.get("endIndex")
                     if end is not None:
                         offset = end
+                    # A linked image carries its link on the inlineObjectElement's
+                    # own textStyle (#977).
+                    link_url = (
+                        pe.get("inlineObjectElement", {})
+                        .get("textStyle", {})
+                        .get("link", {})
+                        .get("url", "")
+                    )
+                    if link_url.startswith("#") and end is not None:
+                        anchor_runs.append((link_url, run_start, end))
 
             if is_heading and heading_id:
                 headings.append(("".join(text_parts).strip(), heading_id))