dsh-office-kit 0.4.2 → 0.4.4

package/assets/skills/office-documents/tasks/comments_manage.md

@@ -1,8 +1,6 @@
 # Comments
 
-**Goal.** Add a review comment, read the comments someone else left, reply or resolve them, and remove comments before the document goes out.
-
-Comments are not text: each one is a `w:comment` in `word/comments.xml`, anchored in the body by a `w:commentRangeStart` / `w:commentRangeEnd` pair plus a `w:commentReference` run. Editing the anchor without the comments part (or the reverse) leaves a document Word reports as corrupt.
+Add, read, reply to, resolve or remove review comments. A comment is not text: each is a `w:comment` in `word/comments.xml`, anchored by a `w:commentRangeStart` / `w:commentRangeEnd` pair plus a `w:commentReference` run. Editing the anchor without the comments part, or the reverse, leaves a file Word reports as corrupt.
 
 ## Add
 
@@ -11,7 +9,7 @@ Comments are not text: each one is a `w:comment` in `word/comments.xml`, anchore
   --author "Review" --add "Renewals=Check the source of this claim" --add "42 new accounts=Who verified this?"
 ```
 
-Each `--add` is `NEEDLE=COMMENT`. The needle is matched inside a paragraph; the anchored range covers exactly the matched text, so pick a distinctive phrase. `--ignore_case` relaxes matching, `--require_all` writes nothing and exits 1 if any needle is missing — use it when the comment set must be complete.
+Each `--add` is `NEEDLE=COMMENT`, matched inside a paragraph; the anchored range covers exactly the matched text, so pick a distinctive phrase. `--ignore_case` relaxes matching; `--require_all` writes nothing and exits 1 if any needle is missing — for comment sets that must be complete.
 
 ## Extract
 
@@ -19,7 +17,7 @@ Each `--add` is `NEEDLE=COMMENT`. The needle is matched inside a paragraph; the
 "<python>" "<skill>/scripts/comments_extract.py" "<file.docx>" --out "<comments.json>"
 ```
 
-Returns `id`, `author`, `initials`, `date`, `text`, `anchored_text`, `part` and `resolved`. An empty array means the file has no comments — do not assume comments exist because the user mentioned them.
+Returns `id`, `author`, `initials`, `date`, `text`, `anchored_text`, `part` and `resolved`. An empty array means the file has no comments; do not assume they exist because the user mentioned them.
 
 ## Patch or resolve
 
