dsh-office-kit 0.4.2 → 0.4.3

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

@@ -1,8 +1,6 @@
 # Accessibility
 
-**Goal.** A document a screen reader can navigate: real headings, described images, tables with a header row, no fake emphasis carrying meaning.
-
-The accessibility tree in Word comes from structure, not appearance. Bold text announces as bold; a `Heading 1` announces as a heading and appears in the navigation pane. Alt text lives in `wp:docPr @descr`.
+Accessibility comes from structure, not appearance: bold announces as bold, `Heading 1` announces as a heading and appears in the navigation pane. Alt text lives in `wp:docPr @descr`.
 
 ## Audit
 
@@ -10,36 +8,32 @@ The accessibility tree in Word comes from structure, not appearance. Bold text a
 "<python>" "<skill>/scripts/a11y_audit.py" "<file.docx>" --out_json "<report.json>"
 ```
 
-Checks: images without a description or title, tables without a repeating header row, heading levels that jump, empty headings, links whose text is only "click here" / "here" / "link", and a missing core title.
-
-Exit code 1 means at least one finding; `--out_json` writes the same report for a larger pass.
+Checks images without description or title, tables without a repeating header row, heading levels that jump, empty headings, link text that is only "click here", "here" or "link", and a missing core title. Exit 1 means at least one finding.
 
-## Fix the mechanical parts
+## Mechanical fixes
 
 ```bash
-"<python>" "<skill>/scripts/a11y_audit.py" "<file.docx>" \
-  --fix_image_alt from_filename --fix_table_headers first_row \
-  --out "<file-a11y.docx>"
+"<python>" "<skill>/scripts/a11y_audit.py" "<file.docx>" --fix_image_alt from_filename --fix_table_headers first_row --out "<file-a11y.docx"
 ```
 
-Both fixes are honest placeholders: the file name as alt text is better than an empty description, and a header row that repeats across pages helps a reader who lands mid-table. Neither substitutes for real text.
+These are honest placeholders, not substitutes for real text.
 
-## Fix the parts that need judgement
+## Judgement fixes
 
-- **Alt text.** Describe what the reader would lose without the picture: "Bar chart: revenue by region, EMEA 4.1M ahead of APAC 3.2M." Decorative rules and dividers get an empty description.
-- **Link text.** "Download the Q2 ledger" instead of "click here".
-- **Reading order.** Decorative text boxes and floating images insert themselves at awkward places in the reading order; convert to inline if the flow matters.
-- **Colour.** Meaning carried only by colour (red = bad) fails for a colour-blind reader; add a word.
-- **Tables for layout.** A layout table announces as a data table. Restructure into paragraphs if the content is not tabular.
+- **Alt text** describes what the reader loses, e.g. "Bar chart: revenue by region, EMEA 4.1M ahead of APAC 3.2M". Decorative rules and dividers get an empty description.
+- **Link text** names the destination: "Download the Q2 ledger", not "click here".
+- **Reading order:** decorative text boxes and floating images land awkwardly; convert them to inline.
+- **Colour alone** (red = bad) fails colour-blind readers; add a word.
+- **Layout tables** announce as data tables; restructure them as paragraphs.
 
-Long documents also want a TOC (`tasks/toc_workflow.md`), which is the screen-reader equivalent of the navigation pane, and language tags so a screen reader pronounces correctly.
+Longer documents also want a TOC (`tasks/toc_workflow.md`) and language tags.
 
 ## Verify
 
-Re-run the audit to zero findings, then render and read the page: heading hierarchy visible, alt text is not visible (it is metadata), table header row distinct. If a screen reader is available, open the document and navigate by heading — that is the true test.
+Re-run the audit to zero findings and render. Heading hierarchy is visible; alt text is metadata and stays invisible; the header row must be distinct. With a screen reader available, navigate by heading.
 
 ## Pitfalls
 
-- Alt text on a decorative image is worse than none; an empty description plus `title` marks it decorative.
-- A table header row is `w:tblHeader` on the row, not a bold first row.
-- Images inside a table cell still need descriptions.
+- Alt text on a decorative image is worse than none: use an empty description plus `title` to mark it decorative.
+- A header row is `w:tblHeader` on the row, not a bold first row.
+- Images inside table cells still need descriptions.

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

@@ -1,49 +1,46 @@
-# Captions and cross-references
+# Captions and numbered cross-references
 
-**Goal.** Number figures and tables automatically and refer to them from the prose without typing a number that will drift.
-
-Two parts: a caption paragraph with a `SEQ` field (`SEQ Table \* ARABIC`), and a bookmark around it that the prose reaches with a `REF` field. Without the bookmark a `REF` has nothing to point at.
+A caption is a paragraph with a `SEQ` field (`SEQ Table \* ARABIC`) plus a bookmark; the prose reaches that bookmark with a `REF` field. Without the bookmark a `REF` has no target.
 
 ## Add captions
 
 ```bash
