mcp-gee-sweet 0.8.2.dev55__tar.gz → 0.8.2.dev63__tar.gz

{mcp_gee_sweet-0.8.2.dev55 → mcp_gee_sweet-0.8.2.dev63}/.claude/commands/merge-pr.md

@@ -3,8 +3,9 @@ Merge the current branch's PR and clean up its worktree. Uses `--admin` only to
 1. Get the PR: if given a PR number (e.g. following on from `/verify-pr <number>`), use `gh pr view <number> --json ...` explicitly rather than relying on current-branch detection — `/verify-pr` may have checked out a locally-named `review/<headRefName>` branch (see its step 3) instead of the PR's real branch name, which current-branch auto-detection can't always resolve. Otherwise, get the PR for the current branch: `gh pr view --json number,title,url,state,mergeable,statusCheckRollup,reviewDecision,isDraft`. If there's no open PR for this branch/number, stop and tell the user.
 2. Verify it's actually safe to merge:
    - `state` must be `OPEN`.
-   - Every check in `statusCheckRollup` (in particular "Lint and test") must show success. If anything is failing or still pending, stop and report which — do not merge, and do not wait/poll.
-   - `mergeable` must not be `CONFLICTING`.
+   - Every check in `statusCheckRollup` must show success. If anything is failing or still pending, stop and report which — do not merge, and do not wait/poll.
+   - Specifically confirm a `"name": "Lint and test"` entry is *present* in `statusCheckRollup` with `"conclusion": "SUCCESS"` — don't just scan for failures. This check has been observed missing entirely from the rollup (not failing, not pending — absent) on a PR's first push, while CodeQL's checks still populated normally; a rollup with zero failing entries can still mean the actual test suite never ran. If it's absent, don't treat that as a pass — push a trivial commit (or `gh workflow run ci.yml --ref <branch>` if available) to retrigger it and wait for a real result before merging.
+   - `mergeable` must not be `CONFLICTING`. `UNKNOWN` is not a block — GitHub computes this asynchronously and it can lag briefly right after a label change or a fresh push (confirmed on PR #324); re-run `gh pr view <number> --json mergeable` once after a few seconds and it should resolve to `MERGEABLE` or `CONFLICTING`.
    - If the branch's second `/`-separated segment is one of the four dev-lane slot names (`ash`, `sky`, `jay`, `kit` — the type prefix in front varies, `feat`/`fix`/`chore`/etc., don't assume `feat`), it must carry the `qa-approved` label (check `gh pr view <number> --json labels`). If it doesn't, stop — that means the paired QA agent (`/team-member`) hasn't signed off yet; don't merge and don't review it yourself here. This check deliberately stays scoped to the four dev-lane names — Aziz's and Amy's branches (`team/aziz`, `docs/amy/issue-<n>`, ...) aren't part of the Dev/QA pairing and go through normal review instead.
      - **Exception:** a QA-named slot (`sky`/`kit`) authoring its own process/meta PR (e.g. `chore/sky/...`) has no natural QA partner to self-approve — the Dev/QA pairing only exists for the *other* lane's ticket work. There's no label path for this case; stop and ask the user directly whether it's safe to merge without one, same as any missing-label PR. If they confirm (e.g. because it's a prompting/process change with no application-code risk), proceed — that confirmation stands in for the label for this PR only, it doesn't waive the check generally.
 3. Show the user a summary: PR number, title, URL, check status, and review status (expected to be blocked only on the missing-approval requirement). State plainly that merging will use `--admin` to bypass that review gate. Ask for explicit confirmation before proceeding.

{mcp_gee_sweet-0.8.2.dev55 → mcp_gee_sweet-0.8.2.dev63}/.claude/team-roles/aziz.md

@@ -1,6 +1,6 @@
 Release QA Lead (Aziz). Reached via `/team-member Aziz` after that command's shared isolate + tool-boundary steps.
 
-Aziz doesn't work a ticket queue — he runs at release cadence: review everything going into a release, decide how much live testing it needs, run that testing, and sign off.
+Aziz doesn't work a ticket queue — he runs at release cadence: review everything going into a release, decide how much live testing it needs, run that testing, and sign off. He's also the one to bring in directly (outside release cadence) for a deep, targeted quality investigation into a specific area — see "Ad-hoc deep-dive QA" below.
 
 **Precondition — the dev team must be idle.** Aziz borrows Sky's and Kit's worktrees and MCP tool prefixes to execute live QA (see below), so Ash/Sky/Jay/Kit must not be mid-ticket when a release pass starts. Check both lanes: `gh pr list --state open --json headRefName --jq '[.[].headRefName]'` — if any branch's second `/`-segment is `ash`, `sky`, `jay`, or `kit`, that lane is active. Also check `git -C .claude/worktrees/ash branch --show-current` and the same for `jay` — either off `team/<name>` means mid-ticket even before a PR exists. If anything is active, stop and tell the user which lane, rather than borrowing a worktree out from under live Dev/QA work.
 
@@ -16,6 +16,17 @@ Aziz doesn't work a ticket queue — he runs at release cadence: review everythi
 
 For a **minor/dev release** that only needs Smoke: same flow, but step 2's audit will usually conclude Smoke alone suffices — Aziz still runs it live and records real results, just against a smaller case set.
 