@@ -45,15 +43,15 @@ Returns `id`, `author`, `initials`, `date`, `text`, `anchored_text`, `part` and
 "<python>" "<skill>/scripts/comments_strip.py" "<file.docx>" --out "<file-clean.docx>"
 ```
 
-Removes every anchor, drops `word/comments.xml`, its relationship and content-type override. Removing comments is required before sharing a file with a customer; check `privacy_scrub_metadata.md` too.
+Removes every anchor and drops `word/comments.xml` with its relationship and content-type override. Required before sharing a file with a customer; see also `privacy_scrub_metadata.md`.
 
 ## Verify
 
-`comments_extract.py` on the output (count and anchors), then render the page the comment sat on — a stripped anchor that leaves an empty run can show as a stray space.
+`comments_extract.py` on the output (count and anchors), then render the page the comment sat on: a stripped anchor that leaves an empty run can show as a stray space.
 
 ## Pitfalls
 
-- A comment anchored to a paragraph mark rather than text shows no `anchored_text`; that is normal for "comment on the whole paragraph".
-- Two comments cannot share an id. `comments_add.py` continues from the highest existing id.
-- The comment body is ordinary paragraphs, so a long comment can contain several; `comments_extract.py` joins them with newlines.
-- Replying in-thread needs Word's `commentsExtended` part. Anchoring a new comment on the same phrase is the portable equivalent.
+- A comment anchored to a paragraph mark rather than to text shows no `anchored_text` — normal for "comment on the whole paragraph".
+- Two comments cannot share an id; `comments_add.py` continues from the highest existing id.
+- The body is ordinary paragraphs, so a long comment can hold several; `comments_extract.py` joins them with newlines.
+- Threaded replies need Word's `commentsExtended` part; anchoring a new comment on the same phrase is the portable equivalent.

package/assets/skills/office-documents/tasks/compare_diff.md

@@ -1,40 +1,34 @@
 # Compare two versions
 
-**Goal.** Say what actually changed between two files, with evidence — not "the text differs somewhere".
+Two comparisons answer different questions: text-level (which words changed) and page-level (what the reader sees). A style-definition change can leave every word identical and move every paragraph.
 
-Two useful comparisons: text-level (what words changed) and page-level (what the reader sees changed). Use both; a change in a style definition can leave the text identical and move every paragraph.
-
-## Page-level diff
+## Page-level
 
 ```bash
 "<python>" "<skill>/scripts/render_and_diff.py" "<before.docx>" "<after.docx>" --outdir "<render-dir>" --dpi 120
 ```
 
-Renders both through the helper CLI, pairs the pages, and writes `diff-NN.png` coloured by pixel difference. Reports which pages changed, the fraction of pixels differing, and a page-count delta.
-
-The exit code is 3 when no renderer is available: render both files another way, or compare text only and say which comparison you could not run.
+Renders both files through the helper CLI, pairs pages, writes `diff-NN.png` coloured by pixel difference, and reports changed pages, the fraction of differing pixels and the page-count delta. Exit code 3 means no renderer: render another way, or compare text only and say which comparison you could not run.
 
-## Text-level diff
+## Text-level
 
 ```bash
 "<python>" "<skill>/scripts/docx_kit.py" text '<before.docx>' > before.json
 "<python>" "<skill>/scripts/docx_kit.py" text '<after.docx>'  > after.json
 ```
 
-Diff the two paragraph dumps (any diff tool, or a few lines of Python). This is the reliable way to separate content changes from layout changes.
+Then diff the paragraph dumps with any diff tool or a few lines of Python. This is the reliable way to separate content from layout changes.
 
 ## Review mode versus diff mode
 
-If the user wants the *document* to carry the changes, use tracked changes (`tasks/clean_tracked_changes.md`) rather than a report: the reviewer accepts or rejects inside Word. A diff is evidence for a conversation; tracked changes are the artefact.
-
-For a version that arrived with markup, `accept_tracked_changes.py --mode report` is the change list, with reviewer names and where each edit sits.
+If the document should carry the changes, use tracked changes (`tasks/clean_tracked_changes.md`): a diff is evidence for a conversation, tracked changes are the artefact. For a version that arrived with markup, `accept_tracked_changes.py --mode report` is the change list with reviewer names and positions.
 
 ## Verify
 
-Open the diff PNGs with `read_image` and look at them: a coloured block on a page that should not have changed usually means a font substitution or a margin change, not a content change. Cross-check with the text diff before writing a conclusion.
+Open the diff PNGs with `read_image`. A coloured block on a page that should not change usually means font substitution or a margin change — cross-check the text diff before concluding.
 
 ## Pitfalls
 
-- Different renderers paginate differently; compare renders made by the same renderer and the same settings.
-- Metadata and revision ids differ between saves and never appear on a page — a text diff of `word/document.xml` is noisy for that reason.
-- An image replaced in place keeps the same relationship and page position; only a pixel comparison notices.
+- Different renderers paginate differently; compare with the same renderer and settings.
+- Metadata and revision ids differ between saves and never appear on a page, so a raw `word/document.xml` diff is mostly noise.
+- An image replaced in place keeps its relationship and position — only a pixel comparison notices.

package/assets/skills/office-documents/tasks/create_edit.md

@@ -1,6 +1,6 @@
 # Create or edit a document
 
-**Goal.** Produce a `.docx` that opens cleanly in Word, with real heading styles, real lists and real tables, then change it later without destroying what is already there.
+Produce a `.docx` that opens cleanly in Word with real heading styles, lists and tables — and change it later without destroying what is there.
 
 ## Create
 
@@ -35,7 +35,7 @@ The command prints counts for headings, paragraphs, list items, tables, images a
 
 ## Edit
 
-The helper CLI does not mutate documents. Every edit is a script that reads the original, writes a copy, and refuses to overwrite its input. Omit `--out` and the copy lands next to the source as `<name>-edited.docx`.
+The helper CLI never mutates a document: every edit reads the original, writes a copy, and refuses to overwrite its input. Without `--out` the copy lands next to the source as `<name>-edited.docx`.
 
 Replace text — body, tables, and every header and footer:
 
@@ -44,7 +44,7 @@ Replace text — body, tables, and every header and footer:
   --find "18%" --replace "21%" --find "Hardware flat" --replace "Hardware steady"
 ```
 
-`--find` / `--replace` are paired in order; `--spec edits.json` takes `{"replace": [{"find": "...", "replace": "..."}]}` instead. The command prints a per-pair count. A match inside one run keeps that run's formatting; a match that straddles runs collapses the paragraph into its first run, so keep needles inside a single styled span when mixed formatting matters. `--require-all` exits 1 if a pair matched nothing, which is the check you want for a scripted edit.
+`--find` / `--replace` pair up in order; `--spec edits.json` takes `{"replace": [{"find": "...", "replace": "..."}]}` instead. The command prints a count per pair. A match inside one run keeps that run's formatting; a match straddling runs collapses the paragraph into its first run, so keep needles inside a single styled span when formatting matters. `--require-all` exits 1 if a pair matched nothing — the check for a scripted edit.
 
 Append blocks — the same block types `docx create` accepts:
 