-"<python>" "<skill>/scripts/captions_and_crossrefs.py" "<file.docx>" "<file-captioned.docx>" \
-  --tables --figures --bookmarks --caption_text "Source: finance ledger"
+"<python>" "<skill>/scripts/captions_and_crossrefs.py" "<file.docx>" "<file-captioned.docx>" --tables --figures --bookmarks --caption_text "Source: finance ledger"
 ```
 
-- `--tables` adds `Table N` under each table, `--figures` adds `Figure N` under each picture. With neither flag, both run.
-- Captions use the `Caption` style and sit inside the same visual block as the object, so a page break cannot orphan them.
-- `--bookmarks` names the captions `tbl1`, `tbl2`, `fig1`, … so cross-references have targets.
-- `--materialize` writes literal numbers instead of `SEQ` fields; use it for a frozen PDF export, not for a document that will change.
-- `--caption_text` appends a fixed note after the number.
+- `--tables` adds `Table N` under each table; `--figures` adds `Figure N` under each picture.
+- Neither flag runs both.
+- `--bookmarks` names them `tbl1`, `tbl2`, `fig1`, … — the `tblN`/`figN` pattern `insert_ref_fields.py` expects.
+- `--materialize` writes literal numbers: for a frozen PDF export, not for a document that will change.
+- `--caption_text` appends a fixed note.
 
-The bookmarks the script creates (`tblN`, `figN`) are what `insert_ref_fields.py` expects by default.
+Captions use the `Caption` style and stay in the same visual block as the object, so a page break cannot orphan them.
 
-## Add cross-references
+## Cross-reference
 
-Write placeholders in your content, then convert them:
+Write `[[REF:tbl1]]` placeholders in the prose, then:
 
 ```bash
-"<python>" "<skill>/scripts/insert_ref_fields.py" "<file.docx>" "<file-refs.docx>"
+"<python>" "<skill>/scripts/insert_ref_fields.py" "<file.docx>" "<file-refs.docx"
 ```
 
-`[[REF:tbl1]]` becomes a `REF tbl1 \h` field, which renumbers when the table moves. `--pattern` accepts your own regular expression as long as it has a named group `bookmark`; `--prefix` prepends text such as `Table ` to each result.
+That produces a `REF tbl1 \h` field, so the number follows the table. `--pattern` accepts your own regex with the named group `bookmark`; `--prefix` prepends text such as `Table `.
 
-If the reference should read "Table 2" rather than just "2", set the `REF` field's `\n` behaviour off and include the label in the prose — a field cannot know whether its target is a table or a figure.
+If a reference should read "Table 2" rather than "2", set the REF field's `\n` behaviour off and put the label in the prose: a field cannot know whether it points at a table or a figure.
 
-## Order of operations
+## Order
 
-1. Add or restructure tables and figures.
-2. Run `captions_and_crossrefs.py` (creates captions and bookmarks).
-3. Run `insert_ref_fields.py` (turns placeholders into fields).
-4. Re-render: caption positions and numbering are a layout decision.
+1. Add or restructure the tables and figures.
+2. Run `captions_and_crossrefs.py`.
+3. Run `insert_ref_fields.py`.
+4. Re-render.
 
 ## Verify
 
-`fields_report.py`: one `SEQ` per caption, one `REF` per reference, no `REF` left with an empty result. Then read the rendered page — a caption above a table instead of below, or a caption separated from its object by a page break, is the usual defect.
+Run `fields_report.py`: one SEQ per caption, one REF per reference, and no REF with an empty result. Then render. The usual defects are a caption above its table, or a caption separated from it by a page break.
 
 ## Pitfalls
 
-- Renumbering happens on field update. Two captions claim `Table 2` until Word recalculates.
-- A caption added by hand with the number typed in will not renumber; use the script or a `SEQ` field.
-- Bookmarks must be unique; copying a caption copies its bookmark name and breaks the reference.
+- Numbering changes on field update, so two captions can claim `Table 2` until Word recalculates.
+- A hand-typed caption number never renumbers.
+- Bookmarks must be unique: copying a caption copies its bookmark name and breaks the reference.

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

@@ -1,49 +1,44 @@
-# Tracked changes
+# Proposed and tracked changes
 
-**Goal.** Propose edits as tracked changes so a reviewer can accept or reject them, or clean up a file that arrives full of markup.
+A tracked edit is markup: an insertion wraps runs in `w:ins`, a deletion wraps `w:delText` in `w:del`, a move is `w:moveFrom`/`w:moveTo` paired by `w:name`, and a formatting change is `w:rPrChange`/`w:pPrChange`. `w:trackRevisions` in `word/settings.xml` makes Word record new edits.
 
-A tracked edit is markup, not text: an insertion is `w:ins` wrapping runs, a deletion is `w:del` wrapping `w:delText`, and formatting changes are `w:rPrChange` / `w:pPrChange`. The setting `w:trackRevisions` in `word/settings.xml` makes Word record new edits the same way.
-
-## Propose an edit
+## Propose
 
 ```bash
