dsh-office-kit 0.4.2 → 0.4.3

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.

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

@@ -1,8 +1,6 @@
 # Images and figures
 
-**Goal.** Pictures that are described for screen readers, sized for the page, and captioned consistently.
-
-An inline picture is a `w:drawing` containing `wp:inline` (or `wp:anchor` for a floating one), with the picture relationship in `a:blip r:embed` and the display size in `wp:extent` (EMU). Alt text lives in `wp:docPr @descr`.
+An inline picture is a `w:drawing` containing `wp:inline` (`wp:anchor` for floating), the picture relationship in `a:blip r:embed`, the display size in `wp:extent` (EMU), and the alt text in `wp:docPr @descr`.
 
 ## Audit
 
@@ -10,54 +8,46 @@ An inline picture is a `w:drawing` containing `wp:inline` (or `wp:anchor` for a
 "<python>" "<skill>/scripts/images_audit.py" "<file.docx>" --max_rows 20
 ```
 
-For every image: the part it sits in, its name, the media file behind it, its size in inches, and the alt text. Findings are `missing_alt` and `oversized` (wider than the text block). The workable check is "does the alt text describe what a reader loses if the picture is gone".
+Reports each picture's part, name, media file, size in inches and alt text, plus `missing_alt` and `oversized` (wider than the text block). The real test is whether the alt text describes what a reader loses without the picture.
 
 ## Fix alt text
 
 ```bash
-"<python>" "<skill>/scripts/a11y_audit.py" "<file.docx>" --fix_image_alt from_filename --out "<file-fixed.docx>"
+"<python>" "<skill>/scripts/a11y_audit.py" "<file.docx>" --fix_image_alt from_filename --out "<file-fixed.docx"
 ```
 
-That writes the file name when no description exists — better than nothing, not as good as real text. For real descriptions, set `descr` yourself; decorative images get an empty description and `title`, while informative images get a sentence:
+A file name is better than nothing but not as good as a real description. For real text, patch `wp:docPr` directly:
 
-```bash
-"<python>" - <<'PY'
-import sys
-from pathlib import Path
+```python
 sys.path.insert(0, r"<skill>/scripts")
 import docx_kit as kit
 d = kit.Docx(r"<file.docx>")
 for doc_pr in d.xml("word/document.xml").iter(kit.q("docPr", kit.WP)):
     if doc_pr.get("name") == "Picture 3":
         doc_pr.set("descr", "Bar chart: revenue by region, EMEA ahead of APAC.")
-out = Path(r"<file-fixed.docx>")
-d.save(out)
-print("saved", out)
-PY
+d.save("<file.docx>")
 ```
 
+Decorative images get an empty description plus a `title`; informative images get a sentence.
+
 ## Insert
 
-```bash
-"<python>" "<cli>" docx create --spec "<spec.json>" --out "<out.docx>"
-```
+`docx create --spec` block:
 
 ```json
 { "type": "image", "path": "<absolute.png>", "width": 5.5 }
 ```
 
-Width is in inches; the height follows the aspect ratio. An image wider than the text block gets clipped or shrinks unpredictably — 5.5in is a safe full-width figure on Letter with 1in margins.
-
-## Figures
+Width is in inches and height follows the aspect ratio. A picture wider than the text block is clipped or shrinks unpredictably; 5.5in is a safe full-width figure on Letter with 1in margins.
 
-Caption a picture the same way as a table (`tasks/captions_crossrefs.md`): `captions_and_crossrefs.py --figures` adds `Figure N` with a `SEQ` field and a `figN` bookmark. Keep the caption in the same block so the figure and its caption do not separate across a page break.
+Figures get captions with `captions_and_crossrefs.py --figures` (`tasks/captions_crossrefs.md`), which adds `Figure N` with a `SEQ` field and a `figN` bookmark. Keep the caption in the same block so picture and caption do not separate.
 
 ## Verify
 
-Render and read the page: the image is not stretched, not blurry beyond the source resolution, not clipped at the margin, and its caption sits under it. Add alt text as a separate check — the render cannot show it.
+Render: not stretched, not blurry beyond the source resolution, not clipped at the margin, caption underneath. Alt text is a separate check the render cannot show.
 
 ## Pitfalls
 
-- Cropping in Word is not lossy for the file but changes the displayed extent; alt text and size checks still apply.
-- A floating image (`wp:anchor`) can overlap text at any zoom level; prefer inline for documents that will be edited.
-- Replacing an image file in `word/media` in place keeps the relationship but not the dimensions — the extent is stored separately.
+- Cropping changes the displayed extent; alt text and size checks still apply.
+- A floating `wp:anchor` image can overlap text at any zoom — prefer inline for documents that will be edited.
+- Replacing a file in `word/media` keeps the relationship but not the dimensions: the extent is stored separately.

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

@@ -1,43 +1,33 @@
 # Merge documents
 
-**Goal.** Put one document after another and keep both looking the same — styles, numbering, images, hyperlinks — instead of pasting content that loses half of it.
-
-Concatenating packages by hand fails on the details: style ids collide, `numId` values point at the wrong list, media parts need new names and relationships, and `r:id` values are document-scoped. Word also requires one `sectPr` at the end of the body, so the appended content has to land before it.
+Concatenating packages by hand fails: style ids collide, `numId` values point at the wrong lists, media parts need new names and relationships, `r:id` values are document-scoped, and Word requires one `sectPr` at the end of the body, so appended content must land before it.
 
 ## Append
 
 ```bash
-"<python>" "<skill>/scripts/merge_docx_append.py" "<base.docx>" "<addition.docx>" --out "<merged.docx>"
+"<python>" "<skill>/scripts/merge_docx_append.py" "<base.docx>" "<addition.docx>" --out "<merged.docx"
 ```
 
-What it carries across: body content (minus the addition's final `sectPr`), media parts renamed under `word/media` with fresh relationships and content types, style definitions referenced by the copied content (following `basedOn`/`next`/`link`), numbering definitions rebuilt with fresh ids and every `w:numId` rewritten, and hyperlink relationships recreated as external relationships.
-
-Drawings are refused by default: a floating image or a text box carries anchor geometry tied to the original page. Pass `--allow_drawings` when the user accepts that the layout may shift, then check that page carefully.
-
-## Merge into a template
+The script carries the body content minus the addition's final `sectPr`, renames media parts under `word/media` with fresh relationships and content types, copies style definitions referenced by the copied content (following `basedOn`/`next`/`link`), rebuilds numbering definitions with fresh ids and rewrites every `w:numId`, and recreates hyperlink relationships as external relationships.
 
-The usual job is "put these sections into the house template". Apply the template first, then append, so the appended content inherits the template's style ids:
+Drawings are refused by default: a floating image or text box carries anchor geometry tied to its original page. Use `--allow_drawings` when the user accepts a possible layout shift, then check that page.
 
-```bash
-"<python>" "<skill>/scripts/apply_template_styles.py" --template "<house.dotx>" --target "<draft.docx>" --out "<draft-styled.docx>"
-"<python>" "<skill>/scripts/merge_docx_append.py" "<draft-styled.docx>" "<section2.docx>" --out "<merged.docx>"
-```
+## Into a template
 
-Then normalize direct formatting so the merged content matches:
+Apply the template first, then append, so content inherits the template's style ids:
 
 ```bash
-"<python>" "<skill>/scripts/style_normalize.py" "<merged.docx>" --out "<merged-final.docx>" --clear_paragraph_format
+"<python>" "<skill>/scripts/apply_template_styles.py" --template "<house.dotx>" --target "<draft.docx>" --out "<draft-styled.docx"
+"<python>" "<skill>/scripts/merge_docx_append.py" "<draft-styled.docx>" "<section2.docx>" --out "<merged.docx"
+"<python>" "<skill>/scripts/style_normalize.py" "<merged.docx>" --out "<merged-final.docx" --clear_paragraph_format
 ```
 
 ## Verify
 
-- Page count should equal the sum of the inputs, unless a page break changed.
-- Headers and footers come from the base document; say so if the addition had its own.
-- Render and read the join: the page where the second document starts often shows a stray page break or a heading that lost its style.
-- `style_lint.py` on the merged file catches undefined style references imported from the addition.
+Page count equals the sum of the inputs unless a page break changed. Headers and footers come from the base document — say so if the addition had its own. Render the join to catch a stray page break or a heading that lost its style. `style_lint.py` catches undefined style references imported from the addition.
 
 ## Pitfalls
 
-- Footnotes and comments in the addition are not merged; port them deliberately if they must survive.
-- `w:id` values for bookmarks and comments can collide across documents; the merge keeps ids and names as they were.
-- A landscape section in the addition is not carried over — section properties were dropped with the `sectPr`.
+- Footnotes and comments in the addition are not merged (the port is deliberate).
+- Bookmark and comment `w:id` values can collide; the merge keeps ids and names.
+- A landscape section in the addition is not carried over: section properties are dropped with the `sectPr`.

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

@@ -1,38 +1,35 @@
-# Internal navigation
+# Navigation and internal links
 
-**Goal.** Let a reader jump around a long document — from a contents list to a section, and back — without relying on the TOC field being recalculated.
+An internal link is `w:hyperlink w:anchor="bookmark"`; the target is a `w:bookmarkStart`/`w:bookmarkEnd` pair. Both live in the body, so PDF export keeps the links.
 
-A hyperlink to a place inside the document is `w:hyperlink w:anchor="bookmark"`; the target is a `w:bookmarkStart`/`w:bookmarkEnd` pair with that name. Both live in the body, so an export to PDF keeps the links.
-
-## Build a navigation set
+## Build navigation
 
 ```bash
-"<python>" "<skill>/scripts/internal_nav.py" "<file.docx>" --out "<file-nav.docx>" --levels 1 2 \
-  --toc_title "Contents"
+"<python>" "<skill>/scripts/internal_nav.py" "<file.docx>" --out "<file-nav.docx>" --levels 1 2 --toc_title "Contents"
 ```
 
-What it does, in order:
+The script:
 
-1. Bookmarks every heading as `nav_h1`, `nav_h2`, … using its outline level.
-2. Inserts a `Contents` heading and a quick-link bar (one link per heading) at the top.
-3. Indents each contents entry by 360 twips per level so the hierarchy is visible.
-4. Appends a small `Back to contents` link after each heading.
-5. Bookmarks the top, the contents list and the bottom (`nav_top`, `nav_toc`, `nav_bottom`).
+- bookmarks every heading `nav_h1`, `nav_h2`, … by outline level;
+- inserts a `Contents` heading and a quick-link bar at the top;
+- indents contents entries 360 twips per level;
+- appends a `Back to contents` link after each heading;
+- bookmarks the top, the contents and the bottom as `nav_top`, `nav_toc`, `nav_bottom`.
 
-Flags: `--no_quicklinks` skips the horizontal bar, `--no_back_to_toc` skips the per-heading back link, `--no_top_bottom` skips the two edge targets.
+Flags: `--no_quicklinks`, `--no_back_to_toc`, `--no_top_bottom`.
 
-The script reports `missing` when a link target could not be created — read that list, because a link without a bookmark is dead in Word and looks fine in a render.
+It reports `missing` when a target could not be created. Read that list: a dead link looks fine in a render.
 
-## Static versus field-driven
+## Static versus field
 
-`internal_nav.py` writes literal entries: it costs a rebuild when headings change, and it always looks the same in every renderer. `insert_toc.py` writes a live `TOC` field: it updates itself but needs a recalculation before it shows anything useful. A document that will be edited repeatedly wants the field; a document going out as a PDF export wants the static list.
+`internal_nav.py` writes literal entries: rebuild when headings change, and every renderer shows the same result. `insert_toc.py` writes a live `TOC` field: self-updating, but it needs recalculation. A repeatedly edited document wants the field; a PDF export wants the static list.
 
 ## Verify
 
-Render, then click through the pages you can see: entry indentation, that the contents heading is styled as a heading, and that `Back to contents` did not push a paragraph onto a new page. Dead anchors do not show in a screenshot — check `bookmarkStart` names against the `w:anchor` values when the script reports a miss.
+Render and click through: entry indentation, the contents heading styled as a heading, and `Back to contents` not pushing a paragraph onto a new page. Dead anchors do not show in a screenshot — when the script reports a miss, check `bookmarkStart` names against the `w:anchor` values.
 
 ## Pitfalls
 
-- Bookmarks must be unique per document; re-running the script on its own output creates `nav_h1` twice, so start from the original.
-- A hyperlink anchor is case-sensitive.
-- Link styling comes from the `Hyperlink` character style; if links look like body text, the style is missing, not the link.
+- Bookmarks must be unique per document. Re-running on its own output duplicates `nav_h1`, so start from the original.
+- Hyperlink anchors are case-sensitive.
+- Link styling comes from the `Hyperlink` character style.

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

@@ -1,29 +1,23 @@
-# Privacy: metadata and residue
+# Privacy and document metadata
 
-**Goal.** A file that carries only the content the user meant to send: no author name, no tracked review history, no comments, no template identity, no editing session ids.
+A `.docx` stores more than text: `docProps/core.xml` (author, last modifier, title, keywords, description), `docProps/app.xml` (company, manager, template), `docProps/custom.xml`, `word/comments.xml`, revision data and per-author `w:rsid` stamps.
 
-`.docx` stores more than the text: `docProps/core.xml` (author, last modifier, title, keywords, description), `docProps/app.xml` (company, manager, template), `docProps/custom.xml`, `word/comments.xml`, revision data and per-author `w:rsid` attributes.
-
-## Scrub metadata
+## Scrub
 
 ```bash
-"<python>" "<skill>/scripts/privacy_scrub.py" "<file.docx>" --out "<file-clean.docx>"
+"<python>" "<skill>/scripts/privacy_scrub.py" "<file.docx>" --out "<file-clean.docx"
 ```
 
-Clears creator, last-modified-by, keywords, description, subject, title, category, company, manager and application; resets the revision counter; drops `docProps/custom.xml` and its relationships and content-type override; strips `w:rsid*` attributes, `w:proofErr` and `w:lastRenderedPageBreak` across the Word parts.
-
-`--keep_title` leaves the title in place when the title is real content the user wants.
+Clears creator, last-modified-by, keywords, description, subject, title, category, company, manager and application; resets the revision counter; drops `docProps/custom.xml` with its relationships and content-type override; strips `w:rsid*`, `w:proofErr` and `w:lastRenderedPageBreak` across the Word parts. `--keep_title` preserves a real title.
 
-## The rest of the residue
+## Other residue
 
-| Residue | Command |
-|---|---|
-| Comments and their authors | `comments_strip.py` |
-| Tracked changes and reviewer names | `accept_tracked_changes.py --mode accept` (or reject) |
-| Watermarks naming the old client | `watermark_audit_remove.py --mode remove` |
-| Emails and phone numbers in the text | `redact_docx.py` |
+- Comments and their authors → `comments_strip.py`.
+- Tracked changes and reviewer names → `accept_tracked_changes.py --mode accept` (or reject).
+- A watermark naming the old client → `watermark_audit_remove.py --mode remove`.
+- Emails and phone numbers → `redact_docx.py`.
 
-Run them in that order — scrub metadata, resolve markup, then redact the text that survived.
+Order matters: scrub metadata, resolve markup, then redact the surviving text.
 
 ## Check before delivery
 
@@ -32,14 +26,14 @@ Run them in that order — scrub metadata, resolve markup, then redact the text
 "<python>" "<skill>/scripts/docx_kit.py" xml '<file-clean.docx>' docProps/core.xml
 ```
 
-`parts` shows whether `docProps/custom.xml` or `word/comments.xml` still exist; the core part shows what a recipient would see in File > Info. Both are cheap and both catch the mistake the scripts did not.
+`parts` shows whether `custom.xml` and `comments.xml` still exist; `core` shows what a recipient sees under File > Info.
 
 ## Verify
 
-Metadata is not visible in a page render. Verify with the commands above, and render to be sure the document still looks right after the scrub — clearing `w:lastRenderedPageBreak` can change where a viewer chooses to break a long line.
+Metadata never appears in a render, so use those two commands. Render afterwards to confirm the document still looks right: clearing `w:lastRenderedPageBreak` can change where a viewer breaks a long line.
 
 ## Pitfalls
 
-- Author names also appear in comment and revision entries, not only in core properties.
-- `docProps/app.xml` names the editing application; it is regenerated on next save by whatever app opens the file.
-- Removing revision ids does not undo content — the text is still there.
+- Author names also appear in comment and revision entries.
+- `docProps/app.xml` names the editing application and is regenerated on the next save.
+- Removing revision ids does not undo content.

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

@@ -1,41 +1,39 @@
 # Restrict editing
 
-**Goal.** Stop a reviewer from changing the body while still letting them comment or track changes — the "send for review" state, not encryption.
+Restrictions live in `w:documentProtection` inside `word/settings.xml`. Modes: `readOnly`, `comments`, `trackedChanges`, `forms`, each with `enforcement`. This is a guardrail against accidental edits, not encryption: a determined reader can remove it.
 
-Editing restrictions live in `w:documentProtection` inside `word/settings.xml`. The modes are `readOnly`, `comments`, `trackedChanges`, `forms`, plus `enforcement` to switch the restriction on. This is a guardrail against accidental edits; it does not encrypt content and a determined reader can remove it.
-
-## Set a mode
+## Set
 
 ```bash
-"<python>" "<skill>/scripts/set_protection.py" "<file.docx>" --mode comments --out "<file-review.docx>"
-"<python>" "<skill>/scripts/set_protection.py" "<file.docx>" --mode readOnly --no_enforce --out "<file-open.docx>"
+"<python>" "<skill>/scripts/set_protection.py" "<file.docx>" --mode comments --out "<file-review.docx"
+"<python>" "<skill>/scripts/set_protection.py" "<file.docx>" --mode readOnly --no_enforce --out "<file-open.docx"
 ```
 
-Modes and aliases: `off`/`none`, `readOnly`/`read_only`, `comments`/`comment`, `trackedChanges`/`tracked_changes`, `forms`/`form`. `--no_enforce` writes the setting without switching it on, which is useful when the opening dialog should be avoided.
+Mode aliases: `off` / `none`, `readOnly` / `read_only`, `comments` / `comment`, `trackedChanges` / `tracked_changes`, `forms` / `form`. `--no_enforce` writes the setting without switching it on, which avoids the dialog on open.
 
-`--hash` also writes a password hash (SHA-512, 100000 spins; `--salt`, `--spin_count` to change it). Be honest with the user: the hash deters casual edits, it is not encryption, and losing the password means the restriction has to be stripped from the XML.
+`--hash` also writes a password hash (SHA-512, 100000 spins; `--salt` and `--spin_count` change the parameters). Say plainly that it deters casual edits, is not encryption, and that losing the password means stripping the restriction from the XML.
 
-## Which mode to pick
+## Choose a mode
 
-| Intent | Mode |
+| Requirement | Mode |
 |---|---|
-| Review comments only, no text edits | `comments` |
-| All edits should be tracked | `trackedChanges` |
-| Fill a form, nothing else | `forms` |
+| Comments only | `comments` |
+| All edits tracked | `trackedChanges` |
+| Fill a form | `forms` |
 | View only | `readOnly` |
 
-## Remove
+Remove the restriction with `--mode off --out "<file-open.docx"`.
+
+## Verify
 
 ```bash
-"<python>" "<skill>/scripts/set_protection.py" "<file-protected.docx>" --mode off --out "<file-open.docx>"
+"<python>" "<skill>/scripts/docx_kit.py" xml '<file.docx>' word/settings.xml | grep documentProtection
 ```
 
-## Verify
-
-`docx_kit.py xml '<file.docx>' word/settings.xml | grep documentProtection` shows the element and its enforcement attribute. Then open behaviour matters, not the page — render will not show a restriction. Say which mode you applied, and that removing it needs the same script or Word's Review pane.
+The element and its enforcement setting appear in the output. Open behaviour is what matters, not the page: a render never shows a restriction. State the mode you applied and that removing it needs the same script or Word's Review pane.
 
 ## Pitfalls
 
-- Protected documents that also contain tracked changes and comments often prompt on open; apply the restriction last.
-- `forms` mode without form fields leaves a document nobody can edit usefully.
-- Protection marked with a hash cannot be turned off in Word without the password, but `--mode off` still clears it — that is why it is a guardrail, not security.
+- A protected document that also holds tracked changes or comments often prompts on open; apply the restriction last.
+- `forms` without form fields leaves a document nobody can use.
+- A hashed restriction cannot be turned off in Word without the password, yet `--mode off` clears it — which is why this is a guardrail, not security.