@@ -56,26 +56,24 @@ Append blocks — the same block types `docx create` accepts:
 [{ "type": "heading", "level": 1, "text": "Appendix" }, { "type": "table", "headers": ["Region", "Revenue"], "rows": [["EMEA", "4.1M"]] }]
 ```
 
-`--spec` takes a full document spec and appends its `blocks` array. The builder is the CLI's own, so anything that works in `docx create` works here, including images (`path`, `width`) and equations (`latex`).
+`--spec` takes a full document spec and appends its `blocks` array. The builder is the CLI's own, so anything that works in `docx create` works here, images (`path`, `width`) and equations (`latex`) included.
 
 Set properties:
 
 ```bash
-"<python>" "<skill>/scripts/core_properties.py" --input "<original.docx>" --out "<original-edited.docx>" \
+"<python>" "<skill>/scripts/core_properties.py" --input "<original.docx>" --out "<original-edited.docx" \
   --title "Regional revenue review (final)" --author "Finance" --keywords "revenue, FY26"
 ```
 
-`--show` reports the current properties without writing; the same names work in `--spec core.json` under a `core` object.
-
-Three independent scripts means a pipeline writes an intermediate copy (append, then properties). That is deliberate: each step is re-runnable and its output is a valid document you can inspect.
+`--show` reports the current properties without writing; the same names work in `--spec core.json` under a `core` object. Each step writes a valid document, so a pipeline is append, then properties, and every stage is re-runnable and inspectable.
 
 ## When the CLI is not enough
 
 | Need | Route |
 |---|---|
-| Edit inside a header, footer, footnote or comment | `scripts/docx_kit.py xml <file> <part>` to inspect, then the snippet below or a purpose script |
-| Mark edits as tracked changes | `scripts/add_tracked_replacements.py`, `tasks/clean_tracked_changes.md` |
-| Header date, footer page numbers, first hyperlink | `scripts/docx_ooxml_patch.py` |
+| Edit inside a header, footer, footnote or comment | `docx_kit.py xml <file> <part>` to inspect, then the snippet below |
+| Mark edits as tracked changes | `add_tracked_replacements.py` (`tasks/clean_tracked_changes.md`) |
+| Header date, footer page numbers, first hyperlink | `docx_ooxml_patch.py` |
 | Replace a paragraph but keep its formatting | `python-docx` snippet below |
 
 ```bash
@@ -93,15 +91,15 @@ d.save(r"<file-edited.docx>")
 PY
 ```
 
-Editing `w:t` text directly (via `docx_kit`) is safe for plain word swaps; anything that changes paragraph structure should go through `python-docx` so the surrounding XML stays consistent.
+Plain word swaps can edit `w:t` through `docx_kit` directly; anything that changes paragraph structure goes through `python-docx` so the surrounding XML stays consistent.
 
 ## Verify
 
-`docx read` to confirm text and counts, then render and look at every page (`tasks/verify_render.md`). A spec that produces three pages instead of two means the table or margins need work, not that the renderer is wrong.
+`docx read` to confirm text and counts, then render every page (`tasks/verify_render.md`). A spec that produces three pages instead of two means the table or margins need work, not that the renderer is wrong.
 
 ## Pitfalls
 
-- Deleting and retyping a heading loses its outline level; edit the text, keep the style.
+- Deleting and retyping a heading loses its outline level; edit the text and keep the style.
 - `append_blocks.py` inserts before the final section properties, so a trailing landscape section or page setup keeps working.
-- Replacing text that lives in a field result changes only the cached value; the field recalculates on open in Word.
-- Copying content between documents by hand drops styles and relationships — use `scripts/merge_docx_append.py`.
+- Replacing text in a field result changes only the cached value; the field recalculates on open in Word.
+- Copying content between documents by hand drops styles and relationships — use `merge_docx_append.py`.

package/assets/skills/office-documents/tasks/equations.md

@@ -1,59 +1,48 @@
 # Equations
 
-**Goal.** Displayed mathematics that Word treats as maths: selectable, reflowable, editable — not a picture and not italic text.
-
-Word stores native equations as OMML inside `m:oMathPara`/`m:oMath`. The helper CLI converts LaTeX to OMML on creation; a picture of an equation cannot be edited by the user and scales badly.
+Word stores native equations as OMML inside `m:oMathPara`/`m:oMath`. The CLI converts LaTeX to OMML on creation. A picture of an equation cannot be edited and scales badly.
 
 ## Create
 
-```bash
-"<python>" "<cli>" docx create --spec "<spec.json>" --out "<out.docx>"
-```
+`docx create --spec` block:
 
 ```json