-"<python>" "<skill>/scripts/add_tracked_replacements.py" "<file.docx>" --out "<file-tracked.docx>" \
-  --author "Review" --replace "18%=21%" --replace "flat=steady"
+"<python>" "<skill>/scripts/add_tracked_replacements.py" "<file.docx>" --out "<file-tracked.docx>" --author "Review" --replace "18%=21%" --replace "flat=steady"
 ```
 
-Each `--replace` is `OLD=NEW`; the script splits runs at the match so only the changed characters are marked, keeps the surrounding formatting, and turns on `trackRevisions`. Quote the `--author` the reviewer should see.
+Each `--replace` is `OLD=NEW`. The script splits runs at the match so only the changed characters are marked, keeps the surrounding formatting, and turns on `trackRevisions`. Quote the `--author` the reviewer should see.
 
-Limit: one replacement per pattern per paragraph, and a match split across runs is still found because the split is computed on paragraph text. Reword the pattern if the paragraph repeats the phrase.
+Limit: one replacement per pattern per paragraph. A match split across runs is still found because the split is computed on paragraph text; reword if a paragraph repeats the phrase.
 
-## Inspect what is proposed
+## Inspect
 
 ```bash
 "<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode report
 "<python>" "<skill>/scripts/docx_kit.py" xml "<file.docx>" word/document.xml
 ```
 
-The report counts insertions, deletions, move pairs and format changes. Use `docx_kit.py xml` when you need to know exactly which words change.
+The report counts insertions, deletions, move pairs and format changes.
 
 ## Accept or reject
 
 ```bash
-"<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode accept --out "<file-accepted.docx>"
-"<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode reject --out "<file-rejected.docx>"
+"<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode accept --out "<file-accepted.docx"
+"<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode reject --out "<file-rejected.docx"
 ```
 
-Accept keeps inserted text and drops deleted text; reject does the reverse and restores `w:delText` as ordinary text. Format-only changes are discarded either way. `--keep_tracking_on` leaves `trackRevisions` enabled, so the next person's edits are also recorded.
-
-## Before delivery
+Accept keeps inserted text and drops deleted text; reject reverses that and restores `w:delText` as ordinary text. Format-only changes are discarded either way. `--keep_tracking_on` leaves `trackRevisions` enabled.
 
-Rendered pages contain no markup, so a document can look finished while still carrying redlines. Always check `--mode report` on a file you are about to send, and accept or reject explicitly.
+Before delivery: rendered pages contain no markup, so a file can look finished while carrying redlines. Always run `--mode report` on a file about to be sent, then accept or reject explicitly.
 
 ## Verify
 
-After accepting, `docx_kit.py text` should show the new wording and no `w:ins`/`w:del` should remain in `word/document.xml`. Render and read the affected page.
+After accepting, `docx_kit.py text` shows the new wording and `word/document.xml` contains no `w:ins`/`w:del`. Render the affected page.
 
 ## Pitfalls
 
-- `w:del` contains `w:delText`, not `w:t`; a text extraction that only looks at `w:t` silently loses deletions.
-- Tables, headers and footnotes can each carry their own tracked changes — the script covers every text part, but a hand edit in one part can miss another.
-- Accepting a move pair (`w:moveFrom`/`w:moveTo`) as two unrelated edits duplicates content; the script treats them as a pair.
-- Comments are not tracked changes. See `comments_manage.md`.
+- `w:del` contains `w:delText`, not `w:t`; extraction that reads only `w:t` loses deletions.
+- Tables, headers and footnotes can each carry tracked changes. The script covers every text part; a hand edit can miss one.
+- Accepting a move pair as two unrelated edits duplicates content. The script treats them as a pair.
+- Comments are not tracked changes; see `comments_manage.md`.

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.