dsh-office-kit 0.4.2 → 0.4.3

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`).

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

@@ -1,64 +1,54 @@
-# Tables and spreadsheets
+# Tables and layout geometry
 
-**Goal.** A table that fits the page, repeats its header row across pages, and survives an edit without cells drifting out of alignment.
-
-A table's geometry is three things that must agree: the grid (`w:tblGrid`, one `w:gridCol` per column), the table width (`w:tblW`), and each cell width (`w:tcW`). When they disagree Word shows a table wider than the text block or columns that jump on the first edit.
+Table geometry is three things that must agree: the grid (`w:tblGrid`, one `w:gridCol` per column), the table width (`w:tblW`) and each cell width (`w:tcW`). When they disagree, Word shows a table wider than the text block, or columns that jump on the first edit.
 
 ## Create
 
-```bash
-"<python>" "<cli>" docx create --spec "<spec.json>" --out "<out.docx>"
-```
+Use `docx create --spec` with a table block:
 
 ```json
-{
-  "type": "table",
-  "headers": ["Region", "Revenue", "Growth"],
-  "rows": [["EMEA", "4.1M", "12%"], ["APAC", "3.2M", "9%"]],
-  "style": "Table Grid"
-}
+{ "type": "table", "headers": ["Region", "Q1"], "rows": [["North", "10"]], "style": "Table Grid" }
 ```
 
-Header cells are bold. For a document with the header repeating on every page, follow up with the a11y fix, which writes `w:tblHeader` on row 1:
+Header cells are bold. To repeat the header row on every page:
 
 ```bash
-"<python>" "<skill>/scripts/a11y_audit.py" "<out.docx>" --fix_table_headers first_row --out "<out-fixed.docx>"
+"<python>" "<skill>/scripts/a11y_audit.py" "<out.docx>" --fix_table_headers first_row --out "<out-fixed.docx"
 ```
 
+That writes `w:tblHeader` on row 1.
+
 ## Inspect and fix geometry
 
 ```bash
 "<python>" "<skill>/scripts/table_geometry.py" "<file.docx>"
-"<python>" "<skill>/scripts/table_geometry.py" "<file.docx>" --fix --out "<file-fixed.docx>"
+"<python>" "<skill>/scripts/table_geometry.py" "<file.docx>" --fix --out "<file-fixed.docx"
 ```
 
-The audit reports `tblW`, layout mode, every grid column in twips and the sum, plus the narrowest and widest cell. `--fix` writes a fixed-layout table at the text width (page width minus margins), rescales the grid proportionally and rewrites each `tcW` including `gridSpan`.
-
-Text width on Letter with 1in margins is 9360 twips — that is the number a full-width table should total.
+The audit reports `tblW`, the layout mode, every grid column in twips with their sum, and the narrowest and widest cell. `--fix` writes a fixed-layout table at the text width (page width minus margins), rescales the grid proportionally and rewrites each `tcW`, including `gridSpan`. On Letter with 1in margins the text width is 9360 twips.
 
-## Convert
+## Move data between formats
 
 ```bash
-"<python>" "<skill>/scripts/docx_table_to_csv.py" "<file.docx>" --table_index 0 --out "<table.csv>"
+"<python>" "<skill>/scripts/docx_table_to_csv.py" "<file.docx>" --table_index 0 --out "<table.csv"
 "<python>" "<skill>/scripts/xlsx_to_docx_table.py" "<book.xlsx>" --sheet Revenue --out "<table.docx>" --title "Revenue by region"
 ```
 
-The first flattens a Word table (expanding horizontal spans, repeating vertically merged values) for data work. The second imports a worksheet as a Word table with a bold header row and `w:tblHeader`, which is the route for "put this spreadsheet in the report" — not a screenshot and not an embedded object.
+`docx_table_to_csv.py` flattens the table, expands horizontal spans and repeats vertically merged values. `xlsx_to_docx_table.py` writes a bold header row plus `w:tblHeader`; it is the route for "put this spreadsheet in the report", not a screenshot or an embedded object.
 
 ## Design
 
-- Bold header row, light grey `#D9D9D9` borders, no shading inside the body.
-- Numeric columns right-aligned; text left-aligned. Thousands separators in the cells themselves.
-- Two or three columns of prose at most; a wide table wants landscape, and that means a section break (`tasks/sections_layout.md`), not a smaller font.
-- Caption above the table (`tasks/captions_crossrefs.md`), and keep it with the table.
-- Avoid vertical merges: they look fine in the file and confuse every downstream reader.
+- Bold header row, light grey `#D9D9D9` borders, no shading in the body.
+- Numeric right-aligned, text left-aligned, thousands separators inside the cells.
+- Two or three prose columns at most. A wide table wants landscape through a section break (`tasks/sections_layout.md`), not a smaller font.
+- Caption above the table (`tasks/captions_crossrefs.md`). Avoid vertical merges.
 
 ## Verify
 