-{
-  "blocks": [
-    { "type": "heading", "level": 1, "text": "Model" },
-    { "type": "equation", "latex": "E = mc^2" },
-    { "type": "equation", "latex": "\\frac{a^2+b^2}{c^2}" }
-  ]
-}
+{ "type": "equation", "latex": "\\frac{a^2+b^2}{c^2}" }
 ```
 
-The command reports `equations` and `equation_fallbacks`. Non-zero fallbacks mean some expression was emitted as italic text because the converter could not handle it — check the counter, then simplify the LaTeX (the converter covers fractions, superscripts, subscripts, roots, sums, Greek letters and common operators).
+Supported: fractions, superscripts, subscripts, roots, sums, Greek letters and common operators. The command reports `equations` and `equation_fallbacks`. A non-zero `equation_fallbacks` means the expression was emitted as italic text: check the counter, then simplify the LaTeX.
 
-Displayed equations belong in their own paragraph; inline maths is ordinary runs plus OMML, which is harder to place and easy to break.
+Displayed equations belong in their own paragraph. Inline maths is ordinary runs plus OMML, harder to place and easy to break.
 
-## Check what a file contains
+## Check the contents
 
 ```bash
 "<python>" "<cli>" docx read --input "<file.docx>"
 "<python>" "<skill>/scripts/docx_kit.py" xml '<file.docx>' word/document.xml | grep -c "oMath"
 ```
 
-`oMath` in the XML is the honest test. Text that merely looks mathematical (italic Times, a slash) is not an equation and will reflow badly.
+`oMath` in the XML is the honest test; lookalike italic Times text is not an equation.
 
 ## When the converter cannot express it
 
-Build the OMML by hand for the specific construct, or split the expression: a matrix or a piecewise definition is often clearer as a small table than as one enormous formula. If neither works, render the expression as an image with a caption and tell the user it is no longer editable.
+- Build the OMML by hand for that construct.
+- Split the expression: a matrix or piecewise definition is often clearer as a small table.
+- Otherwise render it as an image with a caption and tell the user it is no longer editable.
 
-The runtime ships the `latex2mathml` and `mathml2omml` packages, so a custom snippet can produce OMML directly:
+The runtime ships `latex2mathml` and `mathml2omml`, so a custom snippet can produce OMML:
 
-```bash
-"<python>" - <<'PY'
+```python
 from latex2mathml.converter import convert
 from mathml2omml import convert as to_omml
-mathml = convert(r"\sum_{i=1}^{n} x_i")
-print(to_omml(mathml)[:200])
-PY
+print(convert(r"\sum_{i=1}^{n} x_i")[:200])
 ```
 
 ## Verify
 
-Render the page and look at the equation: fractions stacked, limits above and below the operator, Greek letters as glyphs not boxes, and the equation not clipped at the right margin. A fallback shows up as italic Latin text where a symbol should be.
+Render: fractions stacked, limits above and below, Greek glyphs instead of boxes, nothing clipped at the right margin. A fallback shows as italic Latin text.
 
 ## Pitfalls
 
-- An equation inside a table cell or a caption is legal but almost always the wrong layout decision.
-- Copying OMML between documents is safe; copying a picture of it is not.
-- Numeric labels belong in the text (`(3)` right-aligned), not inside the equation object, if the user will renumber later.
+- An equation in a table cell or caption is legal but usually wrong.
+- Copying OMML between documents is safe; copying a picture is not.
+- Numeric labels belong in the text (`(3)` right-aligned) if the user will renumber.

package/assets/skills/office-documents/tasks/fields_update.md

@@ -1,8 +1,6 @@
-# Fields and field updates
+# Update or freeze fields
 
-**Goal.** Find out what a document computes, and decide whether to keep it live or freeze it.
-
-A field is an instruction the reader's Word evaluates: `SEQ` numbers captions, `REF` repeats a bookmark, `PAGE`/`NUMPAGES` count pages, `TOC` builds the contents list, `DATE` prints today. Until Word recalculates it, the file shows a cached result — which is why a TOC in a freshly edited file can look stale.
+A field is an instruction Word evaluates: `SEQ` numbers captions, `REF` repeats a bookmark, `PAGE`/`NUMPAGES` count pages, `TOC` builds contents, `DATE` prints today. The reader sees a cached result until something recalculates.
 
 ## Inspect
 
@@ -10,35 +8,35 @@ A field is an instruction the reader's Word evaluates: `SEQ` numbers captions, `
 "<python>" "<skill>/scripts/fields_report.py" "<file.docx>" --max-examples 5
 ```
 
-Reports the instruction, whether the field is a simple (`w:fldSimple`, one attribute) or complex field (begin/separate/end runs), and the cached result. `docx_kit.py xml` shows the raw runs when the report is not enough:
+The report gives each instruction, whether the field is simple (`w:fldSimple`, one attribute) or complex (begin/separate/end runs), and the cached result. To read the raw runs yourself, dump `docx_kit.py xml` for `word/document.xml` and filter `instrText`:
 
 ```bash
 "<python>" "<skill>/scripts/docx_kit.py" xml '<file.docx>' word/document.xml | grep -o 'instrText[^<]*' | head
 ```
 
-## Freeze a field to its current value
+## Freeze
 
 ```bash
 "<python>" "<skill>/scripts/fields_materialize.py" "<file.docx>" --out "<file-static.docx>" --only SEQ REF
