dsh-office-kit 0.4.2 → 0.4.4

package/assets/skills/office-documents/SKILL.md

@@ -1,77 +1,39 @@
 ---
-description: Build, inspect, revise, and visually verify Word .docx files using the Office helper CLI and the bundled XML scripts.
+description: Create, read, edit, render, and verify Word documents (.docx) — build new files, revise existing ones, and check the rendered pages.
 ---
 
 # Documents (.docx)
 
-A `.docx` is a zip of XML parts: `word/document.xml` holds the body, and headers, footers, footnotes, comments, styles and numbering live beside it. Two routes reach every part of it:
-
-- **Fast path** — the helper CLI inspects, renders and creates: `docx create`, `docx read`, `docx render`. It performs no in-place mutation.
-- **Structural path** — `scripts/*.py` in this skill do all editing: replace text, append blocks, set properties, and everything structural — comments, tracked changes, fields, protection, watermarks.
-
-Pick the cheapest route that produces the structure the user asked for, then verify it visually. Never invent content, and never deliver a file you have not looked at.
+A `.docx` is a zip of XML parts: `word/document.xml` holds the body, with headers, footers, footnotes, comments, styles and numbering beside it. Two routes reach them: the helper CLI (`docx create`, `docx read`, `docx render`, no in-place mutation) and `scripts/*.py`, which edits everything structural — text, blocks, properties, comments, tracked changes, fields, protection, watermarks. Pick the cheapest route that yields the requested structure, then look at the pages. Never invent content; never deliver a file you have not looked at.
 
 ## Before any file work
 
-1. Call the `office_status` tool.
-2. Read the `## Office runtime` block at the end of this file for the verified `python`, `cli`, `skill` and `shared` paths.
-3. If that block says no runtime is available, stop and give the user the `node "..."` remedy command it names, then call `office_status` again. Do not fake a document or claim success.
-
-Quote every path. Spaces, non-ASCII names and `&` are normal on Windows.
+Call `office_status`, then read the `## Office runtime` block at the end of this file — it holds the verified `python`, `cli`, `skill` and `shared` paths for this install. If there is no runtime, stop, give the user the `node "..."` remedy command, and call `office_status` again — never fake a document or claim success. Quote every path: spaces, non-ASCII names and `&` are normal on Windows.
 
 ## Delivery
 