-Render and look at the page the table lands on: nothing spills past the right margin, header row intact, no split row across pages, and the last column not truncated. A table that fits in the XML but overflows the page is a real defect, and only the render shows it.
+Render the page: nothing past the right margin, header row intact, no row split across pages, last column not truncated. A table that fits in XML but overflows the page is a real defect that only the render shows.
 
 ## Pitfalls
 
-- A table inside a table cell inherits the cell width; check the outer table first.
-- `autofit` is a request, not a guarantee — fixed layout plus explicit widths is the only thing that renders the same everywhere.
-- Cell margins default to 108 twips left/right; that is padding, not missing width.
+- A table inside a cell inherits the cell width, so check the outer table first.
+- `autofit` is a request, not a guarantee.
+- Cell margins default to 108 twips of padding.

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

@@ -1,53 +1,49 @@
 # Templates and style packs
 
-**Goal.** Make a new or existing document look like the house template, without copying the template's content into it.
-
-A `.dotx` is a `.docx` whose package is a template: `styles.xml` defines the look, `numbering.xml` defines lists, and the body is empty. Copying the body would import placeholder text; what you actually need is the styles part, the numbering definitions they reference, and the theme.
+A `.dotx` is a `.docx` whose package is a template: `styles.xml` defines the look, `numbering.xml` defines lists, the body is empty. What you need is the styles part, the numbering definitions they reference, and the theme. Copying the body imports placeholder text.
 
 ## Ask before guessing
 
-Do not invent a house style. Get from the user: heading fonts and sizes, body font and size, accent colour, margins, table style, and whether a logo or cover page is required. `references/template-elicitation.md` has the question set that produces a spec.
+Never invent a house style. Get heading fonts and sizes, body font and size, accent colour, margins, table style, and any logo or cover requirement. `references/template-elicitation.md` holds the question set.
 
-## Apply a template
+## Apply
 
 ```bash
-"<python>" "<skill>/scripts/apply_template_styles.py" --template "<house.dotx>" --target "<draft.docx>" --out "<draft-styled.docx>"
+"<python>" "<skill>/scripts/apply_template_styles.py" --template "<house.dotx>" --target "<draft.docx>" --out "<draft-styled.docx"
 ```
 