-"<python>" "<skill>/scripts/flatten_ref_fields.py" "<file.docx>" --out "<file-static.docx>"
+"<python>" "<skill>/scripts/flatten_ref_fields.py" "<file.docx>" --out "<file-static.docx"
 ```
 
-Materialising replaces the field span with one run holding the cached text, keeping the run formatting. `flatten_ref_fields.py` is the narrow version for `REF` and `PAGEREF` only.
+Materialising replaces the field span with one run holding the cached text and keeps the run formatting. `flatten_ref_fields.py` is the narrower tool for `REF`/`PAGEREF` only.
+
+Freeze when a reader must see exactly this number, when the target bookmark is about to be deleted, or when a downstream tool mangles fields. Keep fields live when the document will be edited again: a frozen caption number stops following its table.
 
-Freeze when: the document is going to a reader who must see exactly this number, the target bookmark is being deleted, or a downstream tool mangles fields. Keep it live when the document will be edited again — a frozen caption number stops following its table.
+## Keep fields live
 
-## Keep it live
+Set `w:updateFields val="true"` in `word/settings.xml`; `insert_toc.py` does it for a new TOC, and you add the element yourself otherwise — the first open then prompts the user. LibreOffice and the renderer also refresh fields, so a stale cached value usually means the document was never recalculated, not that fields are broken.
 
-- Word recalculates on open when `w:updateFields val="true"` is set in `word/settings.xml`. `insert_toc.py` sets it for a new TOC; if you need it for an existing file, add the element yourself and tell the user the first open will prompt.
-- LibreOffice and the renderer also refresh fields; a stale cached value in a preview usually means the field was never recalculated, not that the field is broken.
-- `insert_ref_fields.py` converts `[[REF:bookmark]]` placeholders into real `REF` fields, which is the reliable way to build cross-references after restructuring.
+`insert_ref_fields.py` converts `[[REF:bookmark]]` placeholders into real REF fields — the reliable way to build cross-references after a restructure.
 
 ## Verify
 
-`fields_report.py` after the change: frozen fields disappear from the report, live ones keep their instruction. Render and read the page to confirm the number the reader sees.
+Run `fields_report.py` again: frozen fields disappear from the report, live ones keep their instruction. Then render or read the page.
 
 ## Pitfalls
 
 - A field split across paragraphs is invalid; keep begin/separate/end together.
-- `w:fldSimple` and complex fields both appear in the report — do not assume the absence of `w:fldSimple` means there are no fields.
-- Copying a field to another document copies the instruction but not the bookmark it refers to; recreate it there.
+- Both `w:fldSimple` and complex fields appear in the report; handle both.
+- Copying a field copies the instruction but not its bookmark.

package/assets/skills/office-documents/tasks/fixtures_edge_cases.md

@@ -1,8 +1,8 @@
-# Fixtures and edge cases
+# Fixtures for edge cases
 
-**Goal.** Have a file that contains the awkward cases *before* you are asked to handle them, so a fix is tested against a 1600-word paragraph and not only against clean prose.
+Build a file containing the awkward cases before being asked to handle them: a fix proven on clean prose may still mangle a 1600-word paragraph.
 
-## Build the fixture set
+## Build
 
 ```bash
 "<python>" "<skill>/scripts/make_fixtures.py" --outdir "<work-dir>" --only all
@@ -10,41 +10,27 @@
 
 Writes:
 
-| File | Contains |
-|---|---|
-| `tracked.docx` | A replacement as real `w:del`+`w:ins` markup, tracking switched on |
-| `watermark.docx` | A DRAFT watermark in the header |
-| `comments.docx` | One anchored comment in `word/comments.xml` |
-| `edge_cases.docx` | Empty paragraph, H1 to H3 jump, 1600-word paragraph, email and phone, 2×10 unstyled table, image with no alt text |
+- `tracked.docx` — a replacement as real `w:del`+`w:ins`, tracking on.
+- `watermark.docx` — a DRAFT watermark in the header.
+- `comments.docx` — one anchored comment in `word/comments.xml`.
+- `edge_cases.docx` — an empty paragraph, an H1→H3 jump, a 1600-word paragraph, an email and a phone number, a 2×10 unstyled table, and an image with no alt text.
 
-`--only tracked|watermark|comments|edge` builds one.
+`--only tracked|watermark|comments|edge` builds a single file. These are test inputs, not templates: never ship them.
 
-These are inputs for testing a change, not templates. Do not ship them.
+## Cases that break naive edits
 
-## The cases that break naive edits
+- **Long paragraphs.** A replacement that rebuilds the paragraph loses run formatting over thousands of characters. Check with `read_image`, not only a text dump.
+- **Nested tables.** Text inside `table > cell > table > cell` is missed by `document.paragraphs`; walk `cell.tables` or use the pack scripts.
+- **Header and footer text.** Body find-and-replace never sees it.
+- **Tables without a style.** Borders come from the renderer default and change elsewhere: apply `Table Grid` or explicit `#D9D9D9` borders.
+- **Images with no alt text.** An accessibility finding and a sign of pasted content.
+- **Manual spacing.** Empty paragraphs and spaces render differently; normalize first (`tasks/style_lint_normalize.md`).
+- **Mixed page sizes.** A landscape section in a portrait document confuses headers and footers; `section_audit.py` reports it.
 
-- **Long paragraphs** — a replacement that rebuilds the paragraph loses run formatting across thousands of characters; check the result with `read_image`, not only with a text dump.
-- **Nested tables** — text inside `table > cell > table > cell` is missed by `document.paragraphs`; walk `cell.tables` or use the pack scripts, which do.
-- **Header/footer text** — a find-and-replace over the body never sees it.
-- **Tables without a style** — borders come from the renderer default and change when the file is opened elsewhere; apply `Table Grid` or set explicit `#D9D9D9` borders.
-- **Images with no alt text** — an accessibility finding, and also a sign the image was pasted rather than placed.
-- **Manual spacing** — a document padded with empty paragraphs and spaces looks right in one renderer and wrong in the next; normalize instead (`tasks/style_lint_normalize.md`).
-- **Mixed page sizes** — a landscape section inside a portrait document confuses footers and headers; `section_audit.py` reports it.
+## Regression pass
 
-## Regression pass before delivery
-
-```bash
-for f in "<work-dir>"/*.docx; do
-  echo "== $f"
-  "<python>" "<skill>/scripts/heading_audit.py" "$f"        || true
-  "<python>" "<skill>/scripts/style_lint.py" "$f"           || true
-  "<python>" "<skill>/scripts/a11y_audit.py" "$f"           || true
-  "<python>" "<skill>/scripts/section_audit.py" "$f"        || true
-done
-```
-
-An audit that now reports nothing where it previously reported a real problem is the signal that a fix regressed. Keep the fixture out of the user's workspace; put it under the temp directory.
+Loop over `"<work-dir>"/*.docx` running `heading_audit.py`, `style_lint.py`, `a11y_audit.py` and `section_audit.py`, each with `|| true`. An audit that now reports nothing where it used to report a real problem is a regression. Keep fixtures under the temp directory, out of the user's workspace.
 
 ## Verify
 
-Whatever the script produced, render it. Fixtures exist to be looked at: a 1600-word paragraph and a table that is too wide both fail visually first.
+Render whatever the script produced — fixtures exist to be looked at. The long paragraph and the too-wide table fail visually first.

package/assets/skills/office-documents/tasks/footnotes_endnotes.md

@@ -1,18 +1,16 @@
 # Footnotes and endnotes
 
-**Goal.** Attach a reference note at exactly one place in the text, and keep the note body in the notes part rather than in the body.
+Notes live outside the text flow: `word/footnotes.xml` (or `word/endnotes.xml`) holds the note text, a `w:footnoteReference w:id="N"` run in the body points at it, and the part needs the separator notes (ids -1 and 0) or Word repairs the file.
 
-Notes live outside the flow: `word/footnotes.xml` (or `word/endnotes.xml`) holds the text, and a `w:footnoteReference w:id="N"` run in the body points at it. The part also needs the separator notes (ids -1 and 0) or Word repairs the file.
+## Insert
 
-## Insert a note
-
-Put a marker where the reference belongs, then convert it:
+Put a marker where the reference belongs, then run:
 
 ```bash
-"<python>" "<skill>/scripts/insert_note.py" "<file.docx>" --kind footnote --text "Source: ledger extract, June." --out "<file-notes.docx>"
+"<python>" "<skill>/scripts/insert_note.py" "<file.docx>" --kind footnote --text "Source: ledger extract, June." --out "<file-notes.docx"
 ```
 
-The marker defaults to `[[NOTE]]`; change it with `--marker`. The script creates the notes part (with separator and continuation-separator entries) if it does not exist, allocates the next free id, splits the surrounding run so only the marker is replaced by the reference, and styles the note text with `FootnoteText` and the reference with `FootnoteReference`. `--kind endnote` writes to the endnotes part instead.
+The marker defaults to `[[NOTE]]` (`--marker`). The script creates the notes part with separator and continuation-separator entries when they are missing, allocates the next free id, splits the surrounding run so only the marker is replaced, and styles the note text `FootnoteText` and the reference `FootnoteReference`. `--kind endnote` writes the endnotes part instead.
 
 ## Report
 
@@ -20,19 +18,19 @@ The marker defaults to `[[NOTE]]`; change it with `--marker`. The script creates
 "<python>" "<skill>/scripts/footnotes_report.py" "<file.docx>"
 ```
 
-Lists each note's text, how many references point at it, and which references dangle or which notes are orphaned. Orphans appear when content is copied between documents; dangling references appear when a note is deleted but its marker stays.
+Lists each note's text and reference count, dangling references (note deleted, marker kept) and orphaned notes (no reference — usually copied content).
 
 ## Renumbering
 
-Note ids are numbers, but Word displays them sequentially by position, so inserting a note in the middle renumbers the rest automatically. Do not try to keep ids in display order — keep them unique.
+Ids are numbers, but Word displays notes sequentially by position, so inserting in the middle renumbers automatically. Keep ids unique, not in display order.
 
 ## Verify
 
-Render the page with the note and read the note area: the marker should sit immediately after the word it annotates, with no space before it, and the note text should match. Also check the last page — an endnote section that lands after the signature block is a layout defect.
+Render the page with the note. The marker sits immediately after the word it annotates, with no space before it, and the note text matches. Check the last page too: an endnote section after the signature block is a layout defect.
 
 ## Pitfalls
 
-- A footnote reference inside a table cell is allowed; inside a header it is not.
-- Copying a paragraph with `python-docx` copies the reference but not the note body — recreate the note in the target document.
-- Deleting note text without deleting the reference leaves a broken document that opens with a repair prompt.
-- Field instructions are not allowed in the note separator; keep the built-in separator notes untouched.
+- A footnote reference is allowed in a table cell, not in a header.
+- Copying a paragraph with python-docx copies the reference but not the note body.
+- Deleting note text without its reference leaves a repair prompt.
+- Field instructions are not allowed in the note separator; leave the built-in separators untouched.

package/assets/skills/office-documents/tasks/forms_content_controls.md

@@ -1,48 +1,44 @@
-# Forms and content controls
+# Content controls (form fields)
 
-**Goal.** Fill or create a structured field — a name, a date, a choice — as a real content control, so the value is labelled in the XML instead of being plain text between two labels.
+A content control is a `w:sdt` with a `w:sdtPr` (tag, alias, id, type) and a `w:sdtContent`. The tag is the machine name; the alias is what Word shows in the properties panel.
 
-A content control is `w:sdt` with `w:sdtPr` (tag, alias, id, type) and `w:sdtContent`. The tag is the machine name; the alias is what Word shows in the properties panel.
-
-## List what exists
+## List
 
 ```bash
 "<python>" "<skill>/scripts/content_controls.py" list "<file.docx>"
 ```
 
-Reports each control's part, tag, alias, id, type and current text, across the body, headers and footers. `--no_headers_footers` limits it to the body.
+Reports part, tag, alias, id, type and current text across the body, headers and footers. `--no_headers_footers` limits the scan to the body.
 
 ## Create
 
 ```bash
-"<python>" "<skill>/scripts/content_controls.py" create "<file.docx>" \
-  --placeholder "Client name" --tag client_name --alias "Client name" --out "<file-form.docx>"
+"<python>" "<skill>/scripts/content_controls.py" create "<file.docx>" --placeholder "Client name" --tag client_name --alias "Client name" --out "<file-form.docx"
 ```
 
-The script wraps the paragraph containing the placeholder text (or appends a new one) in a `w:sdt`, so the field is a drop-in replacement for a typed placeholder line. `--json` prints the created control instead of a summary.
+Wraps the paragraph containing the placeholder text (or appends one) in a `w:sdt`, so the field is a drop-in replacement for a typed placeholder line. `--json` prints the created control.
 
 ## Fill
 
 ```bash