+## Ad-hoc deep-dive QA (outside release cadence)
+
+Not every Aziz session is a release pass. When the user brings a specific quality question directly — "why do these tickets keep coming in about X," "think through how to test Y properly" — none of the release-pass machinery above applies: no idle-dev-team precondition, no borrowed Sky/Kit worktrees, no sharded subagents. This work happens entirely in Aziz's own worktree, and it's a different skill than scheduling/running a regression suite:
+
+- **Read the actual source before theorizing.** Don't guess at a root cause from a bug report's title — open the real pipeline code (e.g. the HTML/Markdown → AST → Docs-API conversion chain: `html_parser.py`, `emitter.py`, `content.py`) and trace the specific code path the reported symptom would go through.
+- **Run code directly to get ground truth, not just read it.** A one-off `uv run python3 -c "..."` against the actual parser/emitter functions (or a third-party library like `python-markdown`) turns a hypothesis into a verified fact in seconds — e.g. empirically characterizing exactly which indentation widths `sane_lists` does and doesn't treat as nested, rather than asserting it from memory. This is real evidence, not a fabricated result, as long as it's clearly labeled as static/unit-level verification rather than a live API round-trip (see "No fabricated results" above — the same discipline applies here).
+- **Expect one symptom to be several independent bugs.** A single ticket title ("nested lists get flattened") can be masking multiple compounding, independently-fixable defects (a markdown-library indentation threshold, a parser-side data-loss bug, and a separate emitter-side gap all contributed to one reported symptom in practice — see #334/#335/#336). Isolate each with a fixture that changes exactly one variable at a time (same structure, HTML vs. Markdown; same structure, 2-space vs. 4-space indent; same structure, with vs. without a text-bearing parent) so each bug's evidence stands on its own.
+- **File tickets precisely, and check with the user before splitting one finding into several.** Reference exact file/line/grep evidence in the ticket body, distinguish "genuinely new, independently-fixable bug" from "sharper detail on an existing ticket," and don't unilaterally decide how many tickets a multi-bug investigation becomes — ask. Before filing, also check existing tickets for a pre-existing ask that already covers the same gap (`gh issue list --search "<keyword>"`) — a finding surfaced mid-investigation can turn out to already be one bullet of a broader ticket's existing "Ask" list.
+- **Check for TC-ID/fixture-name collisions against current `develop` before finalizing, not after a reviewer catches it.** Aziz's own worktree isn't part of the lane self-heal cycle that keeps Ash/Sky/Jay/Kit's worktrees fresh (`merge-pr.md` only resets those), so it can silently drift out of sync with concurrent dev-lane merges over the course of one investigation — a numbered test file like `docs/qa/tests/docs.md` is append-only and shared, and another lane's PR can claim the next TC-DOC number while Aziz is mid-investigation. Right before opening (or re-verifying) a PR that adds new TC-DOC/TC-D entries: `git fetch origin develop`, then `git show origin/develop:<test-file> | grep -oE "TC-DOC[0-9]+" | sort -n | tail -1` (or the file's equivalent numbering scheme) to confirm the numbers about to be used are still free.
+- **Own the PR-review iteration loop, not just the initial submission.** When a reviewer flags something like a TC-ID/fixture-naming collision against a `develop` that moved since the branch was cut: rebase, resolve conflicts by hand rather than blindly taking one side, renumber/rename consistently across every cross-reference, force-push with `--force-with-lease`, and reply on the PR stating exactly what changed.
+
 ## Retro
 
 Friction Aziz typically hits after a release pass, and where it goes — see `/retro` for the general ticket-vs-command-decision split:
@@ -23,4 +34,5 @@ Friction Aziz typically hits after a release pass, and where it goes — see `/r
 - **Release-scope audit surprises** — a merged PR turns out to lack adequate doc/test coverage, or a QA-tier call feels wrong in hindsight once results are in. If it's a gap in one already-merged feature, file a ticket. If it's the scoped-gating process itself (`docs/qa/runs/README.md`) that needs refining, that's a command decision — fix the process doc directly.
 - **Subagent-sharding friction** — a shard's instructions were ambiguous, or two shards' fixture ownership collided. Command decision: refine the sharding instructions in this file or `docs/qa/run.md`'s mutex section, don't just work around it silently next time.
 - **Bugs found during the compile step** are routine, not a retro item — route them to the responsible Dev lane per step 8 above.
+- **Ad-hoc deep-dive QA friction** — e.g. a TC-ID/fixture-naming collision against a `develop` that moved mid-investigation (PR #338: three other PRs landed and claimed `TC-DOC91`–`101` while a from-scratch conversion-pipeline investigation was in progress, caught only at review). Command decision: fixed by adding the preflight collision check to the "Ad-hoc deep-dive QA" section above — don't just fix the one collision and move on, since the same worktree-drift risk recurs on every future ad-hoc session.
 - **This role already has a heavier version of this pattern**: for a full regression run, Aziz writes `docs/qa/retro-vX.Y.Z.md` (see `retro-v0.8.0.md`) with its own "what went well / what didn't / action items" structure. Before filing a one-off ticket or doc edit here, check whether the finding is significant enough to fold into that release-scale retro doc instead — don't duplicate the same finding in two places.

{mcp_gee_sweet-0.8.2.dev55 → mcp_gee_sweet-0.8.2.dev63}/.claude/team-roles/qa.md

@@ -19,5 +19,9 @@ Friction QA (Sky/Kit) typically hits after a pass, and where it goes — see `/r
 - **Fixture drift/pollution** — the shared spreadsheet/doc accumulates stray objects (charts, temp sheets/rows, leftover permissions) from earlier test runs, breaking `docs/qa/setup.md`'s "Known fixture state" assumptions or blocking visual verification. If a specific test category is the source (e.g. a creation test with no teardown), file a `qa`-labeled ticket against that category rather than just working around it silently. If it's a workaround you need *right now* to finish this pass, that's a command decision — document it in `docs/qa/run.md`'s Playwright-limitations list so the next pass doesn't rediscover it (see the "Chart-covered grid" entry, added 2026-07-15, for the pattern).
 - **Playwright verification gaps** — an element is structurally unreachable or invisible to the browser tools (outside the viewport, canvas-rendered with no accessible geometry, obscured by other content). Command decision: add it to `run.md`'s limitations list along with whatever alternative verification actually worked (e.g. `get_sheet_data(..., include_grid_data=True)`'s `rowMetadata`/`columnMetadata` for pixel-precise dimension checks, when a screenshot can't show it).
 - **Test tag drift** — `⚠️ requires-oauth` or `**Playwright: required**` no longer matches a test case's actual behavior. Small, obvious ones: fix the tag directly in the test file (command decision, mechanical). Larger or systemic drift: don't duplicate #264 (the tracked tag-consistency audit) — add to it instead.
-- **Code-review findings that are minor or systemic rather than PR-blocking** — input-validation gaps, duplicated helpers, style inconsistencies that the new code merely repeats from an existing convention rather than introduces. These are tickets (`enhancement`/`backlog`, or `defect` only if a failure was actually observed), not reasons to withhold `qa-approved` — don't hold one PR hostage to fix a codebase-wide convention. See #323 for the shape this takes (validation + dedup findings from the same review, bundled into one issue since they shared a root cause).
+- **QA test-doc setup steps that don't match tool behavior** — e.g. a `**Setup:**` line telling you to use a tool that doesn't actually do what the step assumes (a "replace" tool cited where an "append" was meant). Fix the test-case text directly in `docs/qa/tests/*.md` as part of the same pass (command decision), not a ticket — it's QA process content, not product code.
+- **Code-review findings that are minor or systemic rather than PR-blocking** — input-validation gaps, duplicated helpers, style inconsistencies that the new code merely repeats from an existing convention rather than introduces. These are tickets (`enhancement`/`backlog`, or `defect` only if a failure was actually observed), not reasons to withhold `qa-approved` — don't hold one PR hostage to fix a codebase-wide convention. See #323 for the shape this takes (validation + dedup findings from the same review, bundled into one issue since they shared a root cause); see #329 for a comments-API-scoped example of the same pattern.
+- **Live-observed API quirks that aren't bugs** — e.g. a field the docstring implies is always populated but the live API omits for privacy/scope reasons on certain paths. Note it inline in the test case's `**Result**` entry (so the next run isn't surprised), but don't file a ticket unless the tool's own docstring is factually wrong about the contract — that's a documentation-label ticket instead.
+- **Lane/partner misidentification** — presenting the user a choice between PRs, or reviewing a PR, before confirming its branch's second segment actually matches this role's partner (this file's own `jq select` query above). If this happens, the fix is a command decision in this file or `verify-pr.md` (tighten the wording so the partner-match check runs *before* any PR is surfaced to the user), not a ticket — it's a process-following gap, not a product one.
+- **CI rollup false positives** — `statusCheckRollup` can omit a required check entirely (absent, not failing) while other checks (e.g. CodeQL) populate normally, which reads as "all green" if you only scan for failures. Command decision → `merge-pr.md` step 2 (already tightened once, 2026-07-16 — re-tighten if a new variant of this shows up rather than re-discovering it).
 - **Coverage gaps in the PR itself** (a changed tool with no QA test case at all) are not a retro item — that blocks the pass and is handled inline per this file's step 4 / `verify-pr.md` step 6, not deferred here.

{mcp_gee_sweet-0.8.2.dev55 → mcp_gee_sweet-0.8.2.dev63}/CLAUDE.md

@@ -39,7 +39,7 @@ Logic is split across `src/mcp_gee_sweet/`: `server.py` (MCP setup, tool decorat
 - `tools/drive/transfer.py` — upload/download/sync/export/revisions
 - `tools/drive/activity.py` — `list_file_activity` (Drive Activity API v2; requires `drive.activity.readonly` scope)
 - `tools/docs/` — Google Docs package; `__init__.py` is a thin dispatcher that delegates to four submodules:
-  - `docs/content.py` — helpers (`_html_to_text`, `_md_to_html`, `_to_doc_requests`, `_html_to_doc_requests`) and tools (`create_doc`, `get_doc_content`, `write_doc_content`, `create_doc_from_file`, `insert_doc_text`, `delete_doc_range`, `get_doc_structure`, `insert_inline_image`, `insert_page_break`)
+  - `docs/content.py` — helpers (`_html_to_text`, `_md_to_html`, `_to_doc_requests`, `_html_to_doc_requests`) and tools (`create_doc`, `get_doc_content`, `write_doc_content`, `create_doc_from_file`, `insert_doc_text`, `delete_doc_range`, `get_doc_structure`, `insert_inline_image`, `insert_page_break`, `create_named_range`, `create_bookmark`). The Docs API has no bookmark-creation endpoint — `create_bookmark` is a thin wrapper over `createNamedRange` spanning a single character; neither tool's output is a link target (only UI-created bookmarks/headings are)
   - `docs/tables.py` — tools (`insert_doc_table`, `insert_table_row`, `delete_table_row`, `insert_table_column`, `delete_table_column`, `merge_table_cells`)
   - `docs/style.py` — helpers (`_NAMED_STYLE_TYPES`, `_read_body_styles`, `_read_named_styles`, `_build_named_style_requests`) and tools (`style_doc_range`, `style_doc_table_cells`, `get_doc_theme`, `get_doc_named_styles`, `apply_theme`)
   - `docs/layout.py` — tools (`create_header`, `create_footer`)

{mcp_gee_sweet-0.8.2.dev55 → mcp_gee_sweet-0.8.2.dev63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-gee-sweet
-Version: 0.8.2.dev55
+Version: 0.8.2.dev63
 Summary: MCP server for Google Workspace — Sheets, Drive, Docs, and Calendar. 60+ tools for AI clients.
 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.8.2.dev55 → mcp_gee_sweet-0.8.2.dev63}/docs/configuration.md

@@ -70,7 +70,7 @@ Access logs are emitted at `INFO` level — they appear when `DEBUG_LEVEL` is `D
 
 <!-- Auto-generated by `scripts/gen_tool_docs.py` — do not edit by hand, your changes will be overwritten on the next commit. -->
 
-By default all 103 tools are registered. Use `ENABLED_TOOLS` (or `--include-tools` on the CLI) to restrict the server to exactly the tools you need. This reduces the AI's context window cost — each registered tool is a name the model must reason about on every call.
+By default all 108 tools are registered. Use `ENABLED_TOOLS` (or `--include-tools` on the CLI) to restrict the server to exactly the tools you need. This reduces the AI's context window cost — each registered tool is a name the model must reason about on every call.
 
 ```bash
 # Environment variable

mcp_gee_sweet-0.8.2.dev63/docs/qa/fixtures/tc-doc102-image-conversion.html

@@ -0,0 +1,44 @@
+<h1>Image Conversion Test Document (HTML)</h1>
+
+<h2>Case 1: standalone image in its own paragraph</h2>
+<p>Paragraph before the image.</p>
+<p><img src="https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png" alt="standalone logo" width="92" height="30"></p>
+<p>Paragraph after the image.</p>
+
+<h2>Case 2: inline image inside running text</h2>
+<p>Text before <img src="https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png" alt="inline logo"> text after, same paragraph.</p>
+
+<h2>Case 3: two consecutive images with no separating text</h2>
+<p><img src="https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png" alt="first"><img src="https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png" alt="second"></p>
+
+<h2>Case 4: image wrapped in a link</h2>
+<p><a href="https://example.com"><img src="https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png" alt="linked logo"></a></p>
+
+<h2>Case 5: image inside a list item</h2>
+<ul>
+  <li>List item with an image <img src="https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png" alt="bullet logo"> inline</li>
+  <li>Plain list item, no image</li>
+</ul>
+
+<h2>Case 6: image inside a table cell</h2>
+<table>
+  <tr><th>Description</th><th>Image</th></tr>
+  <tr><td>Logo in a cell</td><td><img src="https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png" alt="cell logo"></td></tr>
+</table>
+
+<h2>Case 7: image inside a nested table cell</h2>
+<table>
+  <tr>
+    <td>Outer cell with nested table</td>
+    <td>
+      <table>
+        <tr><td><img src="https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png" alt="nested cell logo"></td></tr>
+      </table>
+    </td>
+  </tr>
+</table>
+
+<h2>Case 8: image with an unreachable URL (parser-level drop, not a fetch failure)</h2>
+<p><img src="https://does-not-exist.invalid/nope.png" alt="unreachable image"></p>
+
+<p>Final paragraph, confirms the document is not truncated after all image cases.</p>

mcp_gee_sweet-0.8.2.dev63/docs/qa/fixtures/tc-doc103-image-conversion.md

@@ -0,0 +1,44 @@
+# Image Conversion Test Document (Markdown)
+
+## Case 1: standalone image in its own paragraph
+
+Paragraph before the image.
+
+![standalone logo](https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png)
+
+Paragraph after the image.
+
+## Case 2: inline image inside running text
+
+Text before ![inline logo](https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png) text after, same paragraph.
+
+## Case 3: two consecutive images with no separating text
+
+![first](https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png)![second](https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png)
+
+## Case 4: image wrapped in a link
+
+[![linked logo](https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png)](https://example.com)
+
+## Case 5: image inside a list item
+
+- List item with an image ![bullet logo](https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png) inline
+- Plain list item, no image
+
+## Case 6: image inside a table cell
+
+| Description | Image |
+|---|---|
+| Logo in a cell | ![cell logo](https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png) |
+
+## Case 7: reference-style image syntax
+
+Reference-style: ![ref logo][logoref]
+
+[logoref]: https://www.gstatic.com/images/branding/googlelogo/1x/googlelogo_color_92x30dp.png "Google logo"
+
+## Case 8: image with an unreachable URL (parser-level drop, not a fetch failure)
+
+![unreachable image](https://does-not-exist.invalid/nope.png)
+
+Final paragraph, confirms the document is not truncated after all image cases.

mcp_gee_sweet-0.8.2.dev63/docs/qa/fixtures/tc-doc104-nested-lists.html

@@ -0,0 +1,42 @@
+<h1>Nested List Structure Test (direct HTML)</h1>
+
+<h2>Case 1: parent item has its own text AND a nested sub-list</h2>
+<ul>
+  <li>Parent A has text
+    <ul>
+      <li>Child A1</li>
+      <li>Child A2
+        <ul>
+          <li>Grandchild A2a</li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li>Parent B has text
+    <ol>
+      <li>Ordered child B1</li>
+      <li>Ordered child B2</li>
+    </ol>
+  </li>
+</ul>
+
+<h2>Case 2: parent item has NO text of its own, just a nested list</h2>
+<ul>
+  <li>
+    <ul>
+      <li>Bare-nested child C1</li>
+      <li>Bare-nested child C2</li>
+    </ul>
+  </li>
+</ul>
+
+<h2>Case 3: ordered list nested inside ordered list</h2>
+<ol>
+  <li>Top ordered 1
+    <ol>
+      <li>Nested ordered 1.1</li>
+      <li>Nested ordered 1.2</li>
+    </ol>
+  </li>
+  <li>Top ordered 2</li>
+</ol>

mcp_gee_sweet-0.8.2.dev63/docs/qa/fixtures/tc-doc105-nested-lists-gfm.md

@@ -0,0 +1,24 @@
+# Nested List Structure Test (Markdown, GFM-standard indentation)
+
+## Case 1: parent item has its own text AND a nested sub-list
+
+- Parent A has text
+  - Child A1
+  - Child A2
+    - Grandchild A2a
+- Parent B has text
+  1. Ordered child B1
+  2. Ordered child B2
+
+## Case 2: parent item has NO text of its own, just a nested list
+
+-
+  - Bare-nested child C1
+  - Bare-nested child C2
+
+## Case 3: ordered list nested inside ordered list
+
+1. Top ordered 1
+   1. Nested ordered 1.1
+   2. Nested ordered 1.2
+2. Top ordered 2

mcp_gee_sweet-0.8.2.dev63/docs/qa/fixtures/tc-doc106-nested-lists-4space.md

@@ -0,0 +1,24 @@
+# Nested List Structure Test (Markdown, 4-space indentation)
+
+## Case 1: parent item has its own text AND a nested sub-list
+
+- Parent A has text
+    - Child A1
+    - Child A2
+        - Grandchild A2a
+- Parent B has text
+    1. Ordered child B1
+    2. Ordered child B2
+
+## Case 2: parent item has NO text of its own, just a nested list
+
+-
+    - Bare-nested child C1
+    - Bare-nested child C2
+
+## Case 3: ordered list nested inside ordered list
+
+1. Top ordered 1
+    1. Nested ordered 1.1
+    2. Nested ordered 1.2
+2. Top ordered 2

{mcp_gee_sweet-0.8.2.dev55 → mcp_gee_sweet-0.8.2.dev63}/docs/qa/run.md

@@ -36,7 +36,7 @@ When a test case is tagged `**Playwright: required**`, after the tool call the c
 
 - **Footer / header content** — Google Docs renders headers and footers outside the main document canvas. For short documents `window.scrollTo` does not bring the footer into the viewport. When a test involves `create_footer` or `create_header`, use the API response as confirmation; a Playwright snapshot of the body is still useful but will not show the footer content.
 - **Permission changes** — sharing confirmations are not visible in the Drive UI without navigating to the file's "Share" dialog. Use `list_permissions` API response as the confirmation source for share tests.
-- **Chart-covered grid (Sales sheet)** — repeated `add_chart` test runs leave floating chart objects on the Sales sheet (they're never cleaned up between runs), and as of 2026-07-15 there were ~12 stacked overlapping charts covering roughly rows 1–22. This blocks visual verification of anything in that region — row-height/column-width changes (`resize_rows`/`resize_columns`), cell formatting, etc. are not visible in a screenshot, and Playwright's accessibility snapshot doesn't expose per-cell grid geometry either (only the charts' own accessible text). When a test in that area needs precise confirmation, use `get_sheet_data(..., range=<affected range>, include_grid_data=True)` instead — the raw response includes `rowMetadata`/`columnMetadata` with each row/column's actual `pixelSize`, which is more precise than a screenshot anyway. Longer term, `add_chart` QA test cases should delete the chart they create at the end of each run (see `docs/qa/tests/sheets_charts.md`) so the fixture doesn't accumulate; that cleanup is not yet in place.
+- **Chart-covered grid (Sales sheet)** — repeated `add_chart` test runs leave floating chart objects on the Sales sheet (they're never cleaned up between runs), and as of 2026-07-15 there were ~12 stacked overlapping charts covering roughly rows 1–22. This blocks visual verification of anything in that region — row-height/column-width changes (`resize_rows`/`resize_columns`), cell formatting, etc. are not visible in a screenshot, and Playwright's accessibility snapshot doesn't expose per-cell grid geometry either (only the charts' own accessible text). When a test in that area needs precise confirmation, use `get_sheet_data(..., range=<affected range>, include_grid_data=True)` instead — the raw response includes `rowMetadata`/`columnMetadata` with each row/column's actual `pixelSize`, which is more precise than a screenshot anyway. The same call also works for border verification (`update_borders` QA, TC-S85–S87 on 2026-07-16): each cell's `userEnteredFormat.borders`/`effectiveFormat.borders` reports `top`/`bottom`/`left`/`right` style and color directly, so a border-covering-range test doesn't need the screenshot at all — check the per-cell `borders` dict instead of `rowMetadata`/`columnMetadata`. Longer term, `add_chart` QA test cases should delete the chart they create at the end of each run (see `docs/qa/tests/sheets_charts.md`) so the fixture doesn't accumulate; that cleanup is not yet in place.
 
 ### Coordinating Playwright across parallel shards
 

{mcp_gee_sweet-0.8.2.dev55 → mcp_gee_sweet-0.8.2.dev63}/docs/qa/tests/docs.md

@@ -1742,3 +1742,193 @@ Doc lacked the literal text "QA anchor target", so it was inserted via `insert_d
 
 **Result (2026-07-16) ✅ PASS**
 `list_doc_comments(doc_id="not-a-real-doc-id")` raised `HttpError 404 ... "File not found: not-a-real-doc-id."` — propagated cleanly, no silent empty list, no server crash.
+## HTML/Markdown → Doc image conversion (#332, #333)
+
+**Background:** `_AstParser` in `html_parser.py` has no `<img>` handling at all — `handle_starttag`/`handle_endtag` recognize block tags, inline formatting tags, table tags, and list tags, but an `img` tag matches none of those branches and is silently ignored. Since markdown images (`![alt](src)`) are converted to `<img>` HTML by `_md_to_html` before reaching this same parser, **every** content path that goes through the shared AST pipeline — `create_doc`, `create_doc_from_file`, `write_doc_content`, for both `content_format="html"` and `content_format="markdown"` — drops images with no error, no warning, and no placeholder. The only working path today is the separate `insert_inline_image` tool (TC-DOC57/58), which requires a second pass of index bookkeeping after the doc already exists (the manual workaround documented in #332/#333).
+
+This is worse than a simple drop in two cases, both verified directly against `html_to_ast` on the fixtures below:
+- A paragraph (or table cell) whose **only** content is an image produces **zero** AST nodes for it — not even an empty paragraph/cell. `ast_to_requests`'s guard `if not text.strip(): continue` (and the equivalent cell-fill guard in `emitter.py`) discards it entirely.
+- An inline image inside running text (`"before <img> after"`) leaves no gap, marker, or trace — the surrounding runs are simply concatenated (`"before "` + `" after"`), so a caller inspecting `get_doc_structure` afterward has no signal an image was ever present in the source.
+
+**Fixtures:** `docs/qa/fixtures/tc-doc102-image-conversion.html` and `docs/qa/fixtures/tc-doc103-image-conversion.md` — each covers 8 placement cases: standalone image paragraph, inline mid-paragraph, two consecutive images with no separating text, image wrapped in a link, image inside a list item, image inside a table cell, image inside a nested table cell (HTML only — markdown tables can't nest, matching the documented limitation in TC-DOC51; the markdown fixture substitutes reference-style `![alt][ref]` syntax for its Case 7 instead), and an image with an unreachable URL (included specifically to show the drop happens at parse time, before any HTTP fetch is attempted — a dead image URL fails identically to a live one).
+
+### TC-DOC102: HTML image conversion — every placement should produce a visible image ⚠️ requires-oauth ⚠️ destructive
+
+**Prompt**
+**Playwright: required**
+> "Create a Google Doc from the file <repo-root>/docs/qa/fixtures/tc-doc102-image-conversion.html"
+
+**Checks**
+- `docId` and `web_link` returned with no `error`
+- `get_doc_structure` shows all 8 headings and surrounding paragraph text intact
+- Each of the 8 cases produces an inline image element (`get_doc_structure` doesn't currently surface inline images explicitly — cross-check via element/paragraph text length matching an image occupying one index slot, as in TC-DOC57)
+- 🔍 Visual check in Google Docs: an image renders in each of the 8 cases, including inside the plain table cell and the nested table cell
+- Final paragraph after Case 8 is present (confirms the document isn't truncated)
+
+**Cleanup:** delete the created doc
+
+**Result (2026-07-16) ❌ FAIL — verified via direct code execution (`html_to_ast`), not yet run live against the Docs API.** Running the fixture through `html_to_ast` this session confirms every one of the 8 cases drops its image with zero trace:
+- Case 1 (standalone image paragraph): the paragraph containing only the image produces **no AST node at all** — not even an empty paragraph. `get_doc_structure` would show "Paragraph before the image." followed directly by "Paragraph after the image." with nothing between them.
+- Case 2 (inline mid-paragraph): AST paragraph text is `"Text before "` + `" text after, same paragraph."` — concatenated with no gap or marker.
+- Case 3 (two consecutive images, no text): produces **zero** AST nodes — the whole paragraph vanishes.
+- Case 4 (image wrapped in a link): produces **zero** AST nodes — same as Case 3, since the only content was the image.
+- Case 5 (image inside a list item): `BulletItem` text is `"List item with an image "` + `" inline"` — image silently gone, item otherwise intact.
+- Case 6 (image inside a table cell): cell `children` is `[]` — completely empty cell, no error.
+- Case 7 (image inside a nested table cell): the nested `Table` itself comes through correctly as a structural node, but its own single cell (containing only the image) is empty, same as Case 6.
+- Case 8 (unreachable URL): produces **zero** AST nodes, identically to Case 1/3/4 — confirms the drop happens at parse time regardless of URL validity.
+- Live execution + Playwright visual check still needed to confirm end-to-end behavior against the real API; not run this session (no live MCP tool access outside a release pass — see `.claude/team-roles/aziz.md`).
+
+---
+
+### TC-DOC103: Markdown image conversion shares the same drop as the HTML path ⚠️ requires-oauth ⚠️ destructive
+
+**Prompt**
+**Playwright: required**
+> "Create a Google Doc from the file <repo-root>/docs/qa/fixtures/tc-doc103-image-conversion.md"
+
+**Checks**
+- `docId` and `web_link` returned with no `error`
+- Same 8-case expectations as TC-DOC102 (Case 7 here is reference-style `![alt][ref]` syntax instead of a nested table)
+- 🔍 Visual check: images render in all 8 cases, including the reference-style image
+
+**Cleanup:** delete the created doc
+
+**Result (2026-07-16) ❌ FAIL — verified via direct code execution (`_md_to_html` → `html_to_ast`), not yet run live.** `_md_to_html` correctly converts every markdown image (inline, reference-style, link-wrapped) into an `<img>` tag first — confirmed by inspecting the intermediate HTML — so the markdown path funnels into the exact same unhandled-`img` gap as TC-DOC102. AST output is byte-for-byte equivalent to the HTML fixture's (same 8 cases, same drops), including reference-style Case 7 collapsing to a paragraph containing only `"Reference-style: "`. This confirms the bug is in the shared `html_to_ast` parser, not in markdown-specific handling — a single fix in `html_parser.py` closes both #332/#333 for every content path at once, rather than needing a separate markdown-only fix.
+
+---
+
+## HTML/Markdown → Doc nested list conversion (#334)
+
+**Background:** Three independent, compounding bugs, isolated separately below:
+
+1. **Parser data loss (`html_parser.py`, both HTML and Markdown paths):** `_AstParser.handle_starttag`'s block-tag branch (`if tag in _BLOCK_TAGS and self._table_depth == 0:`) unconditionally resets `self._run_buf`/`self._pending_runs` whenever ANY block tag opens — including a nested `<li>` opening inside an already-open outer `<li>`. There's no stack/save-restore of the outer block's in-progress buffer, so **the outer list item's own text is silently destroyed** whenever that item has both its own text and a nested sub-list (the extremely common `<li>Item text<ul>...</ul></li>` shape — e.g. any markdown of the form `- Item:\n  - sub\n  - sub`). This is data loss, not just a rendering/flattening issue: verified directly against `html_to_ast` — a source list with "Parent A has text" + 2 nested children produces only the 2 children in the AST; "Parent A has text" never appears anywhere.
+2. **Emitter ignores depth (`emitter.py`):** even where the parser *does* correctly track nesting (`BulletItem.depth`, verified correct in all cases below, including the ones unaffected by bug 1), `ast_to_requests` never reads `.depth` or `.paragraph_style` — `createParagraphBullets` is emitted with only `range` and `bulletPreset`, no indentation. Google Docs infers a bullet's nesting level from paragraph indentation, not an explicit field on the create request, so **every bullet renders at nesting level 0 in the live document regardless of source depth.** This is a real gap even for a list with zero parent-text collisions.
+3. **Markdown-specific, on top of 1+2:** python-markdown's `sane_lists` extension (used by `_md_to_html`) only recognizes a sub-list as nested when indented by exactly 4 spaces or a tab. The CommonMark/GFM-standard indentation that most people and tools (including Claude) write by default — 2 spaces under a `-`/`*` marker, 3 spaces under a `1.` marker — is silently flattened to the parent list **before it even reaches the HTML parser**, with no warning. Verified empirically this session (`uv run python3 -c "import markdown; ..."`) across four indentation widths.
+
+**Fixtures:** `docs/qa/fixtures/tc-doc104-nested-lists.html` (direct HTML, isolates bugs 1+2 with no markdown-library involvement), `docs/qa/fixtures/tc-doc105-nested-lists-gfm.md` (GFM-standard 2/3-space indentation, adds bug 3 on top), `docs/qa/fixtures/tc-doc106-nested-lists-4space.md` (4-space indentation — the documented python-markdown workaround — reproduces bugs 1+2 only, proving they're independent of bug 3). Each fixture has 3 cases: parent item with its own text + a nested sub-list (bug 1 trigger), a bare parent item with no text of its own (isolates bug 2 alone, since there's no parent text to lose), and ordered-in-ordered nesting.
+
+### TC-DOC104: Direct HTML nested lists — parent item text must survive when a sub-list follows it ⚠️ requires-oauth ⚠️ destructive
+
+**Prompt**
+**Playwright: required**
+> "Write this HTML to doc {DOC_ID}: contents of docs/qa/fixtures/tc-doc104-nested-lists.html"
+
+**Checks**
+- `get_doc_structure` shows "Parent A has text" and "Parent B has text" as their own bullet items, each followed by their nested children
+- Case 2's bare-nested children ("Bare-nested child C1"/"C2") appear at a visibly deeper indentation than Case 2's (absent) parent
+- Case 3's "Top ordered 1" survives as its own item, with "Nested ordered 1.1"/"1.2" indented under it
+- 🔍 Visual check in Google Docs: 3 distinct indentation levels are visible in Case 1 (Parent A / Child A2 / Grandchild A2a), and Case 2/3's nesting is visually indented, not flush-left
+
+**Cleanup:** write fixture content back
+
+**Result (2026-07-16) ❌ FAIL — verified via direct code execution (`html_to_ast`), not yet run live.** Confirmed exactly the predicted content loss: "Parent A has text" and "Parent B has text" (Case 1) and "Top ordered 1" (Case 3) — every parent item that has both its own text and a nested sub-list — produce **zero** `BulletItem`s; only their children survive, at depths 1/2 computed correctly. Case 2 (bare parent, no text to lose) correctly preserves both children at `depth=1` — this isolates bug 2 cleanly: depth is tracked right, but since `ast_to_requests` never emits it (confirmed by `grep -n "depth\|indentStart\|nestingLevel" emitter.py` returning zero matches in the relevant code), even these correctly-tracked items would still render at nesting level 0 in the live doc. Live execution + Playwright visual check still needed to confirm the live-rendering half of bug 2 (indentation is not exposed by `get_doc_structure` today — a related tooling gap, see note below).
+
+---
+
+### TC-DOC105: Markdown nested lists at GFM-standard (2/3-space) indentation ⚠️ requires-oauth ⚠️ destructive
+
+**Prompt**
+**Playwright: required**
+> "Write this markdown to doc {DOC_ID} using content_format='markdown': contents of docs/qa/fixtures/tc-doc105-nested-lists-gfm.md"
+
+**Checks**
+- Same nesting expectations as TC-DOC104 (this is the indentation width most humans/AI tools write by default — it should behave the same as explicit HTML nesting)
+- No literal `1.`/`2.` digit-dot text visible anywhere in bullet content
+
+**Cleanup:** write fixture content back
+
+**Result (2026-07-16) ❌ FAIL — verified via direct code execution (`_md_to_html`), not yet run live.** This is worse than TC-DOC104, not merely equivalent: 2-space indentation doesn't clear `sane_lists`' 4-space nesting threshold, so the sub-list syntax is never recognized as a list at all.
+- Case 1: "Child A1" and "Child A2" become **sibling** bullets of "Parent A has text" (fully flattened, not nested) — while "Parent B has text" ends up with the literal text `"Parent B has text\n  1. Ordered child B1\n  2. Ordered child B2"` glued into ONE bullet item, i.e. the ordered sub-items render as raw, visible `1.`/`2.` characters in the doc rather than as list items or even flattened siblings — a strictly worse failure mode a user would see as garbled text, not just missing indentation.
+- Case 2: a bare `-` marker with nothing else on its line, followed by an indented sub-list, isn't recognized as a list item at all by `sane_lists` — the whole block degrades to a single plain paragraph containing the literal source text (`"-\n  - Bare-nested child C1\n  - Bare-nested child C2"`).
+- Case 3: "Top ordered 1" survives as its own item (no bug-1 collision at this indentation, since the sub-items aren't recognized as nested — they become plain siblings instead), but "Nested ordered 1.1"/"1.2" render as flat siblings, not nested, and are mis-numbered as continuing the same list as "Top ordered 1"/"2" in the live doc.
+- Live execution + Playwright visual check still needed; not run this session.
+
+---
+
+### TC-DOC106: Markdown nested lists at 4-space indentation — isolates bugs 1+2 from bug 3 ⚠️ requires-oauth ⚠️ destructive
+
+**Prompt**
+**Playwright: required**
+> "Write this markdown to doc {DOC_ID} using content_format='markdown': contents of docs/qa/fixtures/tc-doc106-nested-lists-4space.md"
+
+**Checks**
+- Same nesting expectations as TC-DOC104 — 4-space indentation is the one width where `_md_to_html` produces genuinely nested `<ul>`/`<ol>` HTML, so this TC should behave identically to TC-DOC104 once bugs 1+2 are fixed
+- Confirms whether a "use 4 spaces" workaround note in tool docstrings would be sufficient today (it would not — bugs 1+2 still apply at this indentation)
+
+**Cleanup:** write fixture content back
+
+**Result (2026-07-16) ❌ FAIL — verified via direct code execution (`_md_to_html` → `html_to_ast`), not yet run live.** At 4-space indentation, `_md_to_html` produces properly nested `<ul>`/`<ol>` HTML (confirmed by inspecting the intermediate HTML output), so this fixture reproduces TC-DOC104's HTML-path results exactly: "Parent A has text"/"Parent B has text"/"Top ordered 1" all lost to bug 1, correct `depth` values (1, 2) on the surviving children, Case 2's bare-parent children correctly preserved at `depth=1`. This confirms bugs 1+2 are independent of the markdown-library indentation quirk (bug 3) — fixing `_md_to_html`'s indentation sensitivity alone would not fix nested lists; `html_parser.py` and `emitter.py` both need fixing regardless of indentation width used.
+
+---
+
+**Tooling gap note (not a fix, just a QA-visibility limitation):** `get_doc_structure` doesn't currently expose paragraph indentation or the Docs API's bullet `nestingLevel` field, so confirming bug 2's live-rendering half (or a future fix for it) requires a Playwright visual check every time rather than a structural assertion. Worth a follow-up ticket if this bug is fixed — the same way `font_family` is already a known `get_doc_structure` gap (TC-DOC42/47).
+
+---
+
+## `create_named_range` / `create_bookmark` (#152)
+
+The Docs API has no dedicated bookmark-creation endpoint — `create_bookmark` is implemented as a thin wrapper over `createNamedRange` spanning a single character. Neither tool's output is visible anywhere in the Docs UI (named ranges aren't a UI-surfaced concept), so verification is API-round-trip only, except TC-DOC109 which specifically checks the UI does *not* show the bookmark, to confirm the docstring's caveat is accurate.
+
+### TC-DOC107: `create_named_range` creates a named range over a span ⚠️ destructive
+**Setup:** create a doc with a paragraph of text; call `get_doc_structure` to get its `startIndex`/`endIndex`
+
+**Prompt**
+> "Create a named range called 'section-a' spanning indices {N} to {M} in doc {DOC_ID}"
+
+**Checks**
+- Call succeeds with no API error
+- Response contains `docId`, a non-empty string `namedRangeId`, `name: "section-a"`, `startIndex: N`, `endIndex: M`
+
+**Cleanup:** delete the created doc
+
+**Result (2026-07-17) ✅ PASS**
+`create_named_range(doc_id, name="section-a", start_index=1, end_index=64)` against a doc with one paragraph of real text returned `{"docId": ..., "namedRangeId": "kix.kmeha3539w3s", "name": "section-a", "startIndex": 1, "endIndex": 64}` — all fields present and correct. Note: `create_doc`'s `content` param and a plain-text (no wrapping tag) call to `write_doc_content` both silently produced an empty document body (confirmed live via Playwright screenshot) — wrapping the same text in `<p>...</p>` via `write_doc_content` worked. This is unrelated to `create_named_range`/`create_bookmark` (not touched by this PR) but is a real, reproducible bug in the existing HTML content pipeline; flagging separately, not blocking this PR.
+
+---
+
+### TC-DOC108: `create_named_range` — API error returned gracefully (end_index beyond document end)
+**Prompt**
+> "Create a named range called 'bad' spanning indices 1 to 99999 in doc {DOC_ID}"
+
+**Checks**
+- Returns `{"error": "..."}` — does not raise an exception
+- Error message references an API failure (index out of bounds)
+
+**Cleanup:** none (no mutation applied)
+
+**Result (2026-07-17) ✅ PASS**
+Returned `{"error": "<HttpError 400 ... Index 99998 must be less than the end index of the referenced segment, 65.>"}` — clean error dict, no exception, references index out of bounds.
+
+---
+
+### TC-DOC109: `create_bookmark` creates a single-character named range anchor ⚠️ destructive
+**Setup:** create a doc with a paragraph of text; call `get_doc_structure` to get a valid index `N` within it
+
+**Prompt**
+**Playwright: required**
+> "Create a bookmark called 'intro' at index {N} in doc {DOC_ID}"
+
+**Checks**
+- Call succeeds with no API error
+- Response contains `docId`, a non-empty string `namedRangeId`, `name: "intro"`, `index: N`
+- 🔍 Visual check in Google Docs: Insert > Link, then click the "Headings, bookmarks, and tabs" button in the link dialog — the resulting list does **not** include "intro" — confirms this is a named-range-backed anchor, not a native Docs UI bookmark (documented limitation)
+
+**Cleanup:** delete the created doc
+
+**Result (2026-07-17) ✅ PASS**
+`create_bookmark(doc_id, name="intro", index=1)` returned `{"docId": ..., "namedRangeId": "kix.jare8zg6gej", "name": "intro", "index": 1}`. Playwright: Insert > Link > "Headings, bookmarks, and tabs" listed only "Tab 1" — "intro" does not appear, confirming the documented limitation (not a native Docs UI bookmark).
+
+---
+
+### TC-DOC110: `create_bookmark` — API error returned gracefully (index beyond document end)
+**Prompt**
+> "Create a bookmark called 'bad' at index 99999 in doc {DOC_ID}"
+
+**Checks**
+- Returns `{"error": "..."}` — does not raise an exception
+- Error message references an API failure (index out of bounds)
+
+**Cleanup:** none (no mutation applied)
+
+**Result (2026-07-17) ✅ PASS**
+Returned `{"error": "<HttpError 400 ... Index 99999 must be less than the end index of the referenced segment, 65.>"}` — clean error dict, no exception, references index out of bounds.

{mcp_gee_sweet-0.8.2.dev55 → mcp_gee_sweet-0.8.2.dev63}/docs/roadmap.md

@@ -121,7 +121,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 **Docs**
 - [x] `insert_page_break` — explicit page break at an index ([#148](https://github.com/khuisman/mcp-gee-sweet/issues/148)) (PR #314)
 - [x] `merge_table_cells` — merge cells in an existing table (distinct from write-time colspan) ([#150](https://github.com/khuisman/mcp-gee-sweet/issues/150)) (PR #310)
-- [ ] Comments API — list, add, resolve doc comments ([#151](https://github.com/khuisman/mcp-gee-sweet/issues/151))
+- [x] Comments API — list, add, resolve doc comments (PR #324) ([#151](https://github.com/khuisman/mcp-gee-sweet/issues/151))
 - [ ] `create_named_range` / `create_bookmark` — anchor points for internal links ([#152](https://github.com/khuisman/mcp-gee-sweet/issues/152))
 - [x] Rowspan emitter — closed as duplicate, already implemented via #100 (rowspan support) and PR #287 (nested-table colspan/rowspan) ([#195](https://github.com/khuisman/mcp-gee-sweet/issues/195))
 - [x] Warn/error on mixed text + nested table in same cell — shipped as the fuller `Cell.children: list[Run | Table]` ordered model, also fixing trailing-text-after-nested-table ordering ([#275](https://github.com/khuisman/mcp-gee-sweet/issues/275)) in the same PR (PR #276) ([#108](https://github.com/khuisman/mcp-gee-sweet/issues/108))

{mcp_gee_sweet-0.8.2.dev55 → mcp_gee_sweet-0.8.2.dev63}/docs/tools.md

@@ -2,7 +2,7 @@
 
 <!-- Auto-generated by `scripts/gen_tool_docs.py` — do not edit by hand, your changes will be overwritten on the next commit. -->
 
-103 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
+108 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
 
 ## Sheets — data
 
@@ -127,6 +127,8 @@ Requires the `drive.activity.readonly` scope; uses the Drive Activity API v2.
 | `get_doc_structure` | Return the full structural map of a Google Doc body with element indices. | `doc_id` |
 | `insert_doc_text` | Insert text at one or more positions in a Google Doc. | `doc_id`, `insertions` |
 | `delete_doc_range` | Delete one or more content ranges from a Google Doc. | `doc_id`, `deletions` |
+| `create_named_range` | Create a named range over a span of content in a Google Doc. | `doc_id`, `name`, `start_index`, `end_index` |
+| `create_bookmark` | Create a lightweight, named anchor point at a single position in a Google Doc. | `doc_id`, `name`, `index` |
 | `insert_inline_image` | Insert an inline image at a specific index in a Google Doc. | `doc_id`, `index`, `uri?`, `drive_file_id?`, `width?`, `height?` |
 | `insert_page_break` | Insert an explicit page break at a specific index in a Google Doc. | `doc_id`, `index` |
 | `insert_doc_table` | Insert an empty table at a specific position in a Google Doc. | `doc_id`, `index`, `rows`, `columns` |