mcp-gee-sweet 0.9.2.dev283__tar.gz → 0.9.2.dev289__tar.gz

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev289}/.claude/team-roles/amy.md

@@ -2,7 +2,9 @@ Tech Writer (Amy). Reached via `/team-member Amy` after that command's shared is
 
 Amy keeps documentation accurate, friendly, comprehensive, and fun — README, `docs/`, tool docstrings surfaced to users, and QA test docs' clarity (not their results).
 
-- **On `team/amy` (idle):** claim work the same way Ash/Jay do, but from the `documentation` label instead of `ready-for-development`: `gh issue list --repo khuisman/mcp-gee-sweet --label documentation --state open --json number,title,body --jq 'sort_by(.number)'`. Filter out issues already claimed by an open PR the same way Dev roles do. Before picking one, check whether any open issues describe the same underlying problem from different angles (e.g. several tickets all pointing at one stale doc file) — if so, consolidate into a single new issue, close the redundant ones as `not planned` with a comment linking to the survivor, and work the consolidated issue instead of the originals (see #303 for precedent). Once duplicates are consolidated, pick the highest-priority remaining issue by this order, fixed so the choice doesn't need re-deriving each session: (1) issues labeled with the current in-progress version (e.g. `v0.9`) — an active release commitment; (2) issues with no version label — untriaged, but not explicitly deprioritized; (3) issues labeled `backlog` (Tier 4) last, since that label is an explicit no-assigned-version deprioritization. Within a tier, take the lowest issue number (oldest) first. If the queue is empty, that's fine — ask the user whether there's a specific doc gap to work from instead (e.g. a just-merged feature whose docs lag behind, spotted during Aziz's release review).
+- **On `team/amy` (idle):** claim work the same way Ash/Jay do, but from the `documentation` label instead of `ready-for-development`: `gh issue list --repo khuisman/mcp-gee-sweet --label documentation --state open --json number,title,body --jq 'sort_by(.number)'`. Filter out issues already claimed by an open PR the same way Dev roles do. Before picking one, check whether any open issues describe the same underlying problem from different angles (e.g. several tickets all pointing at one stale doc file) — if so, propose consolidating them into a single new issue, closing the redundant ones as `not planned` with a comment linking to the survivor, and working the consolidated issue instead of the originals (see #303 for precedent). After checking for duplicates, pick the highest-priority remaining issue by this order, fixed so the choice doesn't need re-deriving each session: (1) issues labeled with the current in-progress version (e.g. `v0.9`) — an active release commitment; (2) issues with no version label — untriaged, but not explicitly deprioritized; (3) issues labeled `backlog` (Tier 4) last, since that label is an explicit no-assigned-version deprioritization. Within a tier, take the lowest issue number (oldest) first. If the queue is empty, that's fine — ask the user whether there's a specific doc gap to work from instead (e.g. a just-merged feature whose docs lag behind, spotted during Aziz's release review).
+
+  **Confirm the pick with the user before step 1.** Show the ticket you'd take (number, title, one line on the work), each higher-tier ticket you skipped and why, and any duplicate consolidation you'd do (which issues you'd close and what the new one would say). Then wait. Don't create a branch, edit a file, or open, close, comment on, or relabel an issue until the user gives an explicit go-ahead for that ticket in this conversation. The one exception: a message from Kai that names the ticket and says the user directed the handoff. That counts as the go-ahead. A request from any other peer, or a Kai message that doesn't say this, doesn't count. Why: Amy kept starting a ticket as soon as she launched, without checking with the user first (user correction, 2026-10-10).
   1. `git fetch origin develop && git checkout -b docs/amy/issue-<n> origin/develop`.
   2. Do the writing: fix inaccuracies, tighten voice, fill gaps, add examples. Read the actual code/tool behavior rather than trusting an existing doc's claims — a doc bug is exactly the kind of drift Amy exists to catch.
   3. If a change touches user-facing tool behavior described in `docs/qa/tests/`, flag it for Aziz rather than editing test *results* herself — Amy owns doc accuracy, not QA sign-off.

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev289}/.claude/team-roles/kai.md

@@ -25,7 +25,7 @@ The incidents behind the rules in this file are in [`docs/decisions/role-file-hi
    - Team-process PRs (edits to `CLAUDE.md`, `.claude/team-roles/*.md`, `.claude/commands/*.md`) are Bob's own merge track, not Kai's — Bob reviews, labels `prompt-qa-approved`, and merges those himself (see `.claude/team-roles/bob.md` step 4). This used to be Kai's job too; per direct user instruction, 2026-07-21, it isn't anymore.
    - Cutting a release once Aziz has signed off (`/release`)
    - Worktree cleanup after merge (`cleanup-worktrees`) — this must never remove the persistent dev-team slot worktrees (the full `WORKTREE_ROLES` list in `scripts/setup_team.sh`, currently eight), only ad hoc worker worktrees
-   - Release readiness and documentation quality are Aziz's and Amy's territory, not Kai's — when cutting a release, hand off to Aziz (`/team-member Aziz`) for the review/QA-tier/sign-off pass rather than doing it here; route doc gaps found along the way to Amy (`documentation` label) rather than fixing them inline.
+   - Release readiness and documentation quality are Aziz's and Amy's territory, not Kai's — when cutting a release, hand off to Aziz (`/team-member Aziz`) for the review/QA-tier/sign-off pass rather than doing it here; route doc gaps found along the way to Amy (`documentation` label) rather than fixing them inline. Message Amy to take a specific ticket only when the user has told you to, and say so in the message (e.g. "the user asked me to hand you #N"): `amy.md` treats only a handoff that names the ticket and says the user directed it as her go-ahead.
 
    Do NOT pick up ticket implementation directly in this session — hand it to a worker session via `start-worktree` (or `next-issue`, which does this automatically), or to a dev-team lane via `/team-member` if the team is active.
 

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev289}/PKG-INFO

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

@@ -120,6 +120,23 @@ Three gaps were kept **as documented limitations, not implementation shortcuts**
   next to ordinary text in the same paragraph — the one case it can't resolve (a paragraph
   containing *only* a single inline code span, nothing else) is the genuinely ambiguous case
   documented above, not a bug in the heuristic.
+- **Code delimiters** (#923, #940, #938): a code span's content is literal, so the serializer
+  can only pick a delimiter and padding. A fenced block's fence and an inline span's delimiter
+  are one backtick longer than the longest backtick run in the content (fences at least 3).
+  An inline span is padded with one space a side when its content starts or ends with a
+  backtick, or starts *and* ends with a space (CommonMark strips one space from each end in that
+  case). Adjacent code runs sharing a link merge into one span, since two spans side by side
+  would read as one. An inline code run's line breaks become `<br>` between separate spans: a
+  span can't hold a line break, and a raw newline could start a new block. In a table cell, a
+  code line containing `|` renders as raw HTML `<code>`, because the GFM `\|` escape shows its
+  backslash in renderers that don't implement it. Text inside raw HTML is still parsed as
+  Markdown, so every ASCII punctuation character in that line becomes a numeric entity
+  (`&#124;`, `&#42;`, `&#92;`, ...). Line breaks at either end of a linked code run go outside the
+  link. Because the exporter writes its own `<br>`/`<code>` HTML, plain text escapes `~`, a `<`
+  that could open a tag, and an `&` that starts an entity, so typed markup can't pass for
+  exporter markup. The export tests
+  check these against a strict CommonMark parser (`markdown-it-py`), since Python-Markdown
+  strips whitespace in code spans and closes a fence only on an exact-length match.
 - **Tight vs. loose lists**: consecutive `BulletItem` nodes are joined with a single `"\n"`
   rather than the `"\n\n"` used between other block types — CommonMark still parses a
   blank-line-separated run of list items as one list either way (just "loose", wrapped in `<p>`

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev289}/docs/qa/tests/docs_content.md

@@ -1016,6 +1016,9 @@ Markdown pipe table. 3 rows, 2 columns: Name/Value, Alpha/1, Beta/2 — all corr
 **Result (2026-09-04) ✅ PASS**
 create_doc_from_file(tc-d195-create-doc.md): docId+web_link, no error. get_doc_structure confirmed HEADING_1 "QA Test Document", bold/italic runs, ☑/☐ bullet items, table (Col A/Col B, one/two). Trashed.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+create_doc_from_file(tc-d195-create-doc.md): docId+web_link, no error. get_doc_structure: HEADING_1 "QA Test Document", bold/italic runs, ☑/☐/Plain item bullets, Col A/Col B table. Playwright (account check passed): heading, bold/italic, checkbox glyphs, and table render correctly. Trashed.
+
 ---
 
 ### TC-DOC45: `create_doc_from_file` with a local .html file ⚠️ requires-oauth ⚠️ destructive
@@ -1036,6 +1039,9 @@ create_doc_from_file(tc-d195-create-doc.md): docId+web_link, no error. get_doc_s
 **Result (2026-09-04) ✅ PASS**
 create_doc_from_file(tc-d196-create-doc.html): docId+web_link, no error. get_doc_structure confirmed HEADING_2 "From HTML file", paragraph "Content paragraph." Trashed.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+create_doc_from_file(tc-d196-create-doc.html): docId+web_link, no error. get_doc_structure: HEADING_2 "From HTML file", paragraph "Content paragraph." Trashed.
+
 ---
 
 ### TC-DOC46: `create_doc_from_file` file not found
@@ -1051,6 +1057,9 @@ create_doc_from_file(tc-d196-create-doc.html): docId+web_link, no error. get_doc
 **Result (2026-09-04) ✅ PASS**
 create_doc_from_file('~/does-not-exist.md') returned {"error": "File not found: ~/does-not-exist.md"}, no exception.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+create_doc_from_file('~/does-not-exist.md') returned {"error": "File not found: ~/does-not-exist.md"}, no exception. Unsupported .txt also still returns the no-hint message "Use .md or .html/.htm" (shared helper, format_overridable=False).
+
 ---
 
 ### TC-DOC47: `write_doc_content` inline code monospace ⚠️ destructive
@@ -2804,6 +2813,9 @@ insert_local_images (default revoke_sharing) on scratch doc with "Marker: IMGMAR
 **Result (2026-09-04) ✅ PASS**
 create_doc HTML table with image in a cell: no error. get_doc_structure: cell 0 "Before", cell 2 "After", cell 1 (image) empty (""). No images key in response (image dropped at parse time, table-cell images still out of scope). No timeout/hang. Trashed.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+create_doc HTML table with an image in a cell: returned at once, no error, no `images` key. get_doc_structure: cell 0 "Before", cell 1 "", cell 2 "After". No hang. Trashed.
+
 ---
 
 ### TC-DOC154: A `<pre>` block resumed after a nested table doesn't leave a spurious trailing whitespace-only paragraph ⚠️ requires-oauth ⚠️ destructive
@@ -3107,6 +3119,9 @@ Generated real ~76MB 4800x5000 (24.0MP, under 25MP pre-check) noise PNG. Main ca
 **Result (2026-09-04) ✅ PASS**
 update_doc_from_file(tc-d195-create-doc.md) on DOC_ID: returned docId matching DOC_ID, no error. get_doc_structure matches TC-DOC44's create_doc_from_file output exactly (HEADING_1, bold/italic runs, ☑/☐ items, Col A/Col B table). get_file_metadata before/after identical name/parents/webViewLink — doc identity/location preserved.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+update_doc_from_file(tc-d195-create-doc.md) on DOC_ID: docId matched, web_link present, no error. get_doc_structure matches TC-DOC44's output (HEADING_1, bold/italic, ☑/☐ items, Col A/Col B table). get_file_metadata before/after: same name/parents/webViewLink.
+
 ### TC-DOC169: `update_doc_from_file` with a local .html file ⚠️ destructive
 **Prompt**
 > "Update Google Doc {DOC_ID} from the file <repo-root>/docs/qa/fixtures/tc-d196-create-doc.html"
@@ -3123,6 +3138,9 @@ update_doc_from_file(tc-d195-create-doc.md) on DOC_ID: returned docId matching D
 **Result (2026-09-04) ✅ PASS**
 update_doc_from_file(tc-d196-create-doc.html): docId matched, no error. get_doc_structure: HEADING_2 "From HTML file", paragraph "Content paragraph." — matches TC-DOC45.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+update_doc_from_file(tc-d196-create-doc.html): docId matched, no error. get_doc_structure: HEADING_2 "From HTML file", paragraph "Content paragraph."
+
 ### TC-DOC170: `update_doc_from_file` file not found
 **Prompt**
 > "Update Google Doc {DOC_ID} from the file ~/does-not-exist.md"
@@ -3137,6 +3155,9 @@ update_doc_from_file(tc-d196-create-doc.html): docId matched, no error. get_doc_
 **Result (2026-09-04) ✅ PASS**
 update_doc_from_file('~/does-not-exist.md') returned {"error":"File not found: ~/does-not-exist.md"}, no exception. get_doc_content confirmed doc unchanged (still HEADING_2/paragraph from DOC169).
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+update_doc_from_file('~/does-not-exist.md') returned {"error": "File not found: ~/does-not-exist.md"}, no exception. get_doc_content unchanged.
+
 ### TC-DOC171: `update_doc_from_file` unsupported extension with no override returns an error, doc untouched
 **Setup:** create a local file `qa-update.txt` with arbitrary plain text
 
@@ -3155,6 +3176,9 @@ update_doc_from_file('~/does-not-exist.md') returned {"error":"File not found: ~
 **Result (2026-09-04) ✅ PASS**
 update_doc_from_file(qa-update.txt, no override) returned {"error":"Unsupported file extension '.txt'. Use .md or .html/.htm, or pass content_format explicitly."}. get_doc_content confirmed doc untouched — no Docs API call made.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+update_doc_from_file(qa-update.txt) returned {"error": "Unsupported file extension '.txt'. Use .md or .html/.htm, or pass content_format explicitly."}. get_doc_content unchanged.
+
 ### TC-DOC172: `update_doc_from_file` `content_format` explicitly overrides an unrecognized extension ⚠️ destructive
 **Setup:** create a local file `qa-update-override.txt` containing `# Overridden Heading\n\nParagraph text.\n`
 
@@ -3171,6 +3195,9 @@ update_doc_from_file(qa-update.txt, no override) returned {"error":"Unsupported
 **Result (2026-09-04) ✅ PASS**
 update_doc_from_file(qa-update-override.txt, content_format='markdown') succeeded, no error. get_doc_structure: HEADING_1 "Overridden Heading", paragraph "Paragraph text." Fixture restored after.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+update_doc_from_file(qa-update-override.txt, content_format='markdown'): no error. get_doc_structure: HEADING_1 "Overridden Heading", paragraph "Paragraph text." Fixture restored to setup.md's seed HTML via write_doc_content afterward.
+
 ---
 
 ## `get_doc_as_markdown`
@@ -3514,6 +3541,69 @@ Edge spacers (single <br> each): markdown = "| Trailing test<br> |\n| --- |\n| <
 
 ---
 
+### TC-DOC206: Inline code keeps a space at both ends, and adjacent code runs export as one span (#938)
+**Setup:** raw HTML via `write_doc_content(doc_id={DOC_ID}, content_format='html', content="<p>pad <code> both ends </code> end</p><p>adj <code>x`</code><b><code>`y</code></b> end</p>")`. The bold change splits the second paragraph's code into two Courier New runs.
+
+**Prompt**
+> "Export doc {DOC_ID} as Markdown"
+
+**Checks**
+- `markdown` contains ``pad `  both ends  ` end``: one extra space a side, since CommonMark strips one space from each end when both ends have one
+- `markdown` contains ```` adj ```x``y``` end ````: the two runs merge into one span, with a three-backtick delimiter around the two-backtick run
+- Rendering `markdown` with a strict CommonMark renderer (e.g. `markdown-it-py`'s `commonmark` preset, not Python `markdown`, which strips code-span whitespace) gives `<code> both ends </code>` and `<code>x``y</code>`
+
+**Cleanup:** write fixture content back over `{DOC_ID}`
+
+**Result (2026-10-10) ✅ PASS — Kit, PR #968 round 1 (`d2449f7`).** `get_doc_as_markdown` returned ``pad `  both ends  ` end\n\nadj ```x``y``` end``. markdown-it-py 4.2.0's `commonmark` preset rendered `<code> both ends </code>` and `<code>x``y</code>`. Fixture content was written back.
+
+**Result (2026-10-10) ✅ PASS — Kit, PR #968 round 2 (`759362a`).** Re-run because the fix changed `_render_run`. Output was identical to round 1. Fixture content was written back.
+
+---
+
+### TC-DOC207: Inline code in a table cell keeps a literal `|` and puts line breaks outside the code (#938)
+**Setup:** raw HTML via `write_doc_content(doc_id={DOC_ID}, content_format='html', content="<table><tr><td>Head</td></tr><tr><td>pipe <code>a|b</code> and a|b</td></tr><tr><td><code>x</code><br><code>y|z</code></td></tr></table>")`. The last cell has two code-styled paragraphs.
+
+**Prompt**
+> "Export doc {DOC_ID} as Markdown"
+
+**Checks**
+- `markdown` contains the row `| pipe <code>a&#124;b</code> and a\|b |`: the code's pipe is an HTML entity inside raw `<code>`, with no backslash, and the plain-text pipe is still escaped
+- `markdown` contains the row `` | `x`<br><code>y&#124;z</code> | ``: the cell's paragraph break is a `<br>` between two code elements, not inside one
+- Rendering `markdown` with a GFM-table renderer (e.g. `markdown-it-py`'s `commonmark` preset with `table` enabled) gives a one-column table whose cells contain `<code>a|b</code>` and `<code>x</code><br><code>y|z</code>`. No cell shows a backslash
+
+Not covered live: a soft break (Shift+Enter) inside an inline code run in a paragraph that also has plain text. No tool can build one (`style_doc_range` doesn't set a font), so unit tests cover it (`TestInlineCodeCommonMark::test_newline_in_inline_code_does_not_start_a_new_block`).
+
+**Cleanup:** write fixture content back over `{DOC_ID}`
+
+**Result (2026-10-10) ✅ PASS (checks as written); ❌ probe beyond the case — Kit, PR #968 round 1 (`d2449f7`).** `get_doc_as_markdown` returned both expected rows exactly: `| pipe <code>a&#124;b</code> and a\|b |` and `` | `x`<br><code>y&#124;z</code> | ``. markdown-it-py's `commonmark` preset with `table` enabled rendered a one-column table with `<code>a|b</code>` and `<code>x</code><br><code>y|z</code>`, and no backslash. Probe: a cell with code `a|*b* _c_` exported as `<code>a&#124;*b* _c_</code>`, which renders `<em>` inside the `<code>`. A cell with code `C:\|x` exported as `<code>C:\&#124;x</code>`, which renders as `C:&amp;#124;x`. Both are sent back on the PR. Fixture content was written back.
+
+**Result (2026-10-10) ✅ PASS — Kit, PR #968 round 2 (`759362a`).** Re-run because the fix changed the table-cell `<code>` path. Both expected rows came back exactly, and the render was the same as round 1. The round 1 probe is now TC-DOC208, which passes. Fixture content was written back.
+
+---
+
+### TC-DOC208: Markdown punctuation inside table-cell `<code>`, linked code after a cell break, and HTML-like plain text all export literally (#938)
+**Setup:** raw HTML via `write_doc_content(doc_id={DOC_ID}, content_format='html', content=...)` with this content. The `\` in `C:\|x` is one literal backslash character.
+
+```html
+<table><tr><td>Head</td></tr><tr><td><code>a|*b* _c_</code></td></tr><tr><td><code>C:\|x</code></td></tr><tr><td><code>x</code><br><a href="https://example.com/b"><code>b</code></a></td></tr></table><p>Use &lt;br&gt; or &amp;#124; and ~~old~~, AT&amp;T a &lt; b</p>
+```
+
+**Prompt**
+> "Export doc {DOC_ID} as Markdown"
+
+**Checks**
+- `markdown` contains the row `| <code>a&#124;&#42;b&#42; &#95;c&#95;</code> |`: every punctuation character inside raw `<code>` is a numeric entity
+- `markdown` contains the row `| <code>C&#58;&#92;&#124;x</code> |`: the backslash is an entity too, so it can't escape the pipe's `&`
+- `markdown` contains the row `` | `x`<br>[`b`](https://example.com/b) | ``: the `<br>` from the cell's paragraph break is outside the link
+- `markdown` contains the paragraph `Use \<br> or \&#124; and \~\~old\~\~, AT&T a < b`: `<` before a tag, `&` starting an entity, and `~` are escaped; `AT&T` and `a < b` are not
+- Rendering `markdown` with `markdown-it-py`'s `commonmark` preset with `table` enabled gives cells `<code>a|*b* _c_</code>`, `<code>C:\|x</code>`, and `<code>x</code><br><a href="https://example.com/b"><code>b</code></a>`, with no `<em>` inside any `<code>`, and the paragraph renders as literal text (no line break, no `|`, no strikethrough)
+
+**Cleanup:** write fixture content back over `{DOC_ID}`
+
+**Result (2026-10-10) ✅ PASS — Kit, PR #968 round 2 (`759362a`).** `get_doc_as_markdown` returned all four expected lines exactly. markdown-it-py 4.2.0 (`commonmark` + `table` + `strikethrough`) rendered the cells `<code>a|*b* _c_</code>`, `<code>C:\|x</code>`, and `<code>x</code><br><a href="https://example.com/b"><code>b</code></a>`, and the paragraph `Use &lt;br&gt; or &amp;#124; and ~~old~~, AT&amp;T a &lt; b`, with no `<em>`, `<del>`, or line break. Fixture content was written back.
+
+---
+
 ## Orphan fileId on inline-image sharing failure (#649)
 
 Mirrors #420's fix in `drive/transfer.py` (see TC-D249/TC-D250 in `docs/qa/tests/drive_transfer.md`) applied to the same create()-succeeds-but-follow-up-fails shape in `docs/images.py`'s `upload_and_share_image` and `docs/content.py`'s `_resolve_image_source`: a transient failure in the `permissions().create()`/`files().get()` sharing step, after `files().create()` (or an already-uploaded `_upload_local_file`) had already succeeded, previously returned a bare `{"error": ...}` with no way to find the Drive file that now genuinely exists. Not reliably reproducible live (would require forcing a transient API failure in the exact window between create and share); verified by unit test instead, matching TC-D249/TC-D250's own convention.
@@ -3747,12 +3837,15 @@ Tool call: `insert_local_images(doc_id={DOC_ID}, images=[{"marker": "IMGMARKERBO
 **Checks**
 - `results[0]` has no `fileId` and an `error` containing "14000x13000 (182.0 megapixels)" and "25 megapixels"
 - No `qa-bomb.png` appears in `{FOLDER_ID}`, and the marker text is unchanged
-- Re-run with `auto_downscale=True`: `results[0]` still has no `fileId`, and its `error` ends with "Could not auto-downscale it (unreadable or corrupt image, animated, or too large to decode safely)."
+- Re-run with `auto_downscale=True`: `results[0]` still has no `fileId`, and its `error` ends with "Could not auto-downscale it (unreadable or corrupt image, animated, too large to decode safely, or still over the file-size limit after shrinking)." (the last reason was added by #894/#581)
 
 **Cleanup:** trash the doc; `rm /tmp/qa-bomb.png`
 
 **Result (2026-09-24) ✅ PASS — Kit, PR #801 round 2 (fix `4d5f842`, issue #560).** Both checks matched exactly, and nothing was uploaded. (Round 1 reproduced the pre-fix behavior locally: `check_image_file` returned `None` for this file.) Doc trashed.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+insert_local_images with the 14000x13000 PNG: results[0] no fileId, error names "14000x13000 (182.0 megapixels)" and "25 megapixels". With auto_downscale=True: error ends with "Could not auto-downscale it (unreadable or corrupt image, animated, too large to decode safely, or still over the file-size limit after shrinking)." No qa-bomb.png in FOLDER_ID; marker text unchanged. Doc trashed.
+
 ---
 
 ### TC-DOC198: `insert_local_images` — an unreadable local file fails with "failed to read local file", not a raw upload error (PR #801)
@@ -3935,3 +4028,28 @@ Two extra probes ran from a scratch copy of the script (not committed):
 All files from both probes and the three steps, and the doc, were trashed.
 
 **Result (2026-10-04) ✅ PASS — Kit, PR #903 round 2 (`4e392c3`).** All six steps ran from the kit worktree with its OAuth token, on a fresh scratch doc in `{FOLDER_ID}`. Each step printed `cancelled at '<point>'; the tool returned nothing` and the WARNING `Doc edit for {DOC_ID} failed or was cancelled after its images were resolved; files created by this call: <one file ID>; pre-existing files: none; still link-shared by this call: ...`. That last field listed `{KEPT_FILE_ID}` for step 4 and was `none` for every other step. Steps 2 (`share-fail`, the orphan) and 6 (`revoke`), which logged nothing in round 1's probe, now log. `list_permissions` showed no `anyone` grant on `{SHARE_FILE_ID}`, `{ORPHAN_FILE_ID}`, `{EDIT_FILE_ID}`, `{INFLIGHT_FILE_ID}`, or `{REVOKE_FILE_ID}`, and showed `anyoneWithLink`/`reader` on `{KEPT_FILE_ID}`. After `refresh_cache`, `get_doc_as_markdown` read `Before`, `IMGMARKER883`, an image, an image, `After`. So steps 1–4 left `IMGMARKER883` untouched, step 6's edit landed before its cancel, and step 5's in-flight edit also landed (an image replaced `INFLIGHT883`). All six files and the doc were trashed.
+
+## Unreadable source file returns an error — `create_doc_from_file` / `update_doc_from_file` (PR #961)
+
+Both tools read the local file through the shared `_read_doc_source_file` helper. Before PR #961's round 2, a path that existed but wasn't a readable UTF-8 regular file raised out of the tool (`[Errno 21] Is a directory`, `'utf-8' codec can't decode byte 0xe9 ...`) instead of returning `{"error": ...}`.
+
+### TC-DOC208: A directory or non-UTF-8 source file returns `{"error": ...}`, and nothing is created or edited
+**Setup:**
+- `mkdir -p /tmp/tc-doc208/dir.md`
+- `python3 -c "open('/tmp/tc-doc208/latin1.html','wb').write('<p>caf\xe9</p>'.encode('latin-1'))"`
+- `get_doc_content(file_id={DOC_ID})`, note the content for comparison afterward
+
+**Steps**
+1. `create_doc_from_file(local_path="/tmp/tc-doc208/dir.md", folder_id={FOLDER_ID})`
+2. `create_doc_from_file(local_path="/tmp/tc-doc208/latin1.html", folder_id={FOLDER_ID})`
+3. `update_doc_from_file(doc_id={DOC_ID}, local_path="/tmp/tc-doc208/dir.md")`
+4. `update_doc_from_file(doc_id={DOC_ID}, local_path="/tmp/tc-doc208/latin1.html")`
+
+**Checks**
+- Each call returns a dict with an `error` key naming the path (any wording). None comes back as `Error executing tool ...`
+- `list_files(folder_id={FOLDER_ID})` shows no new Doc named `dir` or `latin1` (the filename stem `create_doc_from_file` uses as the default title; steps 1–2 fail before the Drive `create`)
+- `get_doc_content(file_id={DOC_ID})` matches the Setup snapshot (steps 3–4 fail before any Docs API call)
+
+**Cleanup:** `rm -rf /tmp/tc-doc208`
+
+**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-doc208`. 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`).

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev289}/docs/roadmap.md

@@ -192,7 +192,7 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [x] `create_paragraph_bullets` (`style.py`) has the same isolated-run collapse-to-`nestingLevel 0` bug #439 fixed in `emitter.py` only — port PR #711's anchor-paragraph approach to the sibling path (PR #723) ([#713](https://github.com/khuisman/mcp-gee-sweet/issues/713))
 - [x] Lock in the isolated-run rendering rule — an isolated bullet run renders at its true depth (`depth N` → `nestingLevel N`) at *every* depth, never clamped (decided 2026-09-09: consistency over avoiding orphaned indent; the markup generator owns the depth it emits). Extend TC-DOC190 with a `min_depth >= 2` case; state the rule in `emitter.py`'s bullet-pass comment and the `docs/emitter.py` paragraph of `CLAUDE.md` (PR #731) ([#714](https://github.com/khuisman/mcp-gee-sweet/issues/714))
 - [x] `create_doc` markdown: a fenced code block whose body is raw HTML tags renders as loose plain paragraphs (fence ignored, indentation flattened) instead of a monospaced code block — python-markdown's raw-HTML-block handling appears to pre-empt `fenced_code`. Surfaced during #714 triage (PR #730) ([#719](https://github.com/khuisman/mcp-gee-sweet/issues/719))
-- [ ] **Bundle:** Docs write side (emitter, html_parser, images, content), one PR closing [#509](https://github.com/khuisman/mcp-gee-sweet/issues/509), [#567](https://github.com/khuisman/mcp-gee-sweet/issues/567), [#581](https://github.com/khuisman/mcp-gee-sweet/issues/581), [#638](https://github.com/khuisman/mcp-gee-sweet/issues/638), [#715](https://github.com/khuisman/mcp-gee-sweet/issues/715) — lane A ([#894](https://github.com/khuisman/mcp-gee-sweet/issues/894))
+- [x] **Bundle:** Docs write side (emitter, html_parser, images, content), one PR closing [#509](https://github.com/khuisman/mcp-gee-sweet/issues/509), [#567](https://github.com/khuisman/mcp-gee-sweet/issues/567), [#581](https://github.com/khuisman/mcp-gee-sweet/issues/581), [#638](https://github.com/khuisman/mcp-gee-sweet/issues/638), [#715](https://github.com/khuisman/mcp-gee-sweet/issues/715) — lane A (PR #961) ([#894](https://github.com/khuisman/mcp-gee-sweet/issues/894))
 - [x] **Bundle:** Calendar hardening, one PR closing [#459](https://github.com/khuisman/mcp-gee-sweet/issues/459), [#615](https://github.com/khuisman/mcp-gee-sweet/issues/615), [#626](https://github.com/khuisman/mcp-gee-sweet/issues/626), [#627](https://github.com/khuisman/mcp-gee-sweet/issues/627), [#726](https://github.com/khuisman/mcp-gee-sweet/issues/726) — lane B (PR #912) ([#890](https://github.com/khuisman/mcp-gee-sweet/issues/890))
 - [x] `delete_file(permanent=True)` surfaces a misleading 404 when the caller can trash but not permanently delete (Shared Drive Content manager) — an agent can read it as "already gone" and skip cleanup; check `capabilities.canDelete` first — lane B ([#876](https://github.com/khuisman/mcp-gee-sweet/issues/876)) (PR #888)
 - [x] SSE: SIGTERM with an SSE stream open logs an "Exception in ASGI application" traceback; the server still exits cleanly, pre-existing before #833 — lane A (PR #911) ([#868](https://github.com/khuisman/mcp-gee-sweet/issues/868))
@@ -351,7 +351,7 @@ Requires `gmail/v1` client and `https://www.googleapis.com/auth/gmail.modify` sc
 - [ ] Define the correctness rubric and own execution for the composite-vs-primitive efficiency benchmark — Aziz ([#584](https://github.com/khuisman/mcp-gee-sweet/issues/584))
 - [ ] QA `.env` has no single source of truth — `setup_team.sh` only copies `.env` into a worktree when absent, so fixture-ID changes never propagate (had to hand-sync 9 copies for #305); also `run.md` vs `setup.md` disagree on `docs/qa/.env` vs repo-root `.env`. Surfaced by PR #677, relates to [#648](https://github.com/khuisman/mcp-gee-sweet/issues/648) ([#679](https://github.com/khuisman/mcp-gee-sweet/issues/679))
 - [x] `list_files`/`get_file_metadata` docstrings cite a stale `upload_local_file` `modifiedTime` caveat (fixed at the root by PR #472) and carry a broken self-referential contrast — from Bob's `docs/tools.md` docstring sweep; Dev/QA track, batches with #682/#683 ([#681](https://github.com/khuisman/mcp-gee-sweet/issues/681)) (PR 898)
-- [ ] `create_doc` family docstrings name only the ~25MP inline-image limit; the ~50MB byte-size limit (#562) is equally enforced, and 3 deferring docstrings inherit the gap — from Bob's `docs/tools.md` docstring sweep. Routed to Amy (`documentation`); closed community PR #932 has a diff ([#682](https://github.com/khuisman/mcp-gee-sweet/issues/682))
+- [x] `create_doc` family docstrings name only the ~25MP inline-image limit; the ~50MB byte-size limit (#562) is equally enforced, and 3 deferring docstrings inherit the gap — from Bob's `docs/tools.md` docstring sweep. Routed to Amy (`documentation`); closed community PR #932 has a diff ([#682](https://github.com/khuisman/mcp-gee-sweet/issues/682)) (PR 970)
 - [ ] `qa(docs)`: no comprehensive fixture exercising every Docs formatting construct in one pass — Aziz, triaged out of `backlog` 2026-09-11 ([#477](https://github.com/khuisman/mcp-gee-sweet/issues/477))
 - [ ] Fact-check and word competitive/benchmark claims once real benchmark numbers exist — routed to Amy, triaged out of `backlog` 2026-09-11 ([#585](https://github.com/khuisman/mcp-gee-sweet/issues/585))
 - [x] QA test-doc cross-reference cleanup after the `drive.md`/`docs.md` split (PR #582) — triaged out of `backlog` 2026-09-11 ([#590](https://github.com/khuisman/mcp-gee-sweet/issues/590)) (PR #851)

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev289}/pyproject.toml

@@ -97,4 +97,5 @@ dev = [
     "pytest-cov>=7.1.0",
     "ruff>=0.16.5",
     "tomli>=2.0.1; python_version < '3.11'",
+    "markdown-it-py>=3.0.0",
 ]

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev289}/src/mcp_gee_sweet/tools/docs/ast_to_markdown.py

@@ -21,11 +21,21 @@ Known, deliberate gaps (documented rather than silently dropped):
 from __future__ import annotations
 
 import re
+import string
 
 from .ast import BulletItem, Cell, DocNode, Heading, Image, NamedBlock, Paragraph, Run, Table
 from .emitter import _build_phantom_set
 
-_MD_ESCAPE = re.compile(r"([\\`*_\[\]])")
+# Characters in plain text that Markdown would otherwise read as syntax. "~" is
+# GFM strikethrough. "<" only when it could open an HTML tag or autolink, and
+# "&" only when it starts an entity reference, so ordinary prose ("a < b",
+# "AT&T") stays readable. Exported text must not be mistaken for the <br> and
+# <code> HTML the exporter writes itself (#938).
+_MD_ESCAPE = re.compile(
+    r"[\\`*_\[\]~]"
+    r"|<(?=[A-Za-z/!?])"
+    r"|&(?=#[0-9]{1,7};|#[xX][0-9a-fA-F]{1,6};|[A-Za-z][A-Za-z0-9]*;)"
+)
 _BACKTICK_RUN = re.compile(r"`+")
 
 # A paragraph whose rendered text starts with one of these (unescaped) would be
@@ -93,23 +103,16 @@ def _render_code_block(node: Paragraph) -> str:
     Run text did."""
     segments: list[str] = []
     buffer = ""
-
-    def fenced(text: str) -> str:
-        # Literal fences in the content must never close the surrounding block.
-        ticks = max((len(match.group()) for match in _BACKTICK_RUN.finditer(text)), default=0)
-        fence = "`" * max(3, ticks + 1)
-        return f"{fence}\n{text}\n{fence}"
-
     for item in node.runs:
         if isinstance(item, Run):
             buffer += item.text
         else:
             if buffer:
-                segments.append(fenced(buffer))
+                segments.append(_fenced_code_block(buffer))
                 buffer = ""
             segments.append(f"![{_escape(item.alt or '')}]({_md_link_dest(item.src)})")
     if buffer:
-        segments.append(fenced(buffer))
+        segments.append(_fenced_code_block(buffer))
     return "\n\n".join(segments)
 
 
@@ -171,7 +174,7 @@ def _md_link_dest(url: str) -> str:
 
 def _render_inline(items: list[Run | Image]) -> str:
     parts: list[str] = []
-    for item in items:
+    for item in _coalesce_code_runs(items):
         if isinstance(item, Image):
             parts.append(f"![{_escape(item.alt or '')}]({_md_link_dest(item.src)})")
         else:
@@ -179,22 +182,63 @@ def _render_inline(items: list[Run | Image]) -> str:
     return "".join(parts)
 
 
-def _render_run(run: Run) -> str:
+def _is_code_run(item: Run | Image | Table) -> bool:
+    return isinstance(item, Run) and item.font_family == "Courier New"
+
+
+def _coalesce_code_runs(items: list) -> list:
+    """Merge adjacent code runs that share a link. Docs splits a run at any
+    style change (bold, color), but rendered side by side two code spans
+    would read as one: `` `a``b` `` parses as the single span "a``b", since
+    the first span's closing delimiter and the second's opening one form one
+    backtick run. A code span can't carry those styles anyway, so the merge
+    loses nothing. Runs with different links stay apart; the link brackets
+    already separate them."""
+    merged: list = []
+    for item in items:
+        prev = merged[-1] if merged else None
+        if (
+            _is_code_run(item)
+            and prev is not None
+            and _is_code_run(prev)
+            and prev.link_url == item.link_url
+        ):
+            merged[-1] = Run(
+                text=prev.text + item.text, font_family="Courier New", link_url=prev.link_url
+            )
+        else:
+            merged.append(item)
+    return merged
+
+
+def _render_run(run: Run, in_table: bool = False) -> str:
+    """Markdown for one run. `in_table` makes the result safe inside a
+    pipe-table cell (see `_table_safe`)."""
     if run.text == "":
         return ""
     if run.font_family == "Courier New":
-        # Use a delimiter longer than any literal backtick sequence in the
-        # content, and separate edge backticks from that delimiter.
-        ticks = (
-            max((len(match.group()) for match in _BACKTICK_RUN.finditer(run.text)), default=0) + 1
-        )
-        fence = "`" * ticks
-        content = run.text
-        if content.startswith("`") or content.endswith("`"):
-            content = f" {content} "
-        body = f"{fence}{content}{fence}"
-        return f"[{body}]({_md_link_dest(run.link_url)})" if run.link_url else body
+        return _render_code_run(run, in_table)
+    body = _render_plain_run(run)
+    return _table_safe(body) if in_table else body
+
+
+def _render_code_run(run: Run, in_table: bool) -> str:
+    # Line breaks at either end go outside the link, so a cell's paragraph
+    # break (a leading "\n" from doc_to_ast) or a trailing soft break doesn't
+    # render as a <br> inside the <a>.
+    inner = run.text.strip("\n")
+    if not inner:
+        return "<br>" * len(run.text)
+    lead = "<br>" * (len(run.text) - len(run.text.lstrip("\n")))
+    trail = "<br>" * (len(run.text) - len(run.text.rstrip("\n")))
+    body = _render_code_run_text(inner, in_table)
+    if run.link_url:
+        dest = _md_link_dest(run.link_url)
+        body = f"[{body}]({_table_safe(dest) if in_table else dest})"
+    return f"{lead}{body}{trail}"
+
 
+def _render_plain_run(run: Run) -> str:
     # CommonMark emphasis delimiters can't have whitespace on the inner side
     # (e.g. "**Bold **" doesn't close — the space right before "**" means it
     # renders as literal asterisks, not bold). Keep leading/trailing
@@ -220,7 +264,64 @@ def _render_run(run: Run) -> str:
 
 
 def _escape(text: str) -> str:
-    return _MD_ESCAPE.sub(r"\\\1", text)
+    return _MD_ESCAPE.sub(lambda m: "\\" + m.group(), text)
+
+
+def _longest_backtick_run(text: str) -> int:
+    return max((len(match.group()) for match in _BACKTICK_RUN.finditer(text)), default=0)
+
+
+def _fenced_code_block(text: str) -> str:
+    # A fence must be longer than any backtick run in the content, or a
+    # literal ``` line inside the block would close it early.
+    fence = "`" * max(3, _longest_backtick_run(text) + 1)
+    return f"{fence}\n{text}\n{fence}"
+
+
+def _code_span(text: str) -> str:
+    """One CommonMark code span for `text` (which has no newline).
+
+    A code span's content is literal: backslash escapes don't work inside
+    it, so the only tools are the delimiter length and padding. The
+    delimiter is one backtick longer than the longest run in the content, so
+    no literal run can close the span. Padding is exactly one space a side
+    because CommonMark strips exactly one space from each end when both ends
+    have one (and the content isn't all spaces). That stripping is what
+    separates an edge backtick from the delimiter, and it would also eat a
+    real leading and trailing space, so both cases get padded."""
+    fence = "`" * (_longest_backtick_run(text) + 1)
+    pad = text.startswith("`") or text.endswith("`")
+    pad = pad or (text.startswith(" ") and text.endswith(" ") and text.strip(" ") != "")
+    if pad:
+        text = f" {text} "
+    return f"{fence}{text}{fence}"
+
+
+def _render_code_run_text(text: str, in_table: bool) -> str:
+    """Inline code for `text`, which may span lines.
+
+    A code span can't hold a line break: CommonMark turns one into a space,
+    and in a paragraph a raw newline can start a new block (a "# " heading,
+    a "- " item) before the span is parsed. So each line becomes its own
+    span, joined by <br> the same way a table cell joins its lines.
+
+    In a table cell, a "|" splits the cell before inline parsing, and the
+    GFM `\\|` escape inside a code span shows its backslash in renderers
+    that don't implement that rule. A line holding a "|" is written as raw
+    HTML <code> instead, which no table parser splits on. Text inside raw
+    HTML is still parsed as Markdown, so every ASCII punctuation character
+    becomes a numeric entity: an entity is never Markdown syntax, and a
+    backslash can't escape the "&" that starts one."""
+    spans: list[str] = []
+    for line in text.split("\n"):
+        if not line:
+            spans.append("")
+        elif in_table and "|" in line:
+            escaped = "".join(f"&#{ord(c)};" if c in string.punctuation else c for c in line)
+            spans.append(f"<code>{escaped}</code>")
+        else:
+            spans.append(_code_span(line))
+    return "<br>".join(spans)
 
 
 def _render_table(table: Table) -> str:
@@ -249,29 +350,38 @@ def _render_table(table: Table) -> str:
 
 def _render_cell(cell: Cell) -> str:
     parts: list[str] = []
-    for child in cell.children:
+    for child in _coalesce_code_runs(cell.children):
         if isinstance(child, Table):
             parts.append(_NESTED_TABLE_PLACEHOLDER)
         elif isinstance(child, Image):
-            parts.append(f"![{_escape(child.alt or '')}]({_md_link_dest(child.src)})")
+            parts.append(_table_safe(f"![{_escape(child.alt or '')}]({_md_link_dest(child.src)})"))
         else:
-            parts.append(_render_run(child))
-    # Pipe-table cells are single-line: a literal newline (from a multi-
-    # paragraph cell, see doc_to_ast.py's _cell_content_to_children) would
-    # break the table's row structure, so it becomes a <br> instead. "|" is
-    # escaped for the same structural reason.
-    #
-    # \n -> <br> conversion must happen BEFORE strip(), not after (#594 QA
-    # round 2): a spacer paragraph at the very start or end of a cell (as
-    # opposed to one sandwiched between two real lines) shows up here as a
-    # leading/trailing "\n" on the joined text — stripping first, as an
-    # earlier version of this function did, silently ate exactly that
-    # newline, making an edge spacer indistinguishable from a cell with no
-    # spacer at all. "<br>" is not whitespace, so converting first means
-    # strip() only removes genuine incidental whitespace, never a spacer
-    # that's already been turned into a <br> marker.
-    text = "".join(parts).replace("\n", "<br>").replace("|", "\\|")
-    return text.strip()
+            parts.append(_render_run(child, in_table=True))
+    # Every part is already table-safe, with its newlines turned into <br>,
+    # so strip() here only removes incidental whitespace, never an edge
+    # spacer paragraph (#594 QA round 2; see _table_safe).
+    return "".join(parts).strip()
+
+
+def _table_safe(text: str) -> str:
+    """Make rendered non-code Markdown safe inside a pipe-table cell.
+
+    Pipe-table cells are single-line: a literal newline (from a multi-
+    paragraph cell, see doc_to_ast.py's _cell_content_to_children) would
+    break the table's row structure, so it becomes a <br> instead. "|" is
+    escaped for the same structural reason.
+
+    This runs per part, before _render_cell's strip(), not on the joined
+    cell text after it (#594 QA round 2): a spacer paragraph at the very
+    start or end of a cell shows up as a leading/trailing "\\n", and
+    stripping first silently ate exactly that newline. "<br>" is not
+    whitespace, so converting first keeps the spacer.
+
+    Code runs never go through this: _render_code_run_text writes its own
+    <br> and table-safe <code>, and escaping its output again would put a
+    literal backslash inside the code (#938). Only a code link's
+    destination is passed through here."""
+    return text.replace("\n", "<br>").replace("|", "\\|")
 
 
 def _render_comment(comment: dict) -> str: