dsh-office-kit 0.4.2 → 0.4.4

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.

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

@@ -1,26 +1,17 @@
 # Read and review a file
 
-**Goal.** Understand an existing document before touching it: what it contains, how it is structured, and what is wrong with it.
-
-## Read the content
+## Read
 
 ```bash
 "<python>" "<cli>" docx read --input "<file.docx>"
-```
-
-Returns the title, author, paragraphs with their styles, headings, tables, image and equation counts, and page dimensions. Use it as the first look, including for files you produced earlier in the session.
-
-## Read the structure
-
-```bash
 "<python>" "<skill>/scripts/docx_kit.py" parts '<file.docx>'    # every package part and its size
 "<python>" "<skill>/scripts/docx_kit.py" text '<file.docx>'     # paragraphs with style and outline level
 "<python>" "<skill>/scripts/docx_kit.py" xml '<file.docx>' word/document.xml
 ```
 
-`parts` tells you which features exist at all (a `comments.xml` means the file carries comments; its absence means none, even if the user says otherwise). `text` is faster than reading raw XML when you only need the words and their heading levels.
+`docx read` gives the title, author, styled paragraphs, headings, table/image/equation counts and page dimensions — the first look, including for files produced earlier in the session. `parts` shows which features exist at all: no `comments.xml`, no comments, whatever the user says. `text` is faster than raw XML when you only need the words and their heading levels.
 
-## Audit what is there
+## Audit
 
 | Question | Command |
 |---|---|
@@ -32,19 +23,17 @@ Returns the title, author, paragraphs with their styles, headings, tables, image
 | Are there footnotes or endnotes? | `footnotes_report.py` |
 | What comments exist, and on what text? | `comments_extract.py` |
 
-Every audit script prints JSON and exits non-zero when it found something, so the exit code alone tells you whether the document needs attention. Read the `findings` array rather than the exit code when you need the reason.
+Each audit prints JSON and exits non-zero when it found something: the exit code says whether the document needs attention, the `findings` array says why.
 
 ## Review for the user
 
-When the job is "review this document" rather than "change it":
-
-1. Read the text, not just the audits. Point out the argument, not only the formatting.
+1. Read the text, not just the audits. Address the argument, not only the formatting.
 2. Separate defects (broken table, skipped heading level, missing alt text) from style preferences.
-3. Cite locations by section heading and paragraph text — Word has no stable page numbers.
+3. Cite locations by section heading and paragraph text: Word has no stable page numbers.
 4. Offer the fix as a concrete next action, with the command that performs it.
 
 ## Pitfalls
 
-- `docx read` shows the body only; headers, footers, footnotes and comments need `docx_kit.py xml` or the dedicated report scripts.
-- Tracked changes are visible as plain text in a read; use `accept_tracked_changes.py --mode report` to see what is proposed.
-- A field's displayed text is a cached result. `fields_report.py` shows the instruction, which is the truth.
+- `docx read` shows the body only; headers, footers, footnotes and comments need `docx_kit.py xml` or the report scripts.
+- Tracked changes read as plain text; `accept_tracked_changes.py --mode report` shows what is proposed.
+- A field's displayed text is a cached result; `fields_report.py` shows the instruction, which is the truth.

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

@@ -1,26 +1,29 @@
 # Redaction and anonymisation
 
-**Goal.** Remove personal data — addresses, phone numbers, names, account references — from a document before it leaves the organisation, in the text and in the places text hides.
-
-Text lives in `w:t` (and `w:delText` for deletions, `w:instrText` for field instructions). A redaction that only rewrites paragraphs via `python-docx` misses headers, footers, footnotes and comments.
+Text lives in `w:t` (plus `w:delText` for deletions and `w:instrText` for field instructions). A redaction that only rewrites paragraphs through python-docx misses headers, footers, footnotes and comments.
 
 ## Redact
 
 ```bash
 "<python>" "<skill>/scripts/redact_docx.py" "<file.docx>" "<file-redacted.docx>" --emails --phones
+```
+
+```bash
 "<python>" "<skill>/scripts/redact_docx.py" "<file.docx>" "<file-redacted.docx>" --pattern "ACCT-\d{6}" --replacement "<account>"
 ```
 
-- Default run covers emails and phone numbers; add `--pattern` (repeatable) for account numbers, case ids, postcodes.
-- `--mask_char *` keeps the shape of the value visible (`***@***.com` style), `--replacement` swaps in a token, `--no_preserve_length` stops padding to the original length.
-- `--include_comments` also rewrites `word/comments.xml`; without it, comments keep the original text.
-- Applied to body, every header and footer, footnotes and endnotes.
+`--pattern` is repeatable — use it for account numbers, case ids and postcodes. It applies to the body, every header and footer, footnotes and endnotes.
 
-Matching happens per text run, because merging runs would destroy the surrounding formatting. A value split across runs (bolded digits inside a phone number) is not found — an acceptable trade only if you check the result; when the file mixes formatting inside the sensitive value, flatten that paragraph first (`tasks/style_lint_normalize.md`).
+| Flag | Effect |
+|---|---|
+| `--mask_char *` | masks the shape of the value instead of replacing it (`***@***.com`) |
+| `--replacement` | swap in a token instead of masking |
+| `--no_preserve_length` | stop padding the result to the original length |
+| `--include_comments` | also rewrite `word/comments.xml`; without it comments keep the original text |
 
-## Redaction versus anonymisation
+Matching happens per text run, because merging runs destroys formatting, so a value split across runs is not found. That is acceptable only if you check the result; when formatting is mixed inside the sensitive value, flatten that paragraph first (`tasks/style_lint_normalize.md`).
 
-Redaction removes the value; anonymisation replaces it consistently. If the same account number appears four times and the argument depends on it matching, replace all occurrences with the same token rather than `[redacted]` every time — `--replacement "<account-A>"` per pattern does that.
+Redaction removes a value; anonymisation replaces it consistently. If the same account number appears four times and the argument depends on it matching, replace all occurrences with the same token rather than `[redacted]` every time — per-pattern `--replacement "<account-A>"` does that.
 
 ## Check the whole file
 
@@ -29,14 +32,10 @@ Redaction removes the value; anonymisation replaces it consistently. If the same
 "<python>" "<skill>/scripts/docx_kit.py" xml '<file-redacted.docx>' word/document.xml | grep -c "example.com"
 ```
 
-A grep over dumped XML is the honest check: run it for each sensitive term, across the document, header, footer, footnote and comment parts.
-
-## Verify
-
-Render, then read the pages the data appeared on. A redaction that changed the line length enough to shift the layout is worth a look; a redaction that left a `<w:t>` intact shows up in the grep, not the page.
+Grepping the dumped XML for each sensitive term across document, header, footer, footnote and comment parts is the honest check. Then render and read the pages the data appeared on: check line-length shifts, and remember an intact `<w:t>` shows in the grep, not on the page.
 
 ## Pitfalls
 
-- Field results and field instructions can both contain data; the script rewrites `w:t` and `w:delText` only.
-- Images are not scanned — a screenshot of a spreadsheet is not redacted by any text pass. Say so plainly.
-- Charts store category labels in `word/charts/*.xml`; inspect those parts when a chart carried the sensitive data.
+- Field results and field instructions can both hold data; the script rewrites `w:t` / `w:delText` only.
+- Images are not scanned. Say so plainly instead of implying the file is clean.
+- Charts store category labels in `word/charts/*.xml`; inspect them when a chart carried the data.

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

@@ -1,8 +1,6 @@
-# Sections and page layout
+# Sections, page setup, headers
 
-**Goal.** Page size, orientation, margins, columns, headers and footers that are deliberate at every point in the document, including after a mid-document change.
-
-Page setup lives in a `w:sectPr` element. The last one sits at the end of the body; earlier ones sit inside the last paragraph of the section they end (`w:pPr/w:sectPr`). That is why adding a landscape page means adding a section break before and after, not changing one global setting.
+Page setup lives in `w:sectPr`. The last one sits at the end of the body; earlier ones sit inside the last paragraph of the section they end (`w:pPr/w:sectPr`). A landscape page therefore needs a section break before and after it, not one global setting.
 
 ## Audit
 
@@ -10,45 +8,40 @@ Page setup lives in a `w:sectPr` element. The last one sits at the end of the bo
 "<python>" "<skill>/scripts/section_audit.py" "<file.docx>"
 ```
 
-Per section: width and height in inches, orientation derived from them, every margin, column count, section start type, header and footer parts referenced, `titlePg` (different first page) and any explicit page-number start.
-
-Findings worth fixing: `mixed_page_sizes` (sections that disagree, usually a template artefact), `narrow_text_column` (left plus right margin eats most of the width), `portrait_wider_than_letter`.
+Reports per section: width and height in inches, orientation derived from them, every margin, column count, section start type, header and footer parts referenced, `titlePg`, explicit page-number start. Findings: `mixed_page_sizes`, `narrow_text_column` (left and right margin eat most of the width), `portrait_wider_than_letter`.
 
 ## Common changes
 
-| Wanted | Route |
-|---|---|
-| New document defaults | `docx create` spec: `page_size`, `orientation`, `top_margin`/`bottom_margin`/`left_margin`/`right_margin` in inches |
-| A landscape page inside a portrait document | two section breaks with a landscape section between them |
-| Different first page header | set `titlePg` on the section and fill `first_page_header` |
-| Continuous section change (e.g. narrower margins) | `w:type val="continuous"` on the new section |
+- New-document defaults: `docx create` spec keys `page_size`, `orientation`, `top_margin` / `bottom_margin` / `left_margin` / `right_margin` (inches).
+- A landscape page inside a portrait document: two section breaks with the landscape section between them.
+- A different first-page header: set `titlePg` and fill `first_page_header`.
+- A continuous change such as narrower margins: `w:type val="continuous"`.
 
-Landscape and columns are section properties, so a snippet is often faster than a flag:
+Landscape and columns are section properties, so a snippet is often faster than a script:
 
-```bash
-"<python>" - <<'PY'
+```python
 from docx import Document
 from docx.enum.section import WD_ORIENT, WD_SECTION
+
 d = Document(r"<file.docx>")
 s = d.add_section(WD_SECTION.NEW_PAGE)
 s.orientation = WD_ORIENT.LANDSCAPE
 s.page_width, s.page_height = s.page_height, s.page_width
 d.save(r"<file-edited.docx>")
-PY
 ```
 
-Swap the width and height explicitly: setting the orientation alone does not swap them.
+Setting the orientation alone does not swap the two size values.
 
 ## Headers and footers
 
-A header is `word/headerN.xml` referenced from `w:headerReference`. Headers inherit from the previous section unless the section sets `headerReference` itself. Page numbers go in the footer as a `PAGE` field, page counts as `NUMPAGES`; `docx_ooxml_patch.py --add-page-numbers` writes one.
+`word/headerN.xml` is referenced from `w:headerReference`. A header inherits from the previous section unless the section sets its own reference. Page numbers in the footer are a `PAGE` field; counts are `NUMPAGES`; `docx_ooxml_patch.py --add-page-numbers` writes one.
 
 ## Verify
 
-Render and flip through every page, including the ones after a section break: header content, page numbers, orientation, margins. A section break that leaves an empty page is the classic defect — check for a stray empty paragraph carrying the break.
+Render and flip through every page, including the pages after a section break: header content, page numbers, orientation, margins. The classic defect is a section break that leaves an empty page — look for a stray empty paragraph carrying it.
 
 ## Pitfalls
 
-- `w:pgSz` is width then height; a portrait page taller than wide is normal, a "landscape" 11×8.5 that still says portrait in the panel means only the size changed.
-- `titlePg` without filling the first-page header leaves page one with a blank header, not with the normal one.
-- Deleting a section break merges two sections and keeps the earlier section's settings; edit before deleting.
+- `w:pgSz` holds width then height; a "landscape" 11×8.5 still marked portrait means only the size values changed.
+- `titlePg` without a filled first-page header leaves page one blank instead of showing the normal header.
+- Deleting a section break merges two sections and keeps the earlier settings.

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

@@ -1,44 +1,40 @@
-# Styles: lint and normalize
+# Style lint and normalisation
 
-**Goal.** Formatting that comes from styles, not from pressing bold on each run, so the document can be restyled, exported and understood later.
-
-A paragraph carries a `pStyle` reference; a run carries an `rStyle` plus direct formatting (`w:b`, `w:i`, `w:sz`, `w:color`). Direct formatting wins over the style, which is why a "make all body text 11pt" request fails on the runs someone bolded and resized by hand.
+A paragraph carries `pStyle`; a run carries `rStyle` plus direct formatting (`w:b`, `w:i`, `w:sz`, `w:color`). Direct formatting wins over the style, which is why "make all body text 11pt" fails on hand-formatted runs.
 
 ## Lint
 
 ```bash
-"<python>" "<skill>/scripts/style_lint.py" "<file.docx>" --json "<report.json>"
+"<python>" "<skill>/scripts/style_lint.py" "<file.docx>" --json "<report.json"
 ```
 
-Findings: undefined style references, headings carrying their own paragraph or run formatting, empty runs, manual bullets (`•` typed into text instead of a list style), double spaces, trailing spaces, body sizes that appear once or twice against the dominant size, tables without a style.
-
-Exit code 1 means findings; the JSON has the counts and examples, which is what you want when the number is large.
+Findings: undefined style references, headings carrying their own paragraph or run formatting, empty runs, manual bullets (`•` typed instead of a list style), double spaces, trailing spaces, body sizes appearing once or twice against the dominant size, tables without a style. Exit 1 means findings; the JSON holds counts and examples.
 
-## Normalize
+## Normalise
 
 ```bash
-"<python>" "<skill>/scripts/style_normalize.py" "<file.docx>" --out "<file-clean.docx>" \
-  --clear_paragraph_format --enforce_heading_spacing
+"<python>" "<skill>/scripts/style_normalize.py" "<file.docx>" --out "<file-clean.docx" --clear_paragraph_format --enforce_heading_spacing
 ```
 
-- `--clear_paragraph_format` strips everything from each run's `rPr` except `rStyle`, `rtl` and `lang`, and drops the paragraph-mark run properties. The style then controls the look.
-- `--enforce_heading_spacing` sets space-before/space-after per heading level and `keepNext`, so a heading cannot sit alone at the bottom of a page.
+- `--clear_paragraph_format` strips everything from each run's `rPr` except `rStyle`, `rtl` and `lang`, and drops the paragraph-mark run properties, so the style controls the look.
+- `--enforce_heading_spacing` sets space-before and space-after per heading level plus `keepNext`.
 
-Run this before applying a template; a template cannot win against direct formatting.
+Run it before applying a template: a template cannot win against direct formatting (`tasks/templates_style_packs.md`).
 
-## What "correct" looks like
+## Correct look
 
-- Body text 11–12pt from `Normal`; headings from `Heading 1`–`Heading 3` with no direct bold or size.
-- Bold used for emphasis inside a sentence, via a character style or a single `w:b` run — not for whole paragraphs that are really headings.
-- Lists from `List Bullet` / `List Number`, never typed bullet characters.
+- Body text 11–12pt from `Normal`.
+- Headings from `Heading 1`–`Heading 3`, with no direct bold or size.
+- Bold for in-sentence emphasis via a character style or one `w:b` run, never for whole paragraphs that are really headings.
+- Lists from `List Bullet` / `List Number`, never typed bullets.
 - One table style per document, usually `Table Grid`.
 
 ## Verify
 
-Re-run `style_lint.py` (counts should drop), then render: clearing direct formatting can change the visual hierarchy when a document faked emphasis with size. Compare the rendered page with the original before you claim the clean-up is neutral.
+Re-run `style_lint.py` and watch the counts drop, then render. Clearing direct formatting can change the hierarchy when a document faked emphasis with size; compare against the original before claiming the change was neutral.
 
 ## Pitfalls
 
-- Clearing `rPr` removes field-result formatting too; re-run the field-related scripts afterwards if the number must be bold.
-- A style referenced but not defined falls back to `Normal` silently — the lint is the only warning you get.
-- `w:rsid` and proofing attributes are noise, not style; `privacy_scrub.py` removes them when the file leaves the organisation.
+- Clearing `rPr` also removes field-result formatting; re-run the field scripts if a number must stay bold.
+- A style that is referenced but not defined falls back to `Normal` silently — the lint is the only warning.
+- `w:rsid` and proofing attributes are noise, removed by `privacy_scrub.py` when the file leaves (`tasks/privacy_scrub_metadata.md`).