-"<python>" "<skill>/scripts/content_controls.py" set "<file-form.docx>" \
-  --set client_name="Northwind" --set period="Q2 FY26" --out "<file-filled.docx>"
+"<python>" "<skill>/scripts/content_controls.py" set "<file-form.docx>" --set client_name="Northwind" --set period="Q2 FY26" --out "<file-filled.docx"
 ```
 
-`--set TAG=VALUE` matches on the tag. The command exits 1 and lists `missing_tags` when a tag is not present — that is the check for a scripted fill, so a typo does not silently write nothing.
+`--set TAG=VALUE` matches on the tag. It exits 1 and lists `missing_tags` when a tag is absent — the check for a scripted fill.
 
 ## Design
 
-- One control per value; do not put a whole table into one control.
-- Tag in `snake_case`, alias in the user's words.
-- A choice control lists its options in `w:sdtPr`; a date control has `w:date` with a format. Plain text is the default and the safest thing to generate.
-- Leave the surrounding labels in the body text; the alias is visible only in Word's properties panel.
+- One control per value, not one per table.
+- Tag `snake_case`, alias in the user's words.
+- A choice control lists options in `w:sdtPr`; a date control has `w:date` with a format; plain text is the default and safest.
+- Leave surrounding labels in body text: the alias is visible only in Word's properties panel.
 
 ## Verify
 
-`content_controls.py list` after filling: tags present with the expected text. Then render — a control's content is normal text on the page, so the visual check is that nothing shifted and the filled value fits its line.
+`content_controls.py` `list` after filling (tags present with the expected text), then render. A control is ordinary text on the page, so check that nothing shifted and the filled value fits its line.
 
 ## Pitfalls
 
-- Deleting an `sdt` wrapper while trying to "clear" a field deletes the value and the structure; set the text instead.
-- Two controls with the same tag make `--set` ambiguous; the script updates the first and reports the rest.
-- A content control cannot span two paragraphs without `w:sdtContent` holding both — keep one value per paragraph when generating.
+- Deleting the `sdt` wrapper to clear a field deletes value and structure; set the text instead.
+- Two controls with the same tag make `--set` ambiguous: it updates the first and reports the rest.
+- A control cannot span two paragraphs unless `w:sdtContent` holds both, so generate one value per paragraph.

package/assets/skills/office-documents/tasks/headings_numbering.md

@@ -1,8 +1,6 @@
 # Headings and numbering
 
-**Goal.** A single outline a reader can follow and Word can turn into a TOC: no skipped levels, no headings faked with bold text, consistent spacing.
-
-Heading level comes from the paragraph style (`Heading 1`…`Heading 9`, `Title` uses outline level 0), not from size or weight. `heading_audit.py` reads that structure and flags the common breakages.
+A heading level comes from the paragraph style (`Heading 1` … `Heading 9`, `Title` = outline level 0), not from size or weight.
 
 ## Audit
 
@@ -12,44 +10,41 @@ Heading level comes from the paragraph style (`Heading 1`…`Heading 9`, `Title`
 
 Findings:
 
-- `skipped_level` — a level 3 heading directly under a level 1. Fix by inserting the missing level or by promoting the deeper heading.
-- `empty_heading` — a heading with no text; a stale outline entry that will appear in the TOC as a blank line.
-- `manual_formatting` — a real heading that also carries direct bold or a large font size; the style already does that, so the extra formatting fights restyling.
-- `heading_not_styled` — body text that looks like a heading (bold, 13pt+) but is styled `Normal`. This is the expensive one: the TOC misses it and every later style change misses it.
+- `skipped_level` — L3 directly under L1: insert the missing level or promote the heading.
+- `empty_heading` — a blank line in the TOC.
+- `manual_formatting` — a real heading carrying direct bold or a large size, which fights restyling.
+- `heading_not_styled` — bold 13pt+ text in `Normal`: the TOC and every later style change miss it.
 
 ## Fix
 
-Prefer styles over direct formatting. `style_normalize.py --clear_paragraph_format --enforce_heading_spacing` strips direct run formatting and sets standard space-before/after on headings:
+Prefer real styles. To strip direct run formatting and set standard heading spacing:
 
 ```bash
-"<python>" "<skill>/scripts/style_normalize.py" "<file.docx>" --out "<file-fixed.docx>" --clear_paragraph_format --enforce_heading_spacing
+"<python>" "<skill>/scripts/style_normalize.py" "<file.docx>" --out "<file-fixed.docx" --clear_paragraph_format --enforce_heading_spacing
 ```
 
-For a heading that is only bold text, promote it to the right style rather than making it bolder:
+To promote bold text to a real heading:
 
-```bash
-"<python>" - <<'PY'
-from docx import Document
-d = Document(r"<file.docx>")
+```python
+d = Document("<file.docx>")
 for p in d.paragraphs:
     if p.text.strip() == "<exact heading text>":
         p.style = d.styles["Heading 1"]
-d.save(r"<file-fixed.docx>")
-PY
+d.save("<file-fixed.docx")
 ```
 
 ## Numbered headings
 
-Numbering is a numbering definition attached to the heading style, not text like `1.2`. Two consequences: a typed number keeps lying after an insert, and a numbered outline needs `numPr` on the style with an `abstractNum` that uses `%1.%2` level text. When a document must have numbered sections and the original numbering is lost, restore the style's `numPr` rather than typing numbers into the headings.
+Numbering is a definition attached to the heading style, not text such as `1.2`: a typed number lies after the next insert. A numbered outline needs `numPr` on the style, with an `abstractNum` whose level text is `%1.%2`. Restore the style's `numPr` instead of typing numbers.
 
-Lists are the same machinery at body level: `List Number` restarts only when the numbering definition says so, which is why two separate numbered lists sometimes continue each other.
+Lists are the same machinery at body level. `List Number` restarts only when the numbering definition says so, which is why two separate lists sometimes continue each other.
 
 ## Verify
 
-`heading_audit.py` should exit 0, then render and read the page: heading hierarchy visible, no orphaned heading at the bottom of a page (`keepNext`), and the same spacing before every heading of a level.
+`heading_audit.py` exits 0 on a clean file. Render, then check that no heading is orphaned at the bottom of a page (`keepNext`) and that headings of one level share their spacing.
 
 ## Pitfalls
 
-- Changing a heading's style does not change its text, but it can change its size and colour — re-render.
-- A heading inside a table cell still counts for the outline, which is rarely wanted; use a bold paragraph there.
-- Copying a heading from another document brings a direct-formatting payload with it; run the audit afterwards.
+- Changing a heading's style leaves its text alone but can change size and colour: re-render.
+- A heading inside a table cell still counts for the outline, which is rarely wanted — use a bold paragraph.
+- Copying a heading brings a direct-formatting payload, so run the audit afterwards.