dsh-office-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,107 @@
+# Create or edit a document
+
+**Goal.** Produce a `.docx` that opens cleanly in Word, with real heading styles, real lists and real tables, then change it later without destroying what is already there.
+
+## Create
+
+Write a JSON spec next to the output, then run:
+
+```bash
+"<python>" "<cli>" docx create --spec "<spec.json>" --out "<out.docx>"
+```
+
+```json
+{
+  "title": "Regional revenue review",
+  "subtitle": "FY26 Q2",
+  "author": "Finance",
+  "header": "Internal — do not circulate",
+  "footer": "FY26 Q2 review",
+  "page_size": "Letter",
+  "orientation": "portrait",
+  "blocks": [
+    { "type": "heading", "level": 1, "text": "Summary" },
+    { "type": "paragraph", "text": "Revenue grew 18% year over year." },
+    { "type": "bullets", "items": ["Renewals at 92%", "42 new accounts"] },
+    { "type": "table", "headers": ["Region", "Revenue"], "rows": [["EMEA", "4.1M"], ["APAC", "3.2M"]] },
+    { "type": "page_break" }
+  ]
+}
+```
+
+Block types and keys: `heading` (`level`, `text`), `paragraph` (`text`, `bold`, `italic`, `size`, `color`, `align`, `style`), `bullets` / `numbered` (`items`), `table` (`headers`, `rows`, optional `style`, default `Table Grid`), `image` (`path`, optional `width` in inches), `equation` (`latex`), `quote`, `page_break`, `spacer`. Page keys: `page_size` (`Letter` or `A4`), `orientation`, and `top_margin` / `bottom_margin` / `left_margin` / `right_margin` in inches.
+
+The command prints counts for headings, paragraphs, list items, tables, images and equations. Check `equation_fallbacks`: a non-zero value means some LaTeX was emitted as styled text instead of OMML.
+
+## Edit
+
+The helper CLI does not mutate documents. Every edit is a script that reads the original, writes a copy, and refuses to overwrite its input. Omit `--out` and the copy lands next to the source as `<name>-edited.docx`.
+
+Replace text — body, tables, and every header and footer:
+
+```bash
+"<python>" "<skill>/scripts/replace_text.py" --input "<original.docx>" --out "<original-edited.docx>" \
+  --find "18%" --replace "21%" --find "Hardware flat" --replace "Hardware steady"
+```
+
+`--find` / `--replace` are paired in order; `--spec edits.json` takes `{"replace": [{"find": "...", "replace": "..."}]}` instead. The command prints a per-pair count. A match inside one run keeps that run's formatting; a match that straddles runs collapses the paragraph into its first run, so keep needles inside a single styled span when mixed formatting matters. `--require-all` exits 1 if a pair matched nothing, which is the check you want for a scripted edit.
+
+Append blocks — the same block types `docx create` accepts:
+
+```bash
+"<python>" "<skill>/scripts/append_blocks.py" --input "<original.docx>" --out "<original-edited.docx>" --blocks "blocks.json"
+```
+
+```json
+[{ "type": "heading", "level": 1, "text": "Appendix" }, { "type": "table", "headers": ["Region", "Revenue"], "rows": [["EMEA", "4.1M"]] }]
+```
+
+`--spec` takes a full document spec and appends its `blocks` array. The builder is the CLI's own, so anything that works in `docx create` works here, including images (`path`, `width`) and equations (`latex`).
+
+Set properties:
+
+```bash
+"<python>" "<skill>/scripts/core_properties.py" --input "<original.docx>" --out "<original-edited.docx>" \
+  --title "Regional revenue review (final)" --author "Finance" --keywords "revenue, FY26"
+```
+
+`--show` reports the current properties without writing; the same names work in `--spec core.json` under a `core` object.
+
+Three independent scripts means a pipeline writes an intermediate copy (append, then properties). That is deliberate: each step is re-runnable and its output is a valid document you can inspect.
+
+## When the CLI is not enough
+
+| Need | Route |
+|---|---|
+| Edit inside a header, footer, footnote or comment | `scripts/docx_kit.py xml <file> <part>` to inspect, then the snippet below or a purpose script |
+| Mark edits as tracked changes | `scripts/add_tracked_replacements.py`, `tasks/clean_tracked_changes.md` |
+| Header date, footer page numbers, first hyperlink | `scripts/docx_ooxml_patch.py` |
+| Replace a paragraph but keep its formatting | `python-docx` snippet below |
+
+```bash
+"<python>" - <<'PY'
+from docx import Document
+d = Document(r"<file.docx>")
+for p in d.paragraphs:
+    if "18%" in p.text:
+        runs = p.runs or [p.add_run()]
+        runs[0].text = p.text.replace("18%", "21%")
+        for r in runs[1:]:
+            r.text = ""
+        break
+d.save(r"<file-edited.docx>")
+PY
+```
+
+Editing `w:t` text directly (via `docx_kit`) is safe for plain word swaps; anything that changes paragraph structure should go through `python-docx` so the surrounding XML stays consistent.
+
+## Verify
+
+`docx read` to confirm text and counts, then render and look at every page (`tasks/verify_render.md`). A spec that produces three pages instead of two means the table or margins need work, not that the renderer is wrong.
+
+## Pitfalls
+
+- Deleting and retyping a heading loses its outline level; edit the text, keep the style.
+- `append_blocks.py` inserts before the final section properties, so a trailing landscape section or page setup keeps working.
+- Replacing text that lives in a field result changes only the cached value; the field recalculates on open in Word.
+- Copying content between documents by hand drops styles and relationships — use `scripts/merge_docx_append.py`.

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

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

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

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

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

