dsh-office-kit 0.1.0 → 0.3.0

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

@@ -0,0 +1,167 @@
+#!/usr/bin/env python
+"""Audit table widths in twips, and optionally make every table fit the page.
+
+Word stores table widths three ways (``tblW``, grid columns, cell widths) and they
+disagree often enough that a table overflows the margin after a page-size change.
+``--fix`` makes the table fixed-layout and distributes the text width across the
+grid, writing the same number to each cell so the two can no longer disagree.
+
+Exit codes: 0 clean, 1 problems found (without --fix), 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
+
+
+def text_width_twips(doc: kit.Docx) -> int:
+    sections = doc.sections()
+    if not sections:
+        return 9360
+    sect = sections[0]
+    page = sect.find(kit.q("pgSz"))
+    margins = sect.find(kit.q("pgMar"))
+    width = int(page.get(kit.q("w")) or 12240) if page is not None else 12240
+    if margins is None:
+        return width - 2880
+    return width - sum(int(margins.get(kit.q(side)) or 0) for side in ("left", "right"))
+
+
+def grid_widths(table) -> list[int]:
+    grid = table.find(kit.q("tblGrid"))
+    if grid is None:
+        return []
+    widths = []
+    for column in grid.findall(kit.q("gridCol")):
+        value = column.get(kit.q("w"))
+        widths.append(int(value) if value and value.lstrip("-").isdigit() else 0)
+    return widths
+
+
+def table_info(table) -> dict:
+    props = table.find(kit.q("tblPr"))
+    width = None
+    layout = None
+    if props is not None:
+        node = props.find(kit.q("tblW"))
+        if node is not None:
+            width = {"type": node.get(kit.q("type")), "value": node.get(kit.q("w"))}
+        node = props.find(kit.q("tblLayout"))
+        if node is not None:
+            layout = node.get(kit.q("type"))
+    widths = grid_widths(table)
+    cells = table.findall(".//" + kit.q("tc"))
+    cell_widths = []
+    for cell in cells:
+        node = cell.find(kit.q("tcPr") + "/" + kit.q("tcW"))
+        if node is not None and (node.get(kit.q("w")) or "").isdigit():
+            cell_widths.append(int(node.get(kit.q("w"))))
+    return {
+        "tblW": width,
+        "layout": layout,
+        "grid_twips": widths,
+        "grid_total": sum(widths),
+        "cells": len(cells),
+        "cell_width_min": min(cell_widths) if cell_widths else None,
+        "cell_width_max": max(cell_widths) if cell_widths else None,
+    }
+
+
+def fix_table(table, target: int) -> None:
+    props = table.find(kit.q("tblPr"))
+    if props is None:
+        props = etree.Element(kit.q("tblPr"))
+        table.insert(0, props)
+    for tag in ("tblW", "tblLayout"):
+        for existing in props.findall(kit.q(tag)):
+            props.remove(existing)
+    width = etree.SubElement(props, kit.q("tblW"))
+    width.set(kit.q("type"), "dxa")
+    width.set(kit.q("w"), str(target))
+    etree.SubElement(props, kit.q("tblLayout")).set(kit.q("type"), "fixed")
+
+    columns = grid_widths(table)
+    if not columns:
+        columns = [1]
+    total = sum(columns) or len(columns)
+    scaled = [max(1, round(target * value / total)) for value in columns]
+    grid = table.find(kit.q("tblGrid"))
+    if grid is None:
+        grid = etree.Element(kit.q("tblGrid"))
+        table.insert(1, grid)
+    for column in list(grid):
+        grid.remove(column)
+    for value in scaled:
+        etree.SubElement(grid, kit.q("gridCol")).set(kit.q("w"), str(value))
+
+    for row in table.findall(kit.q("tr")):
+        position = 0
+        for cell in row.findall(kit.q("tc")):
+            span = 1
+            cell_props = cell.find(kit.q("tcPr"))
+            if cell_props is None:
+                cell_props = etree.Element(kit.q("tcPr"))
+                cell.insert(0, cell_props)
+            node = cell_props.find(kit.q("gridSpan"))
+            if node is not None and (node.get(kit.q("val")) or "").isdigit():
+                span = int(node.get(kit.q("val")))
+            own = sum(scaled[position : position + span]) or scaled[0]
+            for existing in cell_props.findall(kit.q("tcW")):
+                cell_props.remove(existing)
+            tcw = etree.SubElement(cell_props, kit.q("tcW"))
+            tcw.set(kit.q("type"), "dxa")
+            tcw.set(kit.q("w"), str(own))
+            position += span
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Audit table geometry in twips and optionally fit tables to the text width.")
+    parser.add_argument("docx", help="Input .docx")
+    parser.add_argument("--fix", action="store_true", help="Set fixed layout and rewrite grid/cell widths to fit the page")
+    parser.add_argument("--out", default=None, help="Output .docx (required with --fix, defaults to overwriting)")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    target = text_width_twips(doc)
+    tables = list(doc.body().iter(kit.q("tbl")))
+    rows = [table_info(table) for table in tables]
+    findings = []
+    for index, info in enumerate(rows, start=1):
+        if info["grid_total"] and info["grid_total"] > target:
+            findings.append({"kind": "grid_wider_than_text", "table": index, "grid_total": info["grid_total"], "text_width": target})
+        if info["layout"] != "fixed":
+            findings.append({"kind": "not_fixed_layout", "table": index})
+        if info["cell_width_max"] and info["grid_total"] and info["cell_width_max"] > info["grid_total"]:
+            findings.append({"kind": "cell_wider_than_grid", "table": index})
+        if info["tblW"] and info["tblW"]["type"] == "pct" and not info["grid_total"]:
+            findings.append({"kind": "percent_width_without_grid", "table": index})
+
+    if args.fix:
+        if not tables:
+            print("error: no tables found", file=sys.stderr)
+            return 2
+        for table in tables:
+            fix_table(table, target)
+        out = args.out or args.docx
+        doc.save(out)
+        kit.emit({"ok": True, "fixed": True, "output": str(Path(out)), "tables": len(tables), "text_width": target, "findings": findings})
+        return 0
+
+    kit.emit({"ok": not findings, "text_width": target, "tables": rows, "findings": findings})
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+"""Add a diagonal text watermark to the page background.
+
+The watermark is a VML text shape in the default header, which is how Word has
+stored them since the 2007 file format: it survives conversion, prints on every
+page, and can be removed again by deleting the header shape.
+
+Exit codes: 0 success, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Add a VML text watermark to the document header.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--text", required=True, help="Watermark text, e.g. CONFIDENTIAL")
+    parser.add_argument("--color", default="#C0C0C0", help="Shape fill colour (hex)")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.input_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    if kit.watermark_texts(doc):
+        print("error: this document already has a watermark; remove it first", file=sys.stderr)
+        return 2
+
+    part = doc.ensure_header_footer("header")
+    root = doc.xml(part)
+    root.append(kit.watermark_paragraph(args.text, doc.next_id(), args.color))
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "text": args.text, "part": part})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,67 @@
+#!/usr/bin/env python
+"""Find and remove VML text watermarks from headers.
+
+A watermark that was meant for a draft can end up in a signed document, and it is
+invisible in text extraction because it lives in a shape, not in a paragraph run.
+
+Exit codes: 0 clean, 1 watermarks found (report mode), 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Report or remove watermarks stored as VML shapes in headers.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--mode", choices=("report", "remove"), default="report")
+    parser.add_argument("--contains", default=None, help="Only match watermarks containing this text")
+    parser.add_argument("--out", default=None, help="Output .docx for --mode remove")
+    args = parser.parse_args(argv)
+
+    if args.mode == "remove" and not args.out:
+        print("error: --mode remove needs --out", file=sys.stderr)
+        return 2
+
+    try:
+        doc = kit.Docx(args.input_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    found = kit.watermark_texts(doc)
+    if args.contains:
+        wanted = args.contains.lower()
+        found = [item for item in found if wanted in (item["text"] or "").lower()]
+
+    removed = 0
+    if args.mode == "remove" and found:
+        for item in found:
+            paragraph = item["paragraph"]
+            if paragraph is not None and paragraph.getparent() is not None:
+                paragraph.getparent().remove(paragraph)
+                removed += 1
+        doc.save(args.out)
+    elif args.mode == "remove":
+        doc.save(args.out)
+
+    kit.emit(
+        {
+            "ok": args.mode == "remove" or not found,
+            "mode": args.mode,
+            "watermarks": [{"part": item["part"], "text": item["text"]} for item in found],
+            "removed": removed,
+            "output": str(Path(args.out)) if args.out else None,
+        }
+    )
+    return 0 if (args.mode == "remove" or not found) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,117 @@
+#!/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
+
+
+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.