-Always hand the finished file to the user with the `present` tool, then summarise in one sentence what changed. A bare path is not delivery: the chat transcript renders `.docx`/`.pptx`/`.xlsx`/`.pdf` links as "二进制文件，无法显示改动" and the user cannot open them.
-
-- Creating a file: write it into the user's workspace, verify it, then `present`.
-- Editing an existing file: never overwrite the original. Write `<original>-edited.<ext>` (or a name the user asked for), verify it, `present` it, and state both paths.
+Deliver with `present` plus a one-sentence summary. A bare path is not delivery: the transcript renders `.docx`/`.pptx`/`.xlsx`/`.pdf` links as "二进制文件，无法显示改动". Write new files into the workspace, verify, `present`. Never overwrite an original — write `<original>-edited.<ext>` (or the user's name), verify, `present`, and state both paths.
 
 ## Annotations
 
-The user may reply with an `office-annotations` block: `[{ page, text, requirement, region: { left, top, width, height } }]`. `region` is normalised 0–1 against the rendered preview page the user drew on; `requirement` is free-form natural language. Treat it as a change request, not as editor state: locate what the region covers, apply the smallest edit that satisfies `requirement`, re-render, and confirm the region now looks right.
-
-When the payload cannot be mapped to a concrete object (the region is empty or the file has no geometry), do not guess silently — say what you could not locate.
-
-For `.docx`, `page` is the page of the *rendered PDF preview*, not a Word page. Use `text` (and the paragraph text near it) to locate the target; the region is a hint for near-misses only. A region that lands on a table row, a caption or a header is ambiguous — state which object you picked before editing.
+An `office-annotations` payload is `[{ page, text, requirement, region: { left, top, width, height } }]`: `region` normalised 0–1 against the rendered preview page, `requirement` free-form. Treat it as a change request, not editor state — find what the region covers, apply the smallest edit that satisfies `requirement`, re-render, confirm. Unmappable payload (empty region, no geometry): say what you could not locate; never guess. For `.docx`, `page` is a rendered PDF page, not a Word page: locate by `text` and its neighbouring paragraphs, use the region only for near-misses, and name the object you picked when a region lands on a table row, caption or header.
 
 ## Verify
 
-Rendering is the only proof that a document looks right.
-
 ```bash
 "<python>" "<cli>" docx render --input "<file.docx>" --out-dir "<render-dir>"
 ```
 
-The command writes a PDF plus one PNG per page and prints the paths. Open each PNG with `read_image` and check: heading hierarchy, table width and cell wrapping, page breaks, header/footer, clipped or overflowing text, missing glyphs (dashes, CJK, symbols), equation rendering, and caption placement.
-
-- Iterate until the pages look correct, then deliver. "It parses" is not verification.
-- If the runtime reports no renderer (`renderers.can_render.docx: false` — the DSH LibreOffice kit is missing), ask the user to fix the install, or fall back to `docx read` plus the audit scripts. Say plainly that layout was not visually verified — do not describe a page you did not see.
-- After a script edits XML, re-render. A package can stay valid while the page it produces is broken.
-
-## Choosing a route
-
-| Job | Fast path | Structural path |
-|---|---|---|
-| New document from scratch | `docx create --spec` | `python-docx` snippet in `tasks/create_edit.md` |
-| Replace or append text and blocks | — | `scripts/replace_text.py`, `scripts/append_blocks.py` |
-| Document properties | — | `scripts/core_properties.py` |
-| Read structure | `docx read` | `scripts/docx_kit.py text`, `style_lint`, audits |
-| Comments, tracked changes | — | `scripts/comments_*.py`, `scripts/*tracked*.py` |
-| Fields, TOC, cross-references | — | `scripts/insert_toc.py`, `insert_ref_fields.py`, `fields_*.py` |
-| Footnotes, endnotes | — | `scripts/insert_note.py`, `footnotes_report.py` |
-| Tables, layout geometry | `docx create` table block | `scripts/table_geometry.py`, `docx_table_to_csv.py` |
-| Styles, templates | — | `scripts/style_*.py`, `apply_template_styles.py` |
-| Protection, watermarks, privacy | — | `scripts/set_protection.py`, `watermark_*.py`, `privacy_scrub.py`, `redact_docx.py` |
-
-Where no verb exists, the fallback is the listed script or a short `python-docx`/`lxml` snippet. Both are runnable with the runtime `python`; neither needs a new dependency.
+Writes a PDF and one PNG per page and prints the paths. Open each PNG with `read_image`; check heading hierarchy, table width and cell wrapping, page breaks, header/footer, clipped or overflowing text, missing glyphs (dashes, CJK, symbols), equations, caption placement. Iterate, then deliver — "it parses" is not verification. Without a renderer (`office_status` reports `renderers.available: false`, with a `remedy`) ask the user to fix the install or fall back to `docx read` plus the audit scripts; say layout was not visually verified and never describe an unseen page. Re-render after every script edit: a package can be valid while its page is broken. Details: `tasks/verify_render.md`. Setup: `troubleshooting/libreoffice_headless.md`.
 
 ## Task index
 
-| Task | Read | Main tool |
+| Job | Task doc | CLI or main tool |
 |---|---|---|
-| Create or edit a document | `tasks/create_edit.md` | CLI create, `replace_text.py`, `append_blocks.py`, `core_properties.py` |
-| Read and review a file | `tasks/read_review.md` | CLI read, `docx_kit.py text` |
-| Comments | `tasks/comments_manage.md` | `comments_add/extract/apply_patch/strip.py` |
+| Create a document | `tasks/create_edit.md` | `docx create --spec`, `python-docx` snippet, `append_blocks.py` |
+| Read and review a file | `tasks/read_review.md` | `docx read`, `docx_kit.py text`, `style_lint`, audits |
+| Edit text, blocks or properties | `tasks/create_edit.md` | `replace_text.py`, `append_blocks.py`, `core_properties.py` |
+| Comments | `tasks/comments_manage.md` | `comments_*.py` |
 | Tracked changes | `tasks/clean_tracked_changes.md` | `accept_tracked_changes.py`, `add_tracked_replacements.py` |
 | Fields and updates | `tasks/fields_update.md` | `fields_report.py`, `fields_materialize.py` |
 | Table of contents | `tasks/toc_workflow.md` | `insert_toc.py`, `fields_*.py` |
@@ -79,7 +41,7 @@ Where no verb exists, the fallback is the listed script or a short `python-docx`
 | Navigation links | `tasks/navigation_internal_links.md` | `internal_nav.py` |
 | Footnotes and endnotes | `tasks/footnotes_endnotes.md` | `insert_note.py`, `footnotes_report.py` |
 | Headings and numbering | `tasks/headings_numbering.md` | `heading_audit.py` |
-| Tables | `tasks/tables_spreadsheets.md` | `table_geometry.py`, `docx_table_to_csv.py`, `xlsx_to_docx_table.py` |
+| Tables and geometry | `tasks/tables_spreadsheets.md` | `docx create` table block, `table_geometry.py`, `docx_table_to_csv.py`, `xlsx_to_docx_table.py` |
 | Images and figures | `tasks/images_figures.md` | `images_audit.py` |
 | Sections and page setup | `tasks/sections_layout.md` | `section_audit.py` |
 | Styles | `tasks/style_lint_normalize.md` | `style_lint.py`, `style_normalize.py` |
@@ -91,24 +53,26 @@ Where no verb exists, the fallback is the listed script or a short `python-docx`
 | Privacy and metadata | `tasks/privacy_scrub_metadata.md` | `privacy_scrub.py` |
 | Redaction | `tasks/redaction_anonymization.md` | `redact_docx.py` |
 | Merging documents | `tasks/multi_doc_merge.md` | `merge_docx_append.py` |
-| Comparing versions | `tasks/compare_diff.md` | `render_and_diff.py` |
-| Equations | `tasks/equations.md` | CLI `equation` block |
-| Visual verification | `tasks/verify_render.md` | `render_docx.py` (skill root) |
+| Comparing versions | `tasks/compare_diff.md` | `docx render`, `render_and_diff.py` |
+| Equations | `tasks/equations.md` | `docx create` `equation` block |
+| Visual verification | `tasks/verify_render.md` | `docx render`, `render_docx.py` (skill root) |
 | Fixtures and edge cases | `tasks/fixtures_edge_cases.md` | `make_fixtures.py` |
 
+Where no verb exists, use the listed script or a short `python-docx`/`lxml` snippet — both run on the runtime `python` without a new dependency.
+
 ## Document defaults
 
 - Letter 8.5×11 portrait (A4 when the user or template says so), 1in margins, body 11–12pt, single column.
-- Black headings and body text; colour only for deliberate emphasis, links and chart series.
-- Tables: light grey `#D9D9D9` borders, a bold header row, `w:tblHeader` so the header repeats across pages, no vertical merges in wide tables.
-- No decorative callout boxes, drop shadows or coloured sidebars. Structure comes from headings, lists and tables.
-- Captions sit under figures and above tables, in the `Caption` style, and stay with their object.
-- Prefer native structures — heading styles, real lists, real tables, OMML equations — over hand-positioned runs, because the next edit depends on that structure.
+- Black headings and body; colour only for deliberate emphasis, links and chart series.
+- Tables: `#D9D9D9` borders, bold header row, `w:tblHeader` repeat, no vertical merges in wide tables.
+- No callout boxes, drop shadows or coloured sidebars — structure comes from headings, lists and tables.
+- Captions under figures and above tables, `Caption` style, staying with the object.
+- Prefer native headings, lists, tables and OMML equations over hand-positioned runs: the next edit depends on that structure.
 
 ## Writing quality
 
-Write the content the user asked for, in plain sentences, without filler. `references/writing-quality.md` holds the checklist; `references/docx-structure.md` explains which package part each feature lives in before you touch XML.
+Plain sentences, no filler. Checklist `references/writing-quality.md`; package parts `references/docx-structure.md`.
 
 ## Shared workflow
 
-Cross-format habits, the review loop and how to read annotation payloads live in `"<shared>/common-workflow.md"` and `"<shared>/annotation-recipes.md"`; read them when the job spans more than one Office format.
+Cross-format habits and annotation payloads: `"<shared>/common-workflow.md"`, `"<shared>/annotation-recipes.md"`.

package/assets/skills/office-documents/examples/end_to_end_smoke_test.md

@@ -1,6 +1,6 @@
 # End-to-end smoke test
 
-A short job that touches creation, inspection, structural changes and verification. Run it once after a runtime change, or as a template for "is this environment healthy".
+A short job touching creation, inspection, structural change and verification. Run it after a runtime change, or as a template for "is this environment healthy".
 
 ```bash
 PY="<python>"; CLI="<cli>"; S="<skill>/scripts"; R="<skill>"; W="/tmp/docx-smoke"
@@ -41,7 +41,7 @@ Expect `ok: true` and non-zero `headings`, `tables`, `equations`.
 "$PY" "$S/style_lint.py" "$W/base.docx"
 ```
 
-Expect the sections, the parts list to include `word/document.xml`, Letter 8.5×11 portrait, and an empty style-lint `counts`.
+Expect the sections, `word/document.xml` in the parts list, Letter 8.5×11 portrait, and an empty style-lint `counts`.
 
 ## 3. Change it structurally
 
@@ -63,7 +63,7 @@ Expect the sections, the parts list to include `word/document.xml`, Letter 8.5×
 "$PY" "$S/table_geometry.py" "$W/with-toc.docx"
 ```
 
-Audits may exit 1 with findings — that is a report, not a failure of the environment. Every finding should be explainable.
+Audits may exit 1 with findings: that is a report, not an environment failure. Every finding should be explainable.
 
 ## 5. Verify visually
 
@@ -71,7 +71,7 @@ Audits may exit 1 with findings — that is a report, not a failure of the envir
 "$PY" "$R/render_docx.py" "$W/with-toc.docx" --output_dir "$W/render" --dpi 150
 ```
 
-Then open each PNG with `read_image`. Without the DSH LibreOffice kit the command exits 3 with `no_renderer`; that is a setup problem, not a document problem, and the rest of the test still stands.
+Open each PNG with `read_image`. Without the DSH LibreOffice kit the command exits 3 with `no_renderer`: a setup problem, not a document problem, and the rest of the test still stands.
 
 ## 6. Deliver
 
@@ -83,4 +83,4 @@ Copy the final file into the user's workspace, `present` it, and state what chan
 rm -rf "$W"
 ```
 
-Nothing under the workspace should be left behind from a smoke test.
+Nothing under the workspace should be left behind by a smoke test.

package/assets/skills/office-documents/ooxml/comments.md

@@ -1,6 +1,6 @@
 # Comments in the package
 
-A comment is three pieces that must agree: `word/comments.xml` holds the content, `word/document.xml` holds a range marking which text is discussed, and the relationship plus content-type override make the part exist at all.
+A comment is three pieces that must agree: `word/comments.xml` holds the content, `word/document.xml` holds a range marking which text is discussed, and a relationship plus content-type override make the part exist at all.
 
 ## The markup
 
@@ -20,21 +20,21 @@ A comment is three pieces that must agree: `word/comments.xml` holds the content
 
 Rules that matter in practice:
 
-- `w:id` must be unique across comments **and** match in all three places. A range start without an end leaves Word showing a comment with no anchor; an end without a start can make the file refuse to open.
-- The comment reference run belongs at the end of the range, not somewhere else in the paragraph.
+- `w:id` is unique across comments **and** matches in all three places. A range start without an end leaves Word showing a comment with no anchor; an end without a start can make the file refuse to open.
+- The comment reference run belongs at the end of the range, not elsewhere in the paragraph.
 - `word/comments.xml` needs an override in `[Content_Types].xml` and a relationship from `word/document.xml`; without both, the part is ignored or the file is corrupt.
-- The file's root has `mc:Ignorable` listing `w14`/`w15` etc.; a `w15:done` attribute (the "resolved" flag) is only legal when those namespaces are declared.
+- The file root lists `w14`/`w15` in `mc:Ignorable`; the `w15:done` "resolved" attribute is only legal with those namespaces declared.
 
 ## Resolved versus deleted
 
-`w15:done="1"` on the `w:comment` keeps the comment in the file and shows it as resolved. Removing the comment is a different operation: delete the `w:comment`, both range markers and the reference run. Resolving hides it from the default pane; it does not remove the text from the file.
+`w15:done="1"` on `w:comment` keeps the comment in the file and shows it as resolved. Removing it is a different operation: delete the `w:comment`, both range markers and the reference run. Resolving hides the comment from the default pane; it does not remove the text from the file.
 
 ## Where comments hide
 
-- Replies are comments too, linked by `w15:paraIdParent`; a strip that removes the parent leaves an orphan.
+- Replies are comments too, linked by `w15:paraIdParent`; removing the parent leaves an orphan.
 - Anchors can sit in headers, footnotes and text boxes as well as the body.
-- A comment deleted in Word leaves no trace; a comment whose range was deleted may remain in `comments.xml` with nothing anchoring it. That is why extraction reports anchors: a comment with empty anchored text is evidence of drift.
+- A comment deleted in Word leaves no trace, but a comment whose range was deleted may remain in `comments.xml` with nothing anchoring it. That is why extraction reports anchors: a comment with empty anchored text is evidence of drift.
 
 ## Working from the scripts
 
-`comments_extract.py` reads the pairing and prints anchored text per comment; `comments_add.py` writes all three pieces; `comments_apply_patch.py` edits content and the resolved flag; `comments_strip.py` removes every trace and the part itself. Use `docx_kit.py xml '<file.docx>' word/comments.xml` when you need to see the raw part.
+`comments_extract.py` reads the pairing and prints anchored text per comment; `comments_add.py` writes all three pieces; `comments_apply_patch.py` edits content and the resolved flag; `comments_strip.py` removes every trace and the part itself. Use `docx_kit.py xml '<file.docx>' word/comments.xml` for the raw part.

package/assets/skills/office-documents/ooxml/hyperlinks_and_fields.md

@@ -1,6 +1,6 @@
 # Hyperlinks and fields
 
-A hyperlink and a field are both "a run that looks like text but is a pointer", and both break in the same way: the visible result is cached, so editing the text does not update anything.
+A hyperlink and a field are both "a run that looks like text but is a pointer", and both break the same way: the visible result is cached, so editing the text updates nothing.
 
 ## Hyperlinks
 
@@ -10,11 +10,11 @@ A hyperlink and a field are both "a run that looks like text but is a pointer",
 </w:hyperlink>
 ```
 
-- The target is a relationship in `word/_rels/document.xml.rels` with `TargetMode="External"` for a URL, or a bare relative path for a file inside the package.
+- The target is a relationship in `word/_rels/document.xml.rels`: `TargetMode="External"` for a URL, a bare relative path for a file inside the package.
 - An internal link uses `w:anchor="bookmarkName"` and no relationship at all.
-- `w:hyperlink` is a wrapper around runs; a link that spans paragraphs is not legal — put one link per paragraph.
+- `w:hyperlink` wraps runs; a link spanning paragraphs is not legal — one link per paragraph.
 
-A link whose relationship is missing renders as blue underlined text that goes nowhere. That is also what a copy-paste between documents produces.
+A link whose relationship is missing renders as blue underlined text that goes nowhere. Copy-paste between documents produces the same thing.
 
 ## Simple fields
 
@@ -24,7 +24,7 @@ A link whose relationship is missing renders as blue underlined text that goes n
 </w:fldSimple>
 ```
 
-The `w:t` inside is a cache, not the truth. Change the text and the next field update overwrites it.
+The `w:t` inside is a cache, not the truth: change the text and the next field update overwrites it.
 
 ## Complex fields
 
@@ -36,13 +36,13 @@ The `w:t` inside is a cache, not the truth. Change the text and the next field u
 <w:r><w:fldChar w:fldCharType="end"/></w:r>
 ```
 
-The begin/instrText/separate/result/end sequence must stay in that order inside one paragraph. Word shows the result between `separate` and `end`, or recomputes on open when `w:updateFields` is set in `settings.xml`:
+The begin/instrText/separate/result/end sequence keeps that order inside one paragraph. Word shows the result between `separate` and `end`, or recomputes on open when `settings.xml` sets:
 
 ```xml
 <w:updateFields w:val="true"/>
 ```
 
-Setting it makes Word prompt or update on open. A viewer that ignores it (a PDF export, some libraries) keeps showing the cache — which is why a document delivered as PDF can show "1" for every page number.
+That makes Word prompt or update on open. A viewer that ignores it (PDF export, some libraries) keeps the cache — which is why a document delivered as PDF can show "1" for every page number.
 
 ## Which field for which job
 
@@ -57,9 +57,9 @@ Setting it makes Word prompt or update on open. A viewer that ignores it (a PDF
 ## Editing fields safely
 
 - To freeze a result, replace the whole field span with a plain run (`fields_materialize.py`, `flatten_ref_fields.py`).
-- To renumber, update the cached result and leave the instruction alone; do not delete the begin/end markers.
-- `w:instrText` is where the instruction lives — a search-and-replace over `w:t` will not find `TOC`.
-- Bookmarks referenced by `REF` must exist (`w:bookmarkStart`/`w:bookmarkEnd` with matching `w:id`); a missing bookmark shows "Error! Reference source not found."
+- To renumber, update the cached result and leave the instruction alone; never delete the begin/end markers.
+- The instruction lives in `w:instrText`, so a search-and-replace over `w:t` will not find `TOC`.
+- Bookmarks referenced by `REF` must exist (`w:bookmarkStart` / `w:bookmarkEnd` with matching `w:id`); a missing bookmark shows "Error! Reference source not found.".
 
 ## See also
 

package/assets/skills/office-documents/ooxml/rels_and_content_types.md

@@ -1,6 +1,6 @@
 # Relationships and content types
 
-A `.docx` is a zip of parts, and every relationship between parts is declared twice: once as a relationship entry, once as a content type. Miss either and the file either loses the feature or refuses to open.
+A `.docx` is a zip of parts, and every relationship between parts is declared twice: once as a relationship entry, once as a content type. Miss either and the file loses the feature or refuses to open.
 
 ## The two registries
 
@@ -10,7 +10,7 @@ _rels/.rels                  # package -> document, core props
 word/_rels/document.xml.rels # document -> styles, numbering, media, header, footer, comments, hyperlinks
 ```
 
-`[Content_Types].xml` has `<Default Extension="xml" ContentType="..."/>` for extension defaults and `<Override PartName="/word/comments.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"/>` for parts that do not follow an extension rule.
+`[Content_Types].xml` uses `<Default Extension="xml" ContentType="..."/>` for extension defaults and `<Override PartName="/word/comments.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"/>` for parts that do not follow an extension rule.
 
 A relationship:
 
@@ -20,7 +20,7 @@ A relationship:
   Target="comments.xml"/>
 ```
 
-`Id` is scoped to the part that owns the `.rels` file, so `rId5` in the document and `rId5` in a header are unrelated. `Target` is relative to the owner directory unless it is absolute (`/word/media/image1.png`) or external (`TargetMode="External"`, used for hyperlinks).
+`Id` is scoped to the part that owns the `.rels` file, so `rId5` in the document and `rId5` in a header are unrelated. `Target` is relative to the owner directory unless absolute (`/word/media/image1.png`) or external (`TargetMode="External"`, used for hyperlinks).
 
 ## What breaks
 
@@ -32,13 +32,13 @@ A relationship:
 | Broken link | Relationship removed but `r:id` left in the body |
 | Lost image | Media copied without a new relationship id |
 
-Ids must be unique within a `.rels` part. When adding one, read the existing ids and take `max+1`; reusing an id silently rewires an unrelated reference.
+Ids are unique within a `.rels` part. Read the existing ids and take `max+1`; reusing an id silently rewires an unrelated reference.
 
 ## The parts that exist only when used
 
-`word/comments.xml`, `word/footnotes.xml`, `word/endnotes.xml`, `word/headerN.xml`, `word/footerN.xml`, `word/numbering.xml`, `docProps/custom.xml` — none are required, and each needs three pieces when added: the part, the override, the relationship. Removing one means removing all three (or Word reports corruption).
+`word/comments.xml`, `word/footnotes.xml`, `word/endnotes.xml`, `word/headerN.xml`, `word/footerN.xml`, `word/numbering.xml`, `docProps/custom.xml` — none are required, and each needs three pieces when added: part, override, relationship. Removing one means removing all three, or Word reports corruption.
 
-Headers and footers are referenced from the section properties, not from the document root:
+Headers and footers are referenced from the section properties, not the document root:
 
 ```xml
 <w:sectPr>
@@ -59,4 +59,4 @@ Headers and footers are referenced from the section properties, not from the doc
 
 ## Rebuild rather than regenerate
 
-When a package is broken, unzipping it, fixing the two registries and rezipping with `[Content_Types].xml` first (stored, not deflated) usually recovers it. The kit writes that order on save for this reason.
+When a package is broken, unzip it, fix the two registries and rezip with `[Content_Types].xml` first (stored, not deflated). The kit writes that order on save for this reason.

package/assets/skills/office-documents/ooxml/tracked_changes.md

@@ -1,6 +1,6 @@
 # Tracked changes
 
-Tracked changes are markup, not a diff. The file contains both the old and the new text, wrapped in elements that say which is which, plus enough metadata for Word to show reviewer names and accept or reject each edit.
+Tracked changes are markup, not a diff. The file holds both old and new text, wrapped in elements that say which is which, plus enough metadata for Word to show reviewer names and accept or reject each edit.
 
 ## The elements
 
@@ -13,7 +13,7 @@ Tracked changes are markup, not a diff. The file contains both the old and the n
 | `w:delText` | The deleted characters — not `w:t` |
 | `w:delInstrText` | A deleted field instruction |
 
-Each carries `w:id`, `w:author`, `w:date`. Ids must be unique within the document; reusing one makes Word show the wrong reviewer.
+Each carries `w:id`, `w:author` and `w:date`. Ids are unique within the document; reusing one makes Word show the wrong reviewer.
 
 A deletion is a `w:del` containing runs with `w:delText`, not a run with a strikethrough:
 
@@ -28,21 +28,21 @@ A deletion is a `w:del` containing runs with `w:delText`, not a run with a strik
 
 ## Tracking has to be on
 
-`<w:trackRevisions/>` in `word/settings.xml` makes *Word* track subsequent edits. It does not affect markup already in the file. Write the markup directly when you are generating the change; turn tracking on when the user will continue editing.
+`<w:trackRevisions/>` in `word/settings.xml` makes *Word* track subsequent edits; it does not affect markup already in the file. Write the markup directly when generating a change; turn tracking on when the user will continue editing.
 
 ## Accepting and rejecting
 
-- **Accept** — keep `w:ins` content and unwrap it; delete `w:del` entirely; for moves keep `w:moveTo`.
-- **Reject** — delete `w:ins` content; keep `w:del` content and convert `w:delText` back to `w:t` (unwrap the `w:del`).
-- Either way, remove the revision containers afterwards; leaving an empty `w:ins` shows a stray marker.
-- Format-change elements have no accept/reject choice in the content sense: accepted means the new properties stay, rejected means the old ones are restored.
+- **Accept** — keep `w:ins` content and unwrap it, delete `w:del` entirely, and for moves keep `w:moveTo`.
+- **Reject** — delete `w:ins` content, keep `w:del` content and convert `w:delText` back to `w:t` (unwrap the `w:del`).
+- Either way, remove the revision containers afterwards; an empty `w:ins` shows a stray marker.
+- Format-change elements are not content: accepting keeps the new properties, rejecting restores the old ones.
 
 ## Where tracking hides
 
-- Inside headers, footers, footnotes, endnotes, table cells, text boxes.
-- Table-level changes: `w:trPr/w:ins` for an inserted row, `w:tcPr/w:cellIns` for a cell.
-- Paragraph-level: a paragraph mark inserted or deleted uses `w:rPr/w:ins` in `w:pPr`, so "delete this paragraph" is not a `w:del` around the paragraph.
-- Comments are separate markup; a comment can survive its being accepted.
+- Inside headers, footers, footnotes, endnotes, table cells and text boxes.
+- Table level: `w:trPr/w:ins` for an inserted row, `w:tcPr/w:cellIns` for a cell.
+- Paragraph level: an inserted or deleted paragraph mark uses `w:rPr/w:ins` in `w:pPr`, so "delete this paragraph" is not a `w:del` around the paragraph.
+- Comments are separate markup; a comment can survive its text being accepted.
 
 ## Reading markup without a renderer
 
@@ -50,4 +50,4 @@ A deletion is a `w:del` containing runs with `w:delText`, not a run with a strik
 "<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode report
 ```
 
-The report lists insertions and deletions with authors and the text on each side. That is the honest way to answer "what changed" when there is no rendered view, and it is also how you confirm a generated change landed as markup rather than as plain text.
+The report lists insertions and deletions with authors and the text on each side — the honest answer to "what changed" with no rendered view, and the way to confirm a generated change landed as markup rather than as plain text.

package/assets/skills/office-documents/references/docx-structure.md

@@ -19,9 +19,7 @@ word/comments.xml, footnotes.xml, endnotes.xml   optional
 
 ## The body
 
-`word/document.xml` is a sequence of block-level elements: `w:p` (paragraph), `w:tbl` (table), `w:sdt` (content control), and finally one `w:sectPr` per section (the last one sits in the body, earlier ones inside a paragraph's `pPr`).
-
-A paragraph is:
+`word/document.xml` is a sequence of block elements — `w:p` (paragraph), `w:tbl` (table), `w:sdt` (content control) — plus one `w:sectPr` per section: the last sits in the body, earlier ones inside a paragraph's `pPr`.
 
 ```xml
 <w:p>
@@ -39,9 +37,9 @@ A paragraph is:
 </w:p>
 ```
 
-Everything a reader sees is a run inside a paragraph; everything that makes it look different from its style is direct formatting in `pPr`/`rPr`. Direct formatting is why `style_normalize.py` exists.
+Everything a reader sees is a run inside a paragraph; everything that makes it differ from its style is direct formatting in `pPr`/`rPr`, which is why `style_normalize.py` exists (`tasks/style_lint_normalize.md`).
 
-A table is `w:tbl` > `w:tblPr` (style, width, layout) + `w:tblGrid` (column widths) + `w:tr` > `w:tc` > `w:p`. A cell always contains at least one paragraph.
+A table is `w:tbl` > `w:tblPr` (style, width, layout) + `w:tblGrid` (column widths) + `w:tr` > `w:tc` > `w:p`. Every cell holds at least one paragraph.
 
 ## Units
 
@@ -52,31 +50,31 @@ A table is `w:tbl` > `w:tblPr` (style, width, layout) + `w:tblGrid` (column widt
 | eighth-point | border widths (`w:sz` on borders) | 8 per point |
 | EMU (914400/in) | drawing extents | 914400 per inch |
 
-A Letter page is 12240×15840 twips. Text width = page width − left − right margins (default 9360 twips with 1in margins).
+A Letter page is 12240×15840 twips. Text width = page width − left − right margins (9360 twips at 1in margins).
 
 ## Styles
 
-`w:style` with `w:type` of `paragraph`, `character`, `table` or `numbering`. Attributes: `w:styleId` (the internal name), `w:name` (the UI name), `w:basedOn`, `w:next`, `w:link`, plus `w:pPr`/`w:rPr`.
+`w:style` with `w:type` of `paragraph`, `character`, `table` or `numbering`; attributes `w:styleId` (internal name), `w:name` (UI name), `w:basedOn`, `w:next`, `w:link`, plus `w:pPr` / `w:rPr`.
 
-- `Normal` is the root; `Heading1`..`Heading9` drive the outline level and the TOC.
-- Outline level can also be set explicitly with `w:outlineLvl` (0-based) in `pPr`; a paragraph can look like a heading without being one, and the TOC will not see it.
+- `Normal` is the root; `Heading1`..`Heading9` drive outline level and the TOC.
+- `w:outlineLvl` (0-based) in `pPr` sets an outline level explicitly: a paragraph can look like a heading without being one, and the TOC will not see it.
 - Latent styles do not exist in the file until used; a document may reference `Heading3` while `styles.xml` has no definition for it.
 
 ## Numbering
 
-`word/numbering.xml` holds `w:abstractNum` (the list definition, per level: format, text, indentation) and `w:num` (`w:numId` → `w:abstractNumId`, optionally overridden). A paragraph joins a list with `w:numPr` referencing a `numId`. Two paragraphs with the same `numId` share a counter.
+`word/numbering.xml` holds `w:abstractNum` (list definition: per level its format, text and indentation) and `w:num` (`w:numId` → `w:abstractNumId`, optionally overridden). A paragraph joins a list with `w:numPr` referencing a `numId`; two paragraphs with the same `numId` share a counter.
 
 ## Sections
 
-`w:sectPr` carries page size (`w:pgSz`), margins (`w:pgMar`), orientation (implied by width vs height, or `w:orient`), columns, and the header/footer references. A document with one section has one `sectPr`; a new section is a paragraph whose `pPr` contains the *previous* section's `sectPr`.
+`w:sectPr` carries page size (`w:pgSz`), margins (`w:pgMar`), orientation (implied by width vs height, or `w:orient`), columns and header/footer references. A single-section document has one `sectPr`; a new section is a paragraph whose `pPr` contains the *previous* section's `sectPr`.
 
 ## Fields
 
-Simple (`w:fldSimple`) and complex (`fldChar` begin/separate/end with `w:instrText`). The visible text is a cache. `w:updateFields` in `settings.xml` asks the editor to refresh on open. See `ooxml/hyperlinks_and_fields.md`.
+Simple (`w:fldSimple`) and complex (`fldChar` begin/separate/end with `w:instrText`). The visible text is a cache; `w:updateFields` in `settings.xml` asks the editor to refresh on open. See `ooxml/hyperlinks_and_fields.md`.
 
 ## Revision markup
 
-`w:ins`, `w:del` (with `w:delText`), `w:moveFrom`/`w:moveTo`, `w:rPrChange`/`w:pPrChange`, each with author and date. See `ooxml/tracked_changes.md`.
+`w:ins`, `w:del` (with `w:delText`), `w:moveFrom` / `w:moveTo`, `w:rPrChange` / `w:pPrChange`, each with author and date. See `ooxml/tracked_changes.md`.
 
 ## Minimum valid package
 

package/assets/skills/office-documents/references/template-elicitation.md

@@ -1,19 +1,17 @@
 # Eliciting a template
 
-A user who says "use our house style" has a file somewhere. Getting it is worth one question; guessing produces a document that has to be redone.
+A user who says "use our house style" has a file somewhere. One question gets it; guessing produces a document that has to be redone.
 
 ## Ask for the artefact, not the description
 
-Description ("blue headings, maybe 11pt") produces a different document every time. The artefact (`house-template.dotx`, an old `.docx` of the same kind, a PDF of the last report) carries the actual styles, margins and fonts.
-
-One sentence is enough:
+A description ("blue headings, maybe 11pt") produces a different document every time. The artefact (`house-template.dotx`, an old `.docx` of the same kind, a PDF of the last report) carries the actual styles, margins and fonts.
 
 > Is there an existing document in this style I should match? Send the file (`.dotx`, or any `.docx` in that style) and I will follow it exactly.
 
-If they have no file, ask for two or three specifics that cannot be guessed and choose the rest from `SKILL.md` defaults:
+With no file, ask for two or three specifics that cannot be guessed and take the rest from `SKILL.md` defaults:
 
-- page size and margins, if their organisation is not US Letter,
-- the heading/body typeface and sizes,
+- page size and margins, if the organisation is not US Letter,
+- heading and body typeface and sizes,
 - anything required by policy (logo in the header, classification mark in the footer).
 
 ## Read the template before using it
@@ -24,7 +22,7 @@ If they have no file, ask for two or three specifics that cannot be guessed and
 "<python>" "<skill>/scripts/section_audit.py" "<template.docx>"
 ```
 
-From `styles.xml`, note the `styleId` of what will be used: `Heading1`..`Heading3`, `Title`, `Caption`, `Quote`, `ListParagraph`. From the section audit, record page size, margins, header/footer text and whether the first page is different.
+From `styles.xml`, note the `styleId` of what will be used: `Heading1`..`Heading3`, `Title`, `Caption`, `Quote`, `ListParagraph`. From the section audit, record page size, margins, header and footer text, and whether the first page is different.
 
 ## Apply it
 
@@ -32,18 +30,18 @@ From `styles.xml`, note the `styleId` of what will be used: `Heading1`..`Heading
 "<python>" "<skill>/scripts/apply_template_styles.py" --template "<template.docx>" --target "<draft.docx>" --out "<styled.docx>"
 ```
 
-This merges style definitions (and numbering) by id — the body content is untouched, so anything written with direct formatting keeps it. Follow with:
+Merges style definitions (and numbering) by id; the body content is untouched, so anything written with direct formatting keeps it. Then:
 
 ```bash
-"<python>" "<skill>/scripts/style_normalize.py" "<styled.docx>" --out "<styled-final.docx>" --clear_paragraph_format --enforce_heading_spacing
+"<python>" "<skill>/scripts/style_normalize.py" "<styled.docx>" --out "<styled-final.docx" --clear_paragraph_format --enforce_heading_spacing
 ```
 
-Now the text picks up the template's look instead of the draft's.
+The text now picks up the template's look instead of the draft's.
 
 ## When the template is a PDF or an image
 
-Extract structure, not styles: heading hierarchy, section order, table layout, caption convention, margin proportions. Then reproduce them with named styles in a generated document. Say which parts were matched approximately — a PDF does not tell you the font size of a heading, only how it looks.
+Extract structure, not styles: heading hierarchy, section order, table layout, caption convention, margin proportions. Reproduce them with named styles in a generated document. Say which parts were matched approximately — a PDF does not reveal a heading's font size, only how it looks.
 
 ## When there is no template and no details
 
-Fall back to the defaults in `SKILL.md` (Letter, 1in margins, 11–12pt body, black headings, `#D9D9D9` table borders) and state the assumption in one line with the delivered file. Do not stall on a question the user may not care about.
+Fall back to the `SKILL.md` defaults (Letter, 1in margins, 11–12pt body, black headings, `#D9D9D9` table borders) and state the assumption in one line with the delivered file. Do not stall on a question the user may not care about.

package/assets/skills/office-documents/references/writing-quality.md

@@ -1,49 +1,49 @@
 # Writing quality
 
-Content quality is the part of a document the format cannot fix. These are the rules to apply while drafting, before any rendering.
+Content quality is the part of a document the format cannot fix. Apply these rules while drafting, before any rendering.
 
 ## Structure before prose
 
-- Every heading states a claim the reader can disagree with ("Services carried the quarter", not "Services"). A heading that only names a topic is a missed opportunity to be clear.
+- Every heading states a claim the reader can disagree with ("Services carried the quarter", not "Services").
 - A section that cannot be summarised in one sentence is two sections.
-- Three levels of heading is the practical maximum; a fourth usually means the content should be a table or an appendix.
-- Nothing between a heading and its first paragraph. No label line, no restated title.
+- Three heading levels is the practical maximum; a fourth means the content wants a table or an appendix.
+- Nothing between a heading and its first paragraph — no label line, no restated title.
 
 ## Paragraphs
 
-- One idea per paragraph, first sentence carries it.
-- 3–6 sentences is the comfortable range; a 1600-word paragraph is a formatting defect even if the prose is good.
-- No em-dash pile-ups, no "furthermore/moreover" chains, no sentence that only announces the next sentence.
-- The last paragraph of a section says what it meant, not that it is finished.
+- One idea per paragraph, carried by the first sentence.
+- 3–6 sentences is comfortable; a 1600-word paragraph is a formatting defect even when the prose is good.
+- No em-dash pile-ups, no "furthermore/moreover" chains, no sentence that only announces the next one.
+- The last paragraph of a section says what the section meant, not that it is finished.
 
 ## Lists and tables
 
 - Bullets for parallel items of equal weight; never for a sequence (that is a numbered list).
-- If items have two attributes, a table beats a bulleted list with parentheticals.
-- Table headers are nouns, units in the header ("Revenue ($m)"), numbers right-aligned.
+- Items with two attributes belong in a table, not a bulleted list with parentheticals.
+- Table headers are nouns with units ("Revenue ($m)"); numbers right-aligned.
 - Every table earns its caption; a table without a purpose is a screenshot of data.
 
 ## Voice
 
-- Active unless the actor is unknown or unimportant; "We found", not "It was found".
+- Active unless the actor is unknown or unimportant: "We found", not "It was found".
 - Present tense for findings, past for actions taken.
-- No unsupported superlatives. "18% growth" beats "strong growth"; if a number is unknown, say so rather than adding an adverb.
-- Define an acronym once, then use it. Never define it twice in different places.
+- No unsupported superlatives: "18% growth" beats "strong growth"; if the number is unknown, say so instead of adding an adverb.
+- Define an acronym once, then use it; never redefine it elsewhere.
 
 ## Numbers
 
-- Consistent precision. Do not mix "12.4%" and "8%" in one table unless the source did.
+- Consistent precision: do not mix "12.4%" and "8%" in one table unless the source did.
 - Percentages below 1 take a leading zero (0.4%, not .4%).
-- State the period and the currency in the table or its caption, not in the surrounding prose.
-- A number in prose must match the number in the table; rendering does not catch this, re-reading does.
+- State period and currency in the table or its caption, not in surrounding prose.
+- A prose number must match the table number; rendering does not catch this, re-reading does.
 
 ## What to cut
 
-- Opening paragraphs that explain that the document will explain something.
-- Closing paragraphs that thank the reader.
+- Opening paragraphs explaining that the document will explain something.
+- Closing paragraphs thanking the reader.
 - Bold on every second phrase: emphasis used everywhere is emphasis used nowhere.
-- Sentences that begin "It is important to note that".
+- Sentences beginning "It is important to note that".
 
 ## Where this connects
 
-`references/docx-structure.md` covers how the structure is expressed in Word — styles, captions, table layout. `tasks/verify_render.md` covers checking the result on a page. Neither replaces reading the text once with the question "would a busy reader get the point from the headings alone?"
+`references/docx-structure.md` covers how structure is expressed in Word — styles, captions, table layout. `tasks/verify_render.md` covers checking the result on a page. Neither replaces reading the text once asking whether a busy reader would get the point from the headings alone.

package/assets/skills/office-documents/scripts/add_tracked_replacements.py

@@ -137,9 +137,10 @@ def main(argv: list[str] | None = None) -> int:
             print("error: %s" % exc, file=sys.stderr)
             return 2
         hits = 0
-        for paragraph in doc.paragraphs():
-            if tracked_replace(paragraph, old, new, args.author, stamp, counter):
-                hits += 1
+        for part in doc.text_parts():
+            for paragraph in doc.paragraphs(part):
+                if tracked_replace(paragraph, old, new, args.author, stamp, counter):
+                    hits += 1
         applied.append({"old": old, "new": new, "paragraphs": hits})
 
     settings = doc.xml("word/settings.xml")