dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/office-documents/scripts/xlsx_to_docx_table.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python
+"""Copy a worksheet range into a Word table.
+
+The header row is bolded and marked as a repeating header so it appears again
+when the table breaks across pages, which is the detail hand-built tables usually
+miss.  This script uses python-docx directly because it creates a new document
+rather than editing an existing one.
+
+Exit codes: 0 success, 1 sheet or data not found, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+from docx import Document
+from docx.enum.table import WD_TABLE_ALIGNMENT
+from docx.shared import Pt
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def cell_text(value) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return str(value).strip()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Build a .docx whose body is a table filled from an .xlsx sheet.")
+    parser.add_argument("xlsx", help="Input .xlsx")
+    parser.add_argument("output_docx", nargs="?", default=None, help="Output .docx")
+    parser.add_argument("--out", default=None, help="Output .docx (alternative to the positional argument)")
+    parser.add_argument("--sheet", default=None, help="Sheet name (default: the active sheet)")
+    parser.add_argument("--header_rows", type=int, default=1, help="Rows to treat as headers (default 1)")
+    parser.add_argument("--title", default=None, help="Heading added above the table")
+    args = parser.parse_args(argv)
+
+    out = args.out or args.output_docx
+    if not out:
+        parser.error("provide an output path (positional or --out)")
+
+    try:
+        from openpyxl import load_workbook
+    except ImportError:
+        print("error: openpyxl is required to read .xlsx", file=sys.stderr)
+        return 2
+
+    try:
+        workbook = load_workbook(args.xlsx, data_only=True, read_only=True)
+    except OSError as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    if args.sheet:
+        if args.sheet not in workbook.sheetnames:
+            print("error: sheet %r not found (have %s)" % (args.sheet, ", ".join(workbook.sheetnames)), file=sys.stderr)
+            return 1
+        sheet = workbook[args.sheet]
+    else:
+        sheet = workbook[workbook.sheetnames[0]]
+
+    rows = [[cell_text(value) for value in row] for row in sheet.iter_rows(values_only=True)]
+    rows = [row for row in rows if any(cell for cell in row)]
+    if not rows:
+        print("error: sheet %r has no data" % sheet.title, file=sys.stderr)
+        return 1
+
+    width = max(len(row) for row in rows)
+    rows = [row + [""] * (width - len(row)) for row in rows]
+    header_count = max(0, min(args.header_rows, len(rows)))
+
+    document = Document()
+    if args.title:
+        document.add_heading(args.title, level=1)
+
+    table = document.add_table(rows=len(rows), cols=width)
+    table.style = "Table Grid"
+    table.alignment = WD_TABLE_ALIGNMENT.CENTER
+    for row_index, row in enumerate(rows):
+        for column_index, value in enumerate(row):
+            cell = table.cell(row_index, column_index)
+            cell.text = value
+            if row_index < header_count:
+                for paragraph in cell.paragraphs:
+                    for run in paragraph.runs:
+                        run.bold = True
+                        run.font.size = Pt(11)
+
+    document.save(out)
+    payload = {"ok": True, "output": str(Path(out)), "sheet": sheet.title, "rows": len(rows), "columns": width, "header_rows": header_count}
+
+    if header_count:
+        doc = kit.Docx(out)
+        first_row = doc.body().find(".//" + kit.q("tr"))
+        if first_row is not None:
+            props = first_row.find(kit.q("trPr"))
+            if props is None:
+                props = etree.Element(kit.q("trPr"))
+                first_row.insert(0, props)
+            etree.SubElement(props, kit.q("tblHeader"))
+            doc.save(out)
+            payload["header_row_repeats"] = True
+
+    kit.emit(payload)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

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

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

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

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

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

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

@@ -0,0 +1,59 @@
+# Comments
+
+**Goal.** Add a review comment, read the comments someone else left, reply or resolve them, and remove comments before the document goes out.
+
+Comments are not text: each one is a `w:comment` in `word/comments.xml`, anchored in the body by a `w:commentRangeStart` / `w:commentRangeEnd` pair plus a `w:commentReference` run. Editing the anchor without the comments part (or the reverse) leaves a document Word reports as corrupt.
+
+## Add
+
+```bash
+"<python>" "<skill>/scripts/comments_add.py" "<file.docx>" --out "<file-commented.docx>" \
+  --author "Review" --add "Renewals=Check the source of this claim" --add "42 new accounts=Who verified this?"
+```
+
+Each `--add` is `NEEDLE=COMMENT`. The needle is matched inside a paragraph; the anchored range covers exactly the matched text, so pick a distinctive phrase. `--ignore_case` relaxes matching, `--require_all` writes nothing and exits 1 if any needle is missing — use it when the comment set must be complete.
+
+## Extract
+
+```bash
+"<python>" "<skill>/scripts/comments_extract.py" "<file.docx>" --out "<comments.json>"
+```
+
+Returns `id`, `author`, `initials`, `date`, `text`, `anchored_text`, `part` and `resolved`. An empty array means the file has no comments — do not assume comments exist because the user mentioned them.
+
+## Patch or resolve
+
+```bash
+"<python>" "<skill>/scripts/comments_apply_patch.py" "<file.docx>" "<patch.json>" --out "<file-patched.docx>"
+```
+
+```json
+{
+  "ops": [
+    { "id": 1, "append": "Confirmed against the ledger." },
+    { "id": 2, "replace": "Resolved: revenue restated in Q3." },
+    { "id": 1, "resolved": true }
+  ]
+}
+```
+
+`replace` rewrites the comment's first paragraph, `append` adds a paragraph, `resolved` sets the `w15:done` flag. The command exits 1 and names the ids it could not find.
+
+## Remove
+
+```bash
+"<python>" "<skill>/scripts/comments_strip.py" "<file.docx>" --out "<file-clean.docx>"
+```
+
+Removes every anchor, drops `word/comments.xml`, its relationship and content-type override. Removing comments is required before sharing a file with a customer; check `privacy_scrub_metadata.md` too.
+
+## Verify
+
+`comments_extract.py` on the output (count and anchors), then render the page the comment sat on — a stripped anchor that leaves an empty run can show as a stray space.
+
+## Pitfalls
+
+- A comment anchored to a paragraph mark rather than text shows no `anchored_text`; that is normal for "comment on the whole paragraph".
+- Two comments cannot share an id. `comments_add.py` continues from the highest existing id.
+- The comment body is ordinary paragraphs, so a long comment can contain several; `comments_extract.py` joins them with newlines.
+- Replying in-thread needs Word's `commentsExtended` part. Anchoring a new comment on the same phrase is the portable equivalent.

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

@@ -0,0 +1,40 @@
+# Compare two versions
+
+**Goal.** Say what actually changed between two files, with evidence — not "the text differs somewhere".
+
+Two useful comparisons: text-level (what words changed) and page-level (what the reader sees changed). Use both; a change in a style definition can leave the text identical and move every paragraph.
+
+## Page-level diff
+
+```bash
+"<python>" "<skill>/scripts/render_and_diff.py" "<before.docx>" "<after.docx>" --outdir "<render-dir>" --dpi 120
+```
+
+Renders both through the helper CLI, pairs the pages, and writes `diff-NN.png` coloured by pixel difference. Reports which pages changed, the fraction of pixels differing, and a page-count delta.
+
+The exit code is 3 when no renderer is available: render both files another way, or compare text only and say which comparison you could not run.
+
+## Text-level diff
+
+```bash
+"<python>" "<skill>/scripts/docx_kit.py" text '<before.docx>' > before.json
+"<python>" "<skill>/scripts/docx_kit.py" text '<after.docx>'  > after.json
+```
+
+Diff the two paragraph dumps (any diff tool, or a few lines of Python). This is the reliable way to separate content changes from layout changes.
+
+## Review mode versus diff mode
+
+If the user wants the *document* to carry the changes, use tracked changes (`tasks/clean_tracked_changes.md`) rather than a report: the reviewer accepts or rejects inside Word. A diff is evidence for a conversation; tracked changes are the artefact.
+
+For a version that arrived with markup, `accept_tracked_changes.py --mode report` is the change list, with reviewer names and where each edit sits.
+
+## Verify
+
+Open the diff PNGs with `read_image` and look at them: a coloured block on a page that should not have changed usually means a font substitution or a margin change, not a content change. Cross-check with the text diff before writing a conclusion.
+
+## Pitfalls
+
+- Different renderers paginate differently; compare renders made by the same renderer and the same settings.
+- Metadata and revision ids differ between saves and never appear on a page — a text diff of `word/document.xml` is noisy for that reason.
+- An image replaced in place keeps the same relationship and page position; only a pixel comparison notices.

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.