-The script merges the template's style definitions by `styleId` (replacing same-id definitions, appending missing ones, taking the template's `docDefaults`), and copies `numbering.xml` with its relationship and content-type override. The target's body is untouched, so the content survives and the look changes.
+Merges style definitions by `styleId` (replacing same-id, appending missing, taking the template's `docDefaults`) and copies `numbering.xml` with its relationship and content-type override. The target's body is untouched.
 
-Then normalize so direct formatting does not override the template:
+Then normalise so direct formatting does not override the imported styles:
 
 ```bash
-"<python>" "<skill>/scripts/style_normalize.py" "<draft-styled.docx>" --out "<draft-final.docx>" --clear_paragraph_format
+"<python>" "<skill>/scripts/style_normalize.py" "<draft-styled.docx>" --out "<draft-final.docx" --clear_paragraph_format
 ```
 
 ## Restyle without a template
 
-When the user describes the style instead of supplying a file, set it on the styles rather than on runs:
+Set values on styles, not on runs:
 
-```bash
-"<python>" - <<'PY'
+```python
 from docx import Document
 from docx.shared import Pt, RGBColor
+
 d = Document(r"<draft.docx>")
-normal = d.styles["Normal"]
-normal.font.name = "Calibri"
-normal.font.size = Pt(11)
+d.styles["Normal"].font.name = "Calibri"
+d.styles["Normal"].font.size = Pt(11)
 for level, size in ((1, 18), (2, 14), (3, 12)):
     style = d.styles[f"Heading {level}"]
     style.font.size = Pt(size)
     style.font.color.rgb = RGBColor(0, 0, 0)
-d.save(r"<draft-styled.docx>")
-PY
+d.save(r"<draft-restyled.docx>")
 ```
 
 ## Verify
 
-Render and compare against the template's own preview page by page: heading sizes, body leading, margins, table borders. A style page that looks right in a style list but wrong on the page usually means a direct-formatting run left over — run the lint.
+Render and compare page by page with the template's own preview: heading sizes, body leading, margins, table borders. A style that looks right in the pane but wrong on the page usually has a leftover direct-formatting run — run the lint (`tasks/style_lint_normalize.md`).
 
 ## Pitfalls
 
-- A template applied over content that references missing styles produces the fallback look, not an error; run `style_lint.py` to find undefined references.
-- Themes (`word/theme/theme1.xml`) carry fonts and accent colours; a style that names a theme font changes when the theme does.
-- Keeping the template's `numbering.xml` without its `abstractNum` ids produces lists that all share one counter.
+- A template applied over content that references missing styles produces the fallback look, not an error; run `style_lint.py`.
+- Themes (`word/theme/theme1.xml`) carry fonts and accent colours, so theme-font styles change with the theme.
+- Keeping the template's `numbering.xml` without its abstractNum ids makes lists share one counter.

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

@@ -1,26 +1,22 @@
 # Table of contents
 
-**Goal.** Put a navigable contents list at the front of the document, built from heading styles rather than typed by hand.
+A TOC is a `TOC` field: Word fills it on recalculation and the file stores the last result. A hand-typed list looks identical, then goes wrong on the first edit.
 
-The TOC is a `TOC` field. Word fills it in when it recalculates; the file stores the last result. A hand-typed list looks identical in a screenshot and then goes wrong on the first edit.
-
-## Insert
+Insert:
 
 ```bash
 "<python>" "<skill>/scripts/insert_toc.py" "<file.docx>" --out "<file-toc.docx>" --levels 1-3
 ```
 
-The script looks for a placeholder paragraph containing `[[TOC]]` (override with `--placeholder`). If there is none it inserts the field at the start of the body. It writes `TOC \o "1-3" \h \z \u`, sets `w:updateFields`, and adds a short cached hint so the page is not blank before recalculation.
+The script fills a placeholder paragraph containing `[[TOC]]` (override with `--placeholder`); with no placeholder it inserts the field at the start of the body. It writes `TOC \o "1-3" \h \z \u`, sets `w:updateFields`, and leaves a short cached hint so the page is not blank before recalculation.
 
-Check that every heading you want in the list uses a heading style: `heading_audit.py` finds headings formatted by hand, which the TOC will silently skip.
+Every heading you want listed must use a heading style. `heading_audit.py` finds hand-formatted headings that the TOC silently skips.
 
 ## Rebuild after edits
 
-If headings changed, the cached list is stale. Either ask the user to update the field in Word (right-click → Update Field), or regenerate: strip the old field with `fields_materialize.py`? — no, that freezes it. Instead delete the field paragraphs and run `insert_toc.py` again. Freezing a TOC is almost never what a reader wants.
-
-## Static contents list
+The cached list goes stale after a structural edit. Ask the user to update the field in Word (right-click → Update Field), or delete the field paragraphs and re-run `insert_toc.py`. Do not freeze a TOC with `fields_materialize.py`.
 
-Sometimes the requirement really is a fixed list — a PDF export that will not be recalculated, or a template with a hand-built contents page. `internal_nav.py` builds one: a heading plus hyperlink entries to every heading, with optional back-links.
+For a fixed PDF export or a hand-built template contents page, generate a static list with `internal_nav.py` instead:
 
 ```bash
 "<python>" "<skill>/scripts/internal_nav.py" "<file.docx>" --out "<file-nav.docx>" --levels 1 2
@@ -30,10 +26,10 @@ See `tasks/navigation_internal_links.md`.
 
 ## Verify
 
-Render the first pages and read them. A TOC that shows one line of grey hint text means the field never recalculated in that renderer; a TOC that shows the old headings means the document was rendered before the field updated. Say which one happened instead of claiming the TOC is correct.
+Render the first pages. A line of grey hint text means the renderer never recalculated the field; old headings mean it rendered before the update. Say which happened instead of claiming the contents are correct.
 
 ## Pitfalls
 
-- TOC entries come from outline levels, not from text that merely looks like a heading.
-- A TOC inside a header or a text box does not work; it belongs in the body.
-- Level 4+ headings are excluded unless you widen `--levels`.
+- TOC entries come from outline levels, not from text that looks like a heading.
+- A TOC in a header or text box does not work — body only.
+- Level 4 and deeper are excluded unless you widen `--levels`.

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

@@ -1,50 +1,38 @@
 # Visual verification
 
-**Goal.** See the pages before the user does. A document that parses and a document that looks right are different claims.
-
-## Render
+See the pages before the user does. A document that parses and a document that looks right are different claims.
 
 ```bash
 "<python>" "<cli>" docx render --input "<file.docx>" --out-dir "<render-dir>"
 ```
 
-Writes one PNG per page and prints their paths plus the renderer it used (`libreoffice-kit`); add `--pdf` to also keep a PDF. Use the same command through `render_docx.py` when you want the JSON report and page list:
+Writes one PNG per page and prints the paths plus the renderer it used (`libreoffice-kit`); add `--pdf` to keep a PDF as well. For a JSON report and page list use `render_docx.py`:
 
 ```bash
 "<python>" "<skill>/render_docx.py" "<file.docx>" --output_dir "<render-dir>" --dpi 150
 ```
 
-## Inspect
-
 Open every PNG with `read_image` and check, in this order:
 
 1. **Hierarchy** — does the page show the structure the user asked for, at a glance?
 2. **Fit** — nothing past the right margin, no clipped table column, no text over a watermark.
 3. **Breaks** — no heading alone at the bottom, no orphaned caption, no half-empty page before a section break.
-4. **Text** — the words that were meant to change did change, and nothing else moved.
+4. **Text** — the intended words changed, and nothing else moved.
 5. **Glyphs** — dashes, quotes, CJK, currency symbols and maths render, not as boxes.
-6. **Header and footer** — present, correct, not repeated on a first page that should not have it.
+6. **Header and footer** — present, correct, and not repeated on a first page that should not have one.
 
-## When no renderer exists
+Re-render after any script edit. Package-valid is not page-valid: a caption placed before the paragraph it describes, a table grown past the margin, a style merge that changed heading sizes — all are invisible in the XML and obvious in the image. To compare two revisions, `render_and_diff.py` writes a heatmapped difference page; read the diff images yourself, because a ratio is not a conclusion.
 
-The runtime reports `renderers.can_render.docx: false` because the DSH LibreOffice kit was not found. `render` then exits non-zero with a JSON error naming the missing renderer, and `render_docx.py` exits 3 with `reason: no_renderer`.
+## When no renderer exists
 
-In that state:
+`office_status` reports `renderers.available: false` (with a `remedy`) because the DSH LibreOffice kit was not found. `render` then exits non-zero with a JSON error naming the missing renderer, and `render_docx.py` exits 3 with `reason: no_renderer`.
 
 - Verify structure with `docx read`, `docx_kit.py parts|text|xml` and the audit scripts.
-- Tell the user plainly that layout was not visually verified, and that the fix is a harness install that ships the kit (the plugin records its path in `config.json` when it loads), not installing Word/LibreOffice.
-- Do not claim a file "looks good" from XML evidence alone.
-
-## After any script edit
-
-Re-render. Package-valid is not page-valid: a caption inserted before the paragraph it describes, a table grown past the margin, a style merge that changed heading sizes — all are invisible to the XML and obvious in the image.
-
-## Comparing revisions
-
-`render_and_diff.py` renders two files and writes a heatmapped difference page. Read the diff images yourself; a ratio is not a conclusion.
+- Say plainly that layout was not visually verified, and that the fix is a harness install shipping the kit (the plugin records its path in `config.json` when it loads), not installing Word or LibreOffice.
+- Never claim a file "looks good" from XML evidence alone.
 
 ## Pitfalls
 
 - Different renderers paginate differently. Compare like with like, and do not promise Word-perfect pagination from a LibreOffice render.
-- A render fails silently into a blank page when a font is missing; a blank page is a finding, not a rendering bug. `missing_fonts` / `glyph_fallback` in the render JSON tells you substitution happened.
-- Render into a fresh directory; stale PNGs from an earlier run are the classic false pass.
+- A missing font turns into a blank page: that is a finding, not a rendering bug. `missing_fonts` / `glyph_fallback` in the render JSON shows substitution happened.
+- Render into a fresh directory: stale PNGs from an earlier run are the classic false pass.

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

@@ -1,35 +1,31 @@
-# Watermarks and background text
+# Watermarks and background marks
 
-**Goal.** A diagonal DRAFT / CONFIDENTIAL mark behind the page content, and the ability to find and remove one that a template left behind.
-
-A Word watermark is not a document feature with its own element: it is a VML shape (`v:shape` with `v:textpath`) in a header part, positioned behind the text. That is why it disappears if the header is replaced, and why it can appear on some pages and not others when sections have their own headers.
+A Word watermark is not its own element: it is a VML shape (`v:shape` with `v:textpath`) inside a header part, behind the text. That is why it disappears when the header is replaced and can differ per section.
 
 ## Add
 
 ```bash
-"<python>" "<skill>/scripts/watermark_add.py" "<file.docx>" --out "<file-draft.docx>" --text "DRAFT"
+"<python>" "<skill>/scripts/watermark_add.py" "<file.docx>" --out "<file-draft.docx" --text "DRAFT"
 ```
 
-Writes the shape into the default header, light grey, rotated -45°, behind the body. The script refuses to add a second watermark when it finds one — remove the old one first, or you get two overlapping marks.
-
-For a per-page mark across a document with several sections, each section's header needs the shape; that is a loop over sections, not one insertion.
+Writes the shape into the default header: light grey, rotated -45°, behind the body. The script refuses to add a second watermark when it finds one, so remove the old one first. For a mark on every page across sections, each section's header needs the shape — loop over the sections.
 
 ## Find and remove
 
 ```bash
 "<python>" "<skill>/scripts/watermark_audit_remove.py" "<file.docx>" --mode report
-"<python>" "<skill>/scripts/watermark_audit_remove.py" "<file.docx>" --mode remove --out "<file-clean.docx>"
+"<python>" "<skill>/scripts/watermark_audit_remove.py" "<file.docx>" --mode remove --out "<file-clean.docx"
 ```
 
-The report lists the text of every VML text path and the part it lives in, and exits 1 when any watermark exists. `--contains` narrows to a substring, which is the case "the template says Company Confidential and it should not". Remove deletes the enclosing paragraph from the header.
+The report lists every VML text path and the part it lives in, and exits 1 when any watermark exists. `--contains` narrows it to a substring, for the "template says Company Confidential" case. Remove deletes the enclosing paragraph from the header.
 
 ## Verify
 
-Render and read the pages: the mark sits behind the text (not over it), stays inside the page, and appears on every page the user expects. A watermark that vanishes on page two means that section has a different header.
+Render and read the pages: the mark sits behind the text, inside the page, on every expected page. A watermark missing on page two means that section has a different header.
 
 ## Pitfalls
 
-- A watermark in a "different first page" header only shows on page one.
-- Removing the header paragraph can leave an empty header that adds vertical space; check the top margin on the rendered page.
-- An image watermark is an `v:imagedata` shape, not a text path — the report will not name it, so inspect the header XML when the visual mark is a logo.
-- Watermarks are not security. See `tasks/protection_restrict_editing.md` for what actually restricts editing.
+- A watermark in a "different first page" header shows only on page one.
+- Removing the header paragraph can leave an empty header that adds vertical space — check the top margin.
+- An image watermark is `v:imagedata`, not a text path, so the report will not name it; inspect the header XML.
+- A watermark is not security (`tasks/protection_restrict_editing.md`).