@qvac/skills 0.1.10 → 0.1.12

package/skills/word/references/rework.md

@@ -1,767 +0,0 @@
-# Reworking an Existing Word Document (python-docx)
-
-Change, replace, extend, trim, or rework a `.docx` that is already in this
-chat by running Python through the `exec` tool: stage it as an input, modify
-paragraphs and tables, and save a **new** output such as
-`existing_revised.docx`. Never overwrite the staged input.
-
-## Replacing Some Facts, Points, Bullets or Paragraphs: Two Script Calls
-
-"Replace the first 10 facts", "change fact 3", "swap these bullets for those",
-"reword paragraph 7" — any request that changes some of the paragraphs and
-keeps the rest — is two `exec` calls that run scripts bundled with this skill.
-**Write no Python for it.** Nothing else in this file applies to that job: no
-`command`, no `Document(...)`, no fingerprint, no loop. `references/paragraphs.md`
-is this same recipe with its error table.
-
-The document's `attachmentId` is already in the chat — in the `attachments` of
-the `exec` result that produced it, or on the user's `[Attached file …]` line.
-Copy it into `inputs`; an entry with only a `path` stages an image, not a
-document.
-
-Step 1 — list the paragraphs (no `outputs`):
-
-```json
-{
-  "language": "python",
-  "packages": ["python-docx==1.2.0"],
-  "inputs": [{ "attachmentId": "<real id>", "path": "existing.docx" }],
-  "skill": "word",
-  "script": "scripts/list_paragraphs.py",
-  "scriptArgs": ["existing.docx"]
-}
-```
-
-It prints one line per paragraph — `index`, style, text — then a count line.
-Only body paragraphs (`Normal`, `List Bullet`, `List Number`) are facts, points,
-or bullets; `Title`, `Heading N`, and an intro sentence are never counted as
-one. "The first 10 facts" = the first 10 body-paragraph indexes after the
-heading or sentence that introduces them — not indexes 0–9.
-
-Step 2 — replace exactly those paragraphs (one `outputs` entry). `scriptArgs`
-is the input name, the output name, then one `index, new text` pair per
-replaced paragraph — "the first 10 facts" is 10 pairs, each a different
-complete sentence:
-
-```json
-{
-  "language": "python",
-  "packages": ["python-docx==1.2.0"],
-  "inputs": [{ "attachmentId": "<real id>", "path": "existing.docx" }],
-  "outputs": ["existing_revised.docx"],
-  "skill": "word",
-  "script": "scripts/replace_paragraphs.py",
-  "scriptArgs": [
-    "existing.docx", "existing_revised.docx",
-    "3", "Dogs have about 1,700 taste buds.",
-    "4", "A dog's nose print is unique, like a fingerprint."
-  ]
-}
-```
-
-Wrong, for this job — a `command` instead of a `script`:
-
-```json
-{ "command": "from docx import Document\ndoc = Document(\"existing.docx\")\nfor i in range(1, 11): ..." }
-```
-
-`exitCode 0` plus an attachment = done: reply with the file name and the
-printed `K of N paragraphs replaced`, and do not call `exec` again. A script
-error names the fix (a heading index, an index out of range, unchanged text,
-missing pairs, a missing `outputs` for the revised name); correct the
-arguments and rerun the **same script**.
-
-Everything below is for the other edits: extending a document, trimming it,
-rewriting a whole section, resizing its text, embedding an image.
-
-## Staging the Document
-
-Stage the document as an input **by its `attachmentId`** and open it with
-`Document("existing.docx")`. The id comes from wherever the document entered
-the chat:
-
-- **Produced earlier in this chat** — the `attachmentId` is in that `exec` result.
-- **Uploaded by the user** — the `[Attached file …]` line on their message names
-  it, when the message carries one:
-
-  ```
-  [Attached file "report.docx" (application/vnd.openxmlformats-officedocument.wordprocessingml.document) — attachmentId: 4f9c2ab1]
-  ```
-
-Copy the id verbatim — never placeholders like `att_doc`, `att_image`, or any
-id you made up. A `.docx` is **never** staged id-less: an id-less input
-resolves to an uploaded _image_, so it can never reach a document. If no
-`attachmentId` for the document appears anywhere in the chat, say you cannot
-open that file for editing and ask the user to attach it again — do not invent
-an id, do not stage it id-less, and do not retry. An attachment from an
-earlier turn can be used when its attachment id is available in the
-conversation.
-
-**The file only exists if this same `exec` call stages it.** The working
-directory starts empty on every call, so an edit needs an `inputs` entry
-naming the attachment, and `Document("existing.docx")` must use that entry's
-exact `path`. Opening a name that was never staged raises
-`PackageNotFoundError: Package not found at '…'` — the fix is the missing
-`inputs`, never a different file name.
-
-## The exec call
-
-Images can be staged alongside the document. Tool-produced images
-(`generate_image` output) take the exact `attachmentId` from the tool result;
-an image the user uploaded is staged with `path` only and **no
-`attachmentId` key** — the first id-less entry is the first image of the
-user's latest message, and so on. Id-less entries resolve _images only_.
-
-```json
-{
-  "language": "python",
-  "packages": ["python-docx==1.2.0"],
-  "inputs": [
-    {
-      "attachmentId": "<id from the exec result or the [Attached file …] line>",
-      "path": "existing.docx"
-    },
-    { "path": "photo.png" }
-  ],
-  "outputs": ["existing_revised.docx"],
-  "command": "..."
-}
-```
-
-- `packages` — `["python-docx==1.2.0"]` on every call. The PyPI package is
-  `python-docx` but the import is `docx`; never list `docx` as the package —
-  that resolves a different, abandoned library. Pin the version; this exact
-  version ships with the app and installs with no network; any other version
-  has to be downloaded, which fails on a device that is offline.
-- `inputs` — staged files land in the working directory under the bare `path`
-  names — reference `Document("existing.docx")` /
-  `doc.add_picture("photo.png", …)` by that name only. Paths must be unique
-  bare filenames.
-- `outputs` — the new file to deliver; a file you write but do not declare
-  here is discarded. Never the staged input's name. **Name it after the
-  document you edited**, not after the change: keep the input's stem and add a
-  marker — `report.docx` edited is `report_revised.docx`. A fresh name picked
-  from the new content (`cats.docx` for an edit of `parrot_facts.docx`) reads
-  as a second, unrelated document and hides the fact that an edit happened at
-  all.
-- `command` — the multi-line Python source, with real newline characters.
-  Never collapse it to one line joined by `;` — a `for`/`if`/`with` after a
-  semicolon is a `SyntaxError`. There is no shell and no installer — packages
-  are declared in `packages`.
-
-If the image was staged in `inputs`, embed it in **that** single build with
-`doc.add_picture("photo.png", width=Inches(5.5))` — never deliver a document
-and then rebuild to add the image. **Do not soft-fail images or imports**:
-never wrap `add_picture` or an import in `try`/`except` that prints a warning
-and continues — a document saved without the requested image is a failed
-turn, not a success. Pass only one of `width`/`height`; passing both distorts
-the picture.
-
-**Image URLs do not work — never download.** Your Python code has **no
-network access**: `requests`, `urllib`, and `socket` all fail with a network
-error, and `http_request` returns truncated text, never image bytes. Say the
-link cannot be downloaded and ask the user to attach the image itself, or
-offer `generate_image` for a similar visual.
-
-## Editing: Work the Objects, Save a New Name
-
-One call does the whole edit: open, change, verify the document actually
-changed, save. Keep the fingerprint lines exactly as written — they are what
-stops an edit that silently matched nothing (or a read that only inspected)
-from delivering an unchanged copy of the user's document at `exitCode 0`. The
-fingerprint covers the body **and** the styles part, so a style-only change —
-the resize recipe below — counts as a change too:
-
-```python
-import hashlib
-from docx import Document
-
-doc = Document("existing.docx")
-fingerprint = hashlib.md5((doc.element.xml + doc.styles.element.xml).encode()).hexdigest()
-
-for paragraph in doc.paragraphs:
-    if paragraph.text == "Prepared by the finance team.":
-        paragraph.text = "Prepared by the finance team. Revised after board review."
-
-table = doc.tables[0]
-row = table.add_row().cells
-row[0].text = "Margin"
-row[1].text = "25%"
-row[2].text = "36%"
-
-doc.add_heading("Appendix", level=1)
-doc.add_paragraph("Margins recovered as one-off costs rolled out of the base.")
-
-assert (
-    hashlib.md5((doc.element.xml + doc.styles.element.xml).encode()).hexdigest() != fingerprint
-), "nothing changed — the edit matched nothing or never ran; fix it, never deliver an unchanged copy"
-doc.save("existing_revised.docx")     # a NEW name — never the staged input
-print(f"{len(doc.paragraphs)} paragraphs, {len(doc.tables)} table(s)")
-```
-
-**An assert that fires is a failed turn to diagnose, not a document to
-deliver**: the usual cause is a paragraph match on text that is not exactly
-there — print the real `.text` values in the rerun, fix the match, and never
-delete the assert to get a file out.
-
-**Keep it an `assert`, never a `print` or an `if`.** Two `print` lines showing
-the old and new hashes let a no-op save and deliver anyway, which is the one
-thing the assert exists to stop. They also invite a second miscoding: taking
-both hashes together, before the change. Then they match whatever the edit did,
-and the run reports "nothing changed" over a document that changed correctly.
-Take the second hash after the last mutation and before `save`, and let the
-assert raise.
-
-**A printed line is never a reason to call `exec` again.** The guard is the
-assert: if it did not fire and the result carries an attachment, the document is
-delivered and the turn is over, whatever stdout says about it. Re-running to
-check saves the same edit under a second name, and the user gets two documents
-for one request.
-
-`doc.paragraphs` walks only the document body — text inside tables, headers, and
-footers is **not** in it. Table text is reached through `doc.tables`; match
-paragraphs by their exact `.text` before rewriting them, and remember the
-formatting-loss rule below.
-
-The `add_heading`/`add_paragraph` pair above appends an **Appendix** because
-that is what the sample edit asks for. Copy that shape only when the user
-genuinely wants new content at the end. Substituting content that is already
-in the document is a different job with its own guards: some of the points —
-"change the first five points" — is the two script calls at the top of this
-file; a whole section — "rewrite section 2" — is Rewriting Whole Sections.
-
-When an edit adds substantial new content — new sections, formatted runs,
-bulleted lists, whole tables — the writing rules apply unchanged: load
-`references/create.md` too and copy its shapes (no markdown characters in
-strings, bold/italic on runs never paragraphs, one string per `add_paragraph`,
-tables built from a header row with `rows=1`).
-
-### Setting `paragraph.text` erases formatting
-
-Assigning `paragraph.text = "…"` replaces **all** runs with one plain run: every
-bold, italic, size, and color in that paragraph is gone. Fine for plain
-paragraphs; on a formatted paragraph edit the runs instead, or accept the loss
-deliberately. This is the top footgun when editing an uploaded document.
-
-### Styles must exist in the document
-
-`style="List Bullet"` names a style **inside the document**. A missing name
-raises `KeyError: "no style with name 'List Bullet'"` at `add_paragraph` time.
-An **uploaded** document carries only its own styles — one written by another
-tool may lack even `List Bullet`. When editing, guard once and fall back:
-
-```python
-names = [s.name for s in doc.styles]
-bullet = "List Bullet" if "List Bullet" in names else None
-doc.add_paragraph("point one", style=bullet)   # style=None → Normal
-```
-
-## Rewriting Whole Sections
-
-This recipe is for whole _sections_ (a heading plus its body). Changing some
-of the facts, points, bullets, or paragraphs is the two script calls at the
-top of this file — never hand-write a loop for that.
-
-`add_paragraph`, `add_heading`, and `add_picture` **always append at the end of
-the document.** None of them takes a position. "Change the first five points",
-"rewrite section 2", "swap these facts for those" are all *replacements*, and
-reaching for `add_*` silently turns them into an append: the original content
-stays where it is, the new content lands after the closing line, and the
-document comes back longer than it started with both versions in it. That is a
-failed turn, not a partial success — it is the most common way this skill goes
-wrong.
-
-**A section is a heading plus everything under it, up to the next heading of
-the same or higher rank** — which may be one paragraph, or six bullets, or a
-whole subsection, or nothing at all. Never assume it is exactly one paragraph:
-rewriting the heading and the single paragraph after it leaves the rest of the
-old section sitting under its new title, which is the same contradiction an
-append produces and is just as invisible in the result. Work out where each
-section ends before changing anything.
-
-Rank matters as much as position. `Heading 2` under a `Heading 1` is a
-subsection, not the next section, so "replace the first two sections" on a
-document with subheadings must not consume the parent's own subheading as
-section two — the same rule the removal recipe below follows. `rank()` reads
-the level off the style name, and only the shallowest rank counts as a section
-start.
-
-**A heading shallower than every other heading is the document's title, not its
-first section.** A document headed `Heading 1` and sectioned `Heading 2` — the
-shape most attached documents have — would otherwise have exactly one
-"section": the title, spanning everything under it. Replacing that section
-replaces the entire document, and nothing about the result says so. The `if`
-drops such a heading before sections are picked, and the whole-document assert
-refuses the span even if one is somehow selected.
-
-**One heading is dropped, never a chain of them.** It is an `if`, not a
-`while`: a document is titled once. Stripping repeatedly walks down the
-outline — on a `Heading 1` title over a `Heading 2` phase holding `Heading 3`
-weeks it drops the title, then the phase, and the weeks become the "sections",
-so replacing the first two rewrites the weeks and leaves the phase untouched.
-That is the silent wrong target this section exists to prevent. Stopping after
-one leaves the phase as the only section, and asking for a second raises an
-error that says so.
-
-Take one snapshot of `doc.paragraphs` and index into it. **Every string in
-`NEW` is a placeholder** — the sample fills it with report sections so the
-shape is readable, and you replace all of it with the content this request asks
-for. Shipping a sample string in the user's document is a failed turn:
-
-```python
-from docx import Document
-
-doc = Document("existing.docx")
-paras = doc.paragraphs                  # one snapshot — index into THIS list
-blocks = list(doc.element.body)         # paragraphs AND tables, in document order
-
-NEW = [                                 # placeholders — you write every string here
-    ("Regional Performance", "Revenue grew in every region except EMEA, where the quarter closed flat."),
-    ("Cost Base", "Headcount costs fell as the contractor pool wound down, and the saving held."),
-]
-TARGET = range(len(NEW))                # which sections to replace — here the first len(NEW)
-
-def rank(paragraph):                    # "Heading 2" -> 2; a bare "Heading" is rank 1
-    tail = paragraph.style.name.split()[-1]
-    return int(tail) if tail.isdigit() else 1
-
-heads = [i for i, p in enumerate(paras) if p.style.name.startswith("Heading")]
-if len(heads) > 1 and all(rank(paras[heads[0]]) < rank(paras[i]) for i in heads[1:]):
-    heads = heads[1:]                   # a lone heading above all the rest is the title
-top = min((rank(paras[i]) for i in heads), default=1)
-starts = [i for i in heads if rank(paras[i]) == top]     # sections, never their subsections
-ends = [next((j for j in heads if j > i and rank(paras[j]) <= top), len(paras)) for i in starts]
-
-assert NEW, "NEW is empty — write the replacement content before running the edit"
-assert len(TARGET) == len(NEW), f"TARGET names {len(TARGET)} sections but NEW has {len(NEW)} items"
-assert len(starts) > max(TARGET), f"TARGET reaches section {max(TARGET) + 1}, but the document has {len(starts)}"
-at = [blocks.index(p._element) for p in paras]           # where each paragraph sits among the blocks
-for k in TARGET:
-    assert ends[k] > starts[k] + 1, f"section {paras[starts[k]].text!r} has no body paragraph to replace"
-    assert (starts[k], ends[k]) != (heads[0], len(paras)), f"section {paras[starts[k]].text!r} spans the whole document — that is a rewrite, not a section replacement"
-    span = blocks[at[starts[k]] : at[ends[k]] if ends[k] < len(paras) else len(blocks)]
-    assert not any(el.tag.endswith("}tbl") for el in span), f"section {paras[starts[k]].text!r} holds a table — this recipe replaces paragraphs only"
-
-# measured from the document, before anything changes — never from what the loop below does
-before = len(paras)
-old_body = [p.text for k in TARGET for p in paras[starts[k] + 1 : ends[k]]]
-doomed = [(p.text, p._element) for k in TARGET for p in paras[starts[k] + 2 : ends[k]]]
-expected = before - len(old_body) + len(NEW)   # each replaced section keeps exactly one body paragraph
-
-for k, (title, body) in zip(TARGET, NEW):
-    paras[starts[k]].text = title       # the heading keeps its own style
-    paras[starts[k] + 1].text = body
-    paras[starts[k] + 1].style = doc.styles["Normal"]    # the reused paragraph may have been a bullet
-    for p in paras[starts[k] + 2 : ends[k]]:             # whatever else the section held
-        p._element.getparent().remove(p._element)
-
-assert len(doc.paragraphs) == expected, f"expected {expected} paragraphs, got {len(doc.paragraphs)} — an old section was not fully replaced, or content was appended"
-for text, el in doomed:
-    assert el.getparent() is None, f"an old paragraph is still in the document: {text[:40]!r}"
-doc.save("existing_revised.docx")       # a NEW name — never the staged input
-print(f"{len(NEW)} of {len(starts)} sections replaced, {before} -> {len(doc.paragraphs)} paragraphs")
-```
-
-`TARGET` names the sections to replace, once, and `zip` pairs each new item with
-the section it overwrites. Replacing a different range is a change to that one
-line — `TARGET = range(2, 5)` for "sections 3 through 5", with three items in
-`NEW` to match. Keep it bound in a single place: a range written twice drifts
-apart the moment one copy is edited, and every guard below reads `TARGET`
-rather than assuming the range starts at zero.
-
-Assigning `paras[head].text` keeps that paragraph's style, because the style
-lives on the paragraph and not on its runs: a `Heading 2` stays a `Heading 2`.
-Only the run-level formatting inside it is lost, per the rule above. The body
-paragraph is the opposite case — it is reused, so it arrives carrying whatever
-style the old body had, which is why the sample sets it back to `Normal`. Set it
-to something else when the new body should be a bullet or a quote, and guard the
-name as shown under Styles.
-
-**Keep the document's own numbering.** The sample titles carry no `1.`, `2.`
-prefix because the document it edits does not number itself, and a typed prefix
-on a `List Number` paragraph double-numbers. When the headings you are
-overwriting *do* carry manual numbers, take each number from the position being
-overwritten so the sequence continues — replacing sections 3 through 5 writes
-`3.`, `4.`, `5.`, never restarting at `1.`
-
-**Every assert, exactly as written — and measured before the loop runs.**
-`old_body` and `expected` come from the document's own structure, never from
-what the loop reports about itself. That is the whole point: a loop that
-rewrites only the paragraph after each heading, the mistake this recipe exists
-to prevent, would tally its own work as complete. Derived up front, the numbers
-contradict it. None of these failures is distinguishable from success by
-`exitCode 0` plus an attachment:
-
-- **`assert NEW`** catches an empty content list. Without it `max(TARGET)`
-  raises a bare `ValueError`, and were it not for that the run would save an
-  untouched copy of the user's document at `exitCode 0`.
-- **`len(TARGET) == len(NEW)`** catches a target range and a content list that
-  drifted apart. `zip` would silently pair only the shorter of the two.
-- **`len(starts) > max(TARGET)`** catches a range reaching past the last
-  section. It reads `TARGET`, not `len(NEW)`, because the range need not start
-  at zero — a `len(NEW)` check passes on `range(2, 5)` over four sections and
-  the run then dies on an `IndexError` that names nothing.
-- **the whole-document assert** refuses a section running from the first
-  heading to the last paragraph. That is not a replacement, it is a rewrite:
-  every other check passes while the document is emptied down to one heading
-  and one paragraph. It anchors on `heads[0]`, not paragraph 0 — a document
-  whose only heading sits under a draft notice, a date, or a byline still has
-  exactly one section, and anchoring on index 0 would wave it through.
-- **`ends[k] > starts[k] + 1`** catches a section with no body paragraph — a
-  heading followed straight by a table, or the last heading in the document.
-  There is nothing under it to rewrite. It runs before any mutation, so a bad
-  target changes nothing.
-- **the `}tbl` assert** catches a table inside a section being replaced.
-  `doc.paragraphs` does not see tables, so the loop below cannot remove one:
-  without this the old table survives under the new heading with every other
-  check passing. Say the table has to be rebuilt, or target a different section.
-- **the `expected` assert** catches an old section left partly in place *and*
-  new content appended, because `expected` is what the paragraph count must be
-  once each replaced section holds exactly one body paragraph.
-- **the `getparent() is None` assert** catches an old paragraph the loop was
-  supposed to drop but left attached. Compare **elements, not text**: text
-  comparison cannot tell a paragraph that survived from an identical one
-  standing legitimately elsewhere, and a document that repeats a line — three
-  status sections each reading `Nothing to report.` — would fail a correct edit
-  with no way to satisfy the assert. Identity has no such collision, and it
-  needs no special case for blank paragraphs.
-
-An assert that fires is a failed turn to diagnose, never a document to deliver.
-
-### When the replacement needs more than one paragraph
-
-The loop above reuses one paragraph per section and drops the rest. When a
-replacement needs an **extra** paragraph, insert it before the paragraph that
-should follow it. `insert_paragraph_before` is the only insert there is, and it
-is a method on the paragraph you want to push down:
-
-```python
-anchor = paras[ends[k]]                 # the next section's heading
-extra = anchor.insert_paragraph_before("A second body paragraph.", style="Normal")
-```
-
-It takes the same style names as `add_paragraph` (`"Heading 2"`, `"List
-Bullet"`, `None` for Normal) and returns the new paragraph, so runs can be
-formatted on it. Inserting a whole new section is this call once per paragraph,
-each against the heading it goes above. A section at the very end of the
-document has no next heading to anchor to — `ends[k]` is `len(paras)` — so
-append there with `doc.add_paragraph`, the one case where appending is right.
-
-Inserting does not disturb the `paras` snapshot: it is a plain Python list
-holding the paragraphs that already existed, so every index taken before the
-insert still points at the same paragraph afterwards. Only a fresh
-`doc.paragraphs` shifts.
-
-Count what you insert and fold it into `expected` rather than dropping the
-guard — `expected = before - len(old_body) + len(NEW) + added` — so an
-accidental append is still caught.
-
-## Removing Content
-
-python-docx has **no delete API.** There is no `doc.remove_paragraph` and no
-`paragraph.delete`, and `doc.paragraphs` is rebuilt on every access, so
-`doc.paragraphs.remove(p)` edits a throwaway list and changes nothing in the file.
-Removing anything means dropping its XML element from the parent — this one line
-is the whole technique, and there is no alternative to it:
-
-```python
-p._element.getparent().remove(p._element)
-```
-
-Code that finds the paragraphs and never runs that line — a `for`/`if` that
-matches the text and falls through, or a comment like
-`# Find and remove paragraphs containing "Conclusion"` standing in for the
-removal — saves a document byte-identical to the input at `exitCode 0`, with an
-attachment that looks like a success. Nothing in the result says the edit was a
-no-op, which is why the sample below asserts the count changed before it saves.
-
-Because `doc.paragraphs` is a fresh list each time, `for p in doc.paragraphs:`
-walks a snapshot and removing inside the loop is safe.
-
-**A whole section** — a heading plus everything under it, up to the next heading
-of the same or higher rank — is that line plus a flag. Track the heading's level,
-or a sub-heading inside the section ends the removal early and orphans the
-paragraphs below it:
-
-```python
-from docx import Document
-
-doc = Document("existing.docx")
-
-TARGET = "Conclusion"                  # the heading text that opens the section
-
-before = len(doc.paragraphs)
-depth = None                           # the target heading's level while removing
-for p in doc.paragraphs:
-    style = p.style.name               # a style object — compare through .name
-    if style.startswith("Heading"):
-        tail = style.split()[-1]
-        level = int(tail) if tail.isdigit() else 1     # "Heading 2" -> 2
-        if depth is not None and level <= depth:
-            depth = None                               # a sibling heading closes the section
-        if p.text.strip() == TARGET:
-            depth = level
-    if depth is not None:
-        p._element.getparent().remove(p._element)
-
-after = len(doc.paragraphs)
-assert after < before, f"removed nothing ({before} -> {after}) — the match never fired"
-doc.save("existing_revised.docx")      # a NEW name — never the staged input
-print(f"{before} -> {after} paragraphs")
-```
-
-Find the heading through `p.style.name`, never the text alone — a body paragraph
-that mentions "Conclusion" is not the section heading. Removing individual
-paragraphs is the same loop without the flag: match them, and call the removal
-line on each one.
-
-**Assert the count changed, before you save.** Keep the
-`assert after < before` line exactly where the sample puts it — between the loop
-and `doc.save(...)` — and do not soften it to a `print` or an `if`. It is what
-makes a no-op impossible to deliver: the assert raises, `save` never runs, so no
-file is written and the result comes back with `missingOutputs` instead of an
-attachment. Without it a removal that never fired still saves the unchanged
-document, and the run is indistinguishable from a real edit — `exitCode 0`, an
-attachment, and nothing anywhere saying the document is a copy of the input.
-
-An assert that fires is a **failed turn to diagnose**, never a result to report.
-It means the match did not fire: wrong heading text, a heading style the document
-does not use, or text living in a table, header, or footer, which
-`doc.paragraphs` never walks. Fix the match and rerun — do not delete the assert
-to get a file out.
-
-The printed `before -> after` line is then just the reply line (`16 -> 12
-paragraphs`), not the check. Both live inside the build, so this takes no extra
-call: the assert and the `print` are in the same `exec` that does the removal.
-
-This assert is also why "Success = stop" needs no second call on a destructive
-edit: `exitCode: 0` plus an attachment cannot on its own tell a real edit from
-a copy of the input, because a removal that never fired produces both. The
-build itself closes that gap — it asserts the count changed before `save`, so
-a no-op returns `missingOutputs` rather than a convincing attachment. A
-delivered document is still never reopened to "verify" it; the fix for a
-failed assert is a corrected build, never an `exec` opened to inspect what was
-already delivered.
-
-**Table rows** have no delete API either, and take the same idiom on the row's own
-element. `table.rows` iterates a snapshot just as `doc.paragraphs` does, so
-removing inside the loop is safe — and the count gets the same assert, because a
-row matched by its cell text can miss exactly the way a paragraph can:
-
-```python
-table = doc.tables[0]
-
-before = len(table.rows)
-for row in table.rows:
-    if row.cells[0].text == "Discontinued":
-        row._element.getparent().remove(row._element)
-assert len(table.rows) < before, f"no row matched ({before} rows unchanged)"
-```
-
-Removing a row by position needs no assert — `table.rows[9]` on a 4-row table
-raises `IndexError` rather than quietly doing nothing:
-
-```python
-row = table.rows[2]
-row._element.getparent().remove(row._element)
-```
-
-Rows only grow at the bottom: there is no insert-at, and no delete either
-outside this idiom. Address cells as `table.cell(row, col)` or
-`table.rows[r].cells[c]` — they are the same cell; for formatting inside a
-cell go through `cell.paragraphs[0]` and its runs like any other paragraph.
-
-**Table columns cannot be removed.** A column is not one element — it is an entry
-in the table grid plus one cell in every row — and a horizontally merged cell is a
-single `<w:tc>` shared across two grid positions, so removing "the second cell" of
-every row deletes that merged cell whole and leaves its row a column short. The
-document opens visibly ragged and nothing raises. Rebuild the table with the
-columns you want instead, or say the column has to be dropped in Word.
-
-## Reading What Is Already in the Document
-
-A document exposes exactly two collections — `doc.paragraphs` and `doc.tables`.
-Everything else is derived by filtering them; there is no `doc.headings`, no
-`doc.sections_by_title`, no `doc.text`. A `Paragraph` has `.text`, `.style` and
-`.runs`, and no `.paragraphs` of its own.
-
-**`paragraph.style` is a style object, not a string** — compare through
-`.name`, or you get
-`AttributeError: 'ParagraphStyle' object has no attribute 'startswith'`:
-
-```python
-headings = [p for p in doc.paragraphs if p.style.name.startswith("Heading")]
-body = [p for p in doc.paragraphs if p.style.name == "Normal"]
-```
-
-Most edits need no inspection at all — go straight to the change. When a look
-is genuinely needed first (an exact `.text` to match, a style name), that call
-only prints: **an inspection never saves and declares no `outputs`** — a save
-without the change delivers a stale copy of the user's document. The new file
-comes only from the one call that changes it. Reading for the _user_ — a
-summary or an answer delivered as chat text — is its own flow with its own
-call shape: load `references/read.md`.
-
-## Resizing Text: Set the Styles, Never Scale `run.font.size`
-
-`run.font.size` is `None` whenever the size comes from the paragraph's style,
-which is the normal case for a document you did not hand-size. **`None` does not
-mean zero.** Reading it as a number and scaling it writes a 0pt font, and 0pt
-text is invisible in Word and Pages — the document opens looking blank, with no
-error anywhere to tell you why:
-
-```python
-size = run.font.size.pt if run.font.size else 0
-run.font.size = Pt(size * 1.5)          # WRONG: 0 * 1.5 = 0pt, invisible text
-```
-
-"Make the font bigger" is a change to the **styles**, because every run without
-its own size inherits from them. Set absolute point sizes on the styles the
-document actually uses, and the whole document — body, tables, headers — follows
-in four lines:
-
-```python
-from docx import Document
-from docx.shared import Pt
-
-doc = Document("existing.docx")
-
-doc.styles["Normal"].font.size = Pt(14)      # body text; 11pt is the default
-doc.styles["List Bullet"].font.size = Pt(14)
-doc.styles["Heading 1"].font.size = Pt(20)
-doc.styles["Title"].font.size = Pt(32)
-
-doc.save("larger.docx")
-print(f"{len(doc.paragraphs)} paragraphs resized")
-```
-
-**Keep the hierarchy.** Raise every style you touch, not one size for all of
-them — a title and a heading set to the body size read as unstyled text. Body
-around 14pt pairs with roughly 20pt headings and a 32pt title, and the same
-ratios hold at any size the user asks for.
-
-Only touch a style the document has — guard with the `doc.styles` check above
-when unsure. If a specific run really must be sized on its own, assign an
-absolute `Pt(...)` value; never one derived from the size you read back.
-
-## Errors
-
-- `PackageNotFoundError: Package not found at '…'` — the document was never
-  staged, or an id-less entry staged an image under a `.docx` path. Add
-  `inputs: [{ "attachmentId": "<id from the exec result or the [Attached file …]
-line>", "path": "existing.docx" }]` and open that exact path. If no id is
-  available, ask the user to attach the file again rather than guessing a name.
-- `attachment … not found in this chat` means `inputs` listed an id that is not
-  in this chat (often a copied placeholder like `att_doc`). Re-copy the exact id
-  from the `exec` result or the `[Attached file …]` line that names the file;
-  if no id appears anywhere in the chat, ask the user to re-attach.
-- `ModuleNotFoundError: No module named 'docx'` means `packages` was missing or
-  wrong — add `["python-docx==1.2.0"]` and rerun. Never try to install it, and
-  never "fix" it by importing `python_docx`; the import stays `docx`.
-- `KeyError: "no style with name '…'"` — the style is not in this document.
-  Check `doc.styles` and fall back as shown under Styles.
-- `NameError: name 'Pt' is not defined` (or `Inches`, `RGBColor`) — the import
-  line is missing that name; they all import from `docx.shared`.
-- `AssertionError: removed nothing (16 -> 16)` means the removal matched nothing:
-  either the loop never fired or it never called
-  `p._element.getparent().remove(p._element)`; python-docx has no delete method to
-  reach for instead. Diagnose the match and rerun — never delete the assert to get
-  a file out, since the file it would produce is a copy of the input.
-- `AssertionError: expected 7 paragraphs, got 9` means the document did not end
-  up the shape a replacement makes. Two causes: the old sections were only
-  partly replaced — the loop rewrote the paragraph after each heading and left
-  the rest of the section standing — or new content was appended with
-  `add_paragraph`/`add_heading`, which only ever append. `expected` is derived
-  from the section bounds before anything changes, so it is right and the
-  document is wrong: replace each section through to the next heading.
-- `AssertionError: an old paragraph is still in the document: '…'` means the
-  loop was adapted and no longer drops everything past the paragraph it reuses.
-  Every paragraph from `starts[k] + 2` to `ends[k]` has to go; the removal idiom
-  below is the only thing that removes one. This compares elements, so it never
-  fires because the document happens to repeat a line elsewhere.
-- `AssertionError: section '…' has no body paragraph to replace` means that
-  heading is followed straight by a table, or is the last paragraph in the
-  document. There is nothing under it to rewrite: target a different section, or
-  insert the body with `insert_paragraph_before` before adding to it.
-- `IndexError: list index out of range` while walking sections means an index
-  ran past the end of `starts` or of `paras`: a `TARGET` reaching past the last
-  section, or `paras[i + 1]` on a document whose final paragraph is a heading.
-  Guard the range with `len(starts) > max(TARGET)` — not against `len(NEW)`,
-  which says nothing when the range does not start at zero — and take section
-  ends from the next heading of the same or higher rank, with `len(paras)`
-  closing the last one.
-- `AssertionError: section '…' holds a table` means the section being replaced
-  contains a table. `doc.paragraphs` never sees tables, so the loop cannot
-  remove one and it would survive under the new heading. Rebuild the table
-  explicitly, or tell the user that section has to be replaced by hand.
-- `AssertionError: TARGET names 2 sections but NEW has 3 items` means the range
-  and the content list drifted apart. Fix whichever is wrong; do not let `zip`
-  quietly use the shorter.
-- `AssertionError: TARGET reaches section 2, but the document has 1` on a
-  document that plainly has several usually means its sections are `Heading 2`
-  under a `Heading 1` title. The title is dropped before sections are picked,
-  so check `rank()` is reading the style names this document actually uses —
-  print `[p.style.name for p in doc.paragraphs]` — rather than lowering
-  `TARGET` until the assert passes. Section 1 of a title-only document is the
-  whole document.
-- `AssertionError: section '…' spans the whole document` means the heading
-  selected covers every paragraph, so replacing it would empty the document.
-  It is a title being treated as a section, or a request to rewrite rather than
-  edit — build a new document with `references/create.md` if that is what the
-  user wants.
-- `AttributeError: 'Document' object has no attribute 'insert_paragraph'` means
-  the code guessed an insert API on the document. There is none. The only insert
-  is `paragraph.insert_paragraph_before(text, style)`, on the paragraph the new
-  one goes above.
-- `TypeError: Document.add_paragraph() takes from 1 to 3 positional arguments
-  but 4 were given` means a position was passed to `add_paragraph`. It has no
-  position parameter and always appends; use `insert_paragraph_before`.
-- Identical old and new fingerprints on a run that saved anyway means the
-  assert was softened into `print` lines and both hashes were taken before the
-  change. It is not evidence the edit failed, and it is not grounds for another
-  `exec`: restore the assert and take the second hash after the mutation.
-- A delivered document identical to the one you opened means an edit ran
-  without the fingerprint assert — an edit that matched nothing, or an
-  inspection that saved. Add the assert before `save` and rerun the actual
-  change.
-- `AssertionError: nothing changed — the edit matched nothing or never ran`
-  means exactly that: the paragraph match found no text, or no mutation
-  happened before `save`. Print the real `.text` values, fix the match, rerun
-  — never remove the assert.
-- `TypeError: 'Table' object is not subscriptable` — a table was indexed
-  directly (`table[0]`). Cells are reached through `table.rows[r].cells[c]` or
-  `table.cell(r, c)`; a whole row of cells is `table.add_row().cells`.
-- `AttributeError: 'Document' object has no attribute 'remove_paragraph'` (or
-  `'Paragraph' object has no attribute 'delete'`) means the code guessed a delete
-  API. There is none; drop the XML element instead.
-- A resize that "worked" but left the document blank means a 0pt font: something
-  scaled `run.font.size` while it was `None`. Set absolute sizes on the styles
-  instead — see Resizing Text.
-- `SyntaxError: invalid syntax` on a one-line `for`/`if` means the source was
-  collapsed — restore multi-line newlines from the sample and rerun. Underscores
-  in names (`add_paragraph`, not `addparagraph`) must stay. Do not switch to
-  `python -c` or change the package pin.
-- On an `AttributeError` from python-docx the API name is wrong; on a `TypeError`
-  about positional arguments the call passes the wrong number of them — usually
-  several strings where one is allowed. Fix either against this file's examples,
-  reading the line number in the traceback. Do not retry the same call, and do
-  not switch to a shell.
-- If the result has `missingOutputs`, the file was never written. Read stderr
-  first: an `AssertionError` there means a guard stopped the save on purpose
-  and its message names what to fix — rerunning the same code fails the same
-  way. Only when stderr is clean is this a naming problem: check the `save()`
-  name matches the declared output and rerun once.
-- Never print the document's bytes or base64 — stdout is capped and the file
-  travels through `outputs`. A build call prints exactly one line (e.g. `9
-paragraphs, 1 table(s)`).
-- Never pass an absolute path to `save()`.
-
-## Finish
-
-When `exitCode` is `0` and `attachments` lists the `.docx`, the edit is done —
-the `exec` result carries
-`attachments: [{ attachmentId, fileName, byteLength }]` and the file is already
-attached to the chat for the user to open or save. Stop tool use and reply
-with a single line: file name + the count line from stdout. Exactly one
-successful `exec` per request; never reopen a delivered document to "verify"
-it.