@@ -0,0 +1,50 @@
+# Fixtures and 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 the fixture set
+
+```bash
+"<python>" "<skill>/scripts/make_fixtures.py" --outdir "<work-dir>" --only all
+```
+
+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 |
+
+`--only tracked|watermark|comments|edge` builds one.
+
+These are inputs for testing a change, not templates. Do not ship them.
+
+## The cases that break naive edits
+
+- **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 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.
+
+## 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.

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

@@ -0,0 +1,38 @@
+# 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 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 a note
+
+Put a marker where the reference belongs, then convert it:
+
+```bash
+"<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.
+
+## Report
+
+```bash
+"<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.
+
+## 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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,48 @@
+# Forms and content controls
+
+**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 `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
+
+```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.
+
+## Create
+
+```bash
+"<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.
+
+## Fill
+
+```bash
+"<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.
+
+## 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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,55 @@
+# 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.
+
+## Audit
+
+```bash
+"<python>" "<skill>/scripts/heading_audit.py" "<file.docx>" --max_findings 20
+```
+
+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.
+
+## 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:
+
+```bash
+"<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:
+
+```bash
+"<python>" - <<'PY'
+from docx import Document
+d = Document(r"<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
+```
+
+## 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.
+
+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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,63 @@
+# 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`.
+
+## Audit
+
+```bash
+"<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".
+
+## Fix alt text
+
+```bash
+"<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:
+
+```bash
+"<python>" - <<'PY'
+import sys
+from pathlib import Path
+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
+```
+
+## Insert
+
+```bash
+"<python>" "<cli>" docx create --spec "<spec.json>" --out "<out.docx>"
+```
+
+```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
+
+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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,43 @@
+# 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.
+
+## Append
+
+```bash
+"<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 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:
+
+```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>"
+```
+
+Then normalize direct formatting so the merged content matches:
+
+```bash
+"<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.
+
+## 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`.

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

@@ -0,0 +1,38 @@
+# Internal navigation
+
+**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.
+
+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
+
+```bash
+"<python>" "<skill>/scripts/internal_nav.py" "<file.docx>" --out "<file-nav.docx>" --levels 1 2 \
+  --toc_title "Contents"
+```
+
+What it does, in order:
+
+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`).
+
+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.
+
+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.
+
+## Static versus field-driven
+
+`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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,45 @@
+# Privacy: metadata and residue
+
+**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.
+
+`.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
+
+```bash
+"<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.
+
+## The rest of the 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` |
+
+Run them in that order — scrub metadata, resolve markup, then redact the text that survived.
+
+## Check before delivery
+
+```bash
+"<python>" "<skill>/scripts/docx_kit.py" parts '<file-clean.docx>'
+"<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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,41 @@
+# 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.
+
+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
+
+```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>"
+```
+
+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.
+
+`--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.
+
+## Which mode to pick
+
+| Intent | Mode |
+|---|---|
+| Review comments only, no text edits | `comments` |
+| All edits should be tracked | `trackedChanges` |
+| Fill a form, nothing else | `forms` |
+| View only | `readOnly` |
+
+## Remove
+
+```bash
+"<python>" "<skill>/scripts/set_protection.py" "<file-protected.docx>" --mode off --out "<file-open.docx>"
+```
+
+## 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.
+
+## 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.