@qvac/skills 0.0.0 → 0.1.0

package/skills/word/references/edit.md

@@ -0,0 +1,704 @@
+# Editing an Existing Word Document (python-docx)
+
+**Stop here if the request changes some of the facts, points, bullets, items,
+or paragraphs** — "replace the first 10 facts", "change fact 3", "swap the
+bullets", "reword paragraph 7". That job is `references/replace.md`: call the
+`skill` tool with `name: "word"` and `file: "references/replace.md"` now, and
+do not use anything in this file for it. No Python is written for that job.
+
+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.
+
+## 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 — "change the first five points", "rewrite section 2" — is a
+different job with its own recipe and its own guards: see Replacing Content In
+Place.
+
+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
+```
+
+## Replacing Content In Place
+
+This recipe is for whole *sections* (a heading plus its body). Changing some
+of the facts, points, bullets, or paragraphs is `references/replace.md` —
+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.