dsh-office-kit 0.4.2 → 0.4.4

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

@@ -250,7 +250,7 @@ class Docx:
         while self.exists("word/%s%d.xml" % (kind, index)):
             index += 1
         part = "word/%s%d.xml" % (kind, index)
-        root = etree.Element(q(kind), nsmap={"w": W, "r": R, "wp": WP, "v": V})
+        root = etree.Element(q("hdr" if kind == "header" else "ftr"), nsmap={"w": W, "r": R, "wp": WP, "v": V})
         etree.SubElement(etree.SubElement(root, q("p")), q("r"))
         self.set_xml(part, root)
         self.ensure_override(part, CT_BY_REL[rel_type])
@@ -459,45 +459,86 @@ def add_bookmark(parent, name: str, ident: int) -> None:
 
 # -- watermarks -------------------------------------------------------------
 
-_WATERMARK_SHAPETYPE = """<v:shapetype xmlns:v="urn:schemas-microsoft-com:vml" id="_x0000_t136" coordsize="21600,21600" adj="10800" path="m@7,l@8,m@5,21600l@11,21600e"><v:formulas><v:f eqn="sum #0 0 10800"/><v:f eqn="prod #0 2 1"/><v:f eqn="sum 21600 0 @1"/><v:f eqn="sum 0 0 @2"/><v:f eqn="sum 21600 0 @3"/><v:f eqn="if @0 @3 0"/><v:f eqn="if @0 21600 @1"/><v:f eqn="if @0 0 @2"/><v:f eqn="if @0 @4 21600"/><v:f eqn="mid @5 @6"/><v:f eqn="mid @8 @5"/><v:f eqn="mid @7 @8"/><v:f eqn="mid @6 @7"/><v:f eqn="sum @6 0 @5"/></v:formulas><v:path textpathok="t"/><v:textpath on="t" fitshape="t"/><v:handles><v:h position="#0,bottomRight" xrange="6629,14971"/></v:handles></v:shapetype>"""
-
-_WATERMARK_STYLE = (
-    "position:absolute;margin-left:0;margin-top:0;width:468pt;height:117pt;"
-    "rotation:-45;z-index:-251658752;mso-position-horizontal:center;"
-    "mso-position-horizontal-relative:margin;mso-position-vertical:center;"
-    "mso-position-vertical-relative:margin"
-)
+WATERMARK_DESCR = "DSH Office watermark"
+
+_WATERMARK_ANCHOR = """<wp:anchor xmlns:wp="%(wp)s" xmlns:a="%(a)s" xmlns:w="%(w)s" xmlns:wps="%(wps)s"
+  distT="0" distB="0" distL="0" distR="0" simplePos="0" relativeHeight="251658240"
+  behindDoc="1" locked="0" layoutInCell="1" allowOverlap="1">
+  <wp:simplePos x="0" y="0"/>
+  <wp:positionH relativeFrom="page"><wp:align>center</wp:align></wp:positionH>
+  <wp:positionV relativeFrom="page"><wp:align>center</wp:align></wp:positionV>
+  <wp:extent cx="5486400" cy="1371600"/>
+  <wp:effectExtent l="0" t="0" r="0" b="0"/>
+  <wp:wrapNone/>
+  <wp:docPr id="%(id)d" name="PowerPlusWaterMarkObject%(id)d" descr="%(descr)s"/>
+  <wp:cNvGraphicFramePr/>
+  <a:graphic><a:graphicData uri="%(wps)s"><wps:wsp>
+    <wps:cNvSpPr/>
+    <wps:spPr>
+      <a:xfrm rot="-2700000"><a:off x="0" y="0"/><a:ext cx="5486400" cy="1371600"/></a:xfrm>
+      <a:prstGeom prst="rect"><a:avLst/></a:prstGeom>
+      <a:noFill/><a:ln><a:noFill/></a:ln>
+    </wps:spPr>
+    <wps:txbx><w:txbxContent><w:p><w:pPr><w:jc w:val="center"/></w:pPr>
+      <w:r><w:rPr><w:color w:val="%(color)s"/><w:sz w:val="120"/></w:rPr><w:t>%(text)s</w:t></w:r>
+    </w:p></w:txbxContent></wps:txbx>
+    <wps:bodyPr vert="horz" wrap="square" lIns="0" tIns="0" rIns="0" bIns="0"
+      anchor="ctr" anchorCtr="0"><a:noAutofit/></wps:bodyPr>
+  </wps:wsp></a:graphicData></a:graphic>
+</wp:anchor>"""
+
+_WPS_NS = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape"
 
 
 def watermark_paragraph(text: str, ident: int = 1, color: str = "#C0C0C0"):
-    """A header paragraph holding one VML text watermark."""
+    """A header paragraph holding one DrawingML text watermark.
+
+    Word stores watermarks as VML, but VML shapes are routinely dropped by other
+    renderers, so the shape here is DrawingML (wps) and marked with a stable
+    ``descr`` so it can be found and removed again.
+    """
+    from xml.sax.saxutils import escape
+
+    color = color.lstrip("#").upper() or "C0C0C0"
     paragraph = etree.Element(q("p"))
     run = etree.SubElement(paragraph, q("r"))
     run_props = etree.SubElement(run, q("rPr"))
     etree.SubElement(run_props, q("noProof"))
-    pict = etree.SubElement(run, q("pict"))
-    pict.append(etree.fromstring(_WATERMARK_SHAPETYPE))
-    shape = etree.SubElement(pict, q("shape", V))
-    shape.set("id", "WaterMarkObject%d" % ident)
-    shape.set("type", "#_x0000_t136")
-    shape.set("style", _WATERMARK_STYLE)
-    shape.set("fillcolor", color)
-    shape.set("stroked", "f")
-    textpath = etree.SubElement(shape, q("textpath", V))
-    textpath.set("style", 'font-family:"Calibri";font-size:1pt')
-    textpath.set("string", text)
+    drawing = etree.SubElement(run, q("drawing"))
+    anchor = etree.fromstring(_WATERMARK_ANCHOR % {
+        "wp": WP,
+        "a": A,
+        "w": W,
+        "wps": _WPS_NS,
+        "id": ident,
+        "descr": WATERMARK_DESCR,
+        "color": color,
+        "text": escape(str(text)),
+    })
+    drawing.append(anchor)
     return paragraph
 
 
+def _paragraph_above(node):
+    while node is not None and node.tag != q("p"):
+        node = node.getparent()
+    return node
+
+
 def watermark_texts(doc: Docx) -> list[dict]:
-    """Every VML text watermark in the headers, with the paragraph that holds it."""
+    """Every VML or DrawingML text watermark in the headers, with its paragraph."""
     found = []
     for part in doc.names("word/header"):
-        for textpath in doc.xml(part).iter(q("textpath", V)):
-            paragraph = textpath
-            while paragraph is not None and paragraph.tag != q("p"):
-                paragraph = paragraph.getparent()
-            found.append({"part": part, "text": textpath.get("string"), "paragraph": paragraph})
+        root = doc.xml(part)
+        for textpath in root.iter(q("textpath", V)):
+            text = textpath.get("string")
+            if text:
+                found.append({"part": part, "kind": "vml", "text": text, "paragraph": _paragraph_above(textpath)})
+        for pr in root.iter(q("docPr", WP)):
+            if pr.get("descr") != WATERMARK_DESCR:
+                continue
+            text = "".join(node.text or "" for node in pr.getparent().iter(q("t")))
+            found.append({"part": part, "kind": "drawingml", "text": text, "paragraph": _paragraph_above(pr)})
     return found
 
 

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

@@ -58,7 +58,8 @@ def main(argv: list[str] | None = None) -> int:
     for index, paragraph in enumerate(doc.paragraphs(), start=1):
         text = kit.paragraph_text(paragraph).strip()
         level = kit.heading_level(paragraph)
-        if level == 0:
+        style = (kit.paragraph_style(paragraph) or "").strip().lower()
+        if style == "title":
             outline.append({"index": index, "style": "Title", "text": text})
             continue
         if level:
@@ -71,9 +72,7 @@ def main(argv: list[str] | None = None) -> int:
             if manual_heading(paragraph):
                 findings.append({"kind": "manual_formatting", "index": index, "text": text})
             previous = level
-        elif not text:
-            continue
-        elif manual_heading(paragraph) and len(text) <= 120:
+        elif text and manual_heading(paragraph) and len(text) <= 120:
             findings.append({"kind": "heading_not_styled", "index": index, "text": text})
 
     counts = {}

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

@@ -131,8 +131,10 @@ def main(argv: list[str] | None = None) -> int:
         body.insert(position + offset, node)
 
     if not args.no_back_to_toc:
+        anchors = {entry["anchor"] for entry in headings}
         for paragraph_node in list(body.iter(kit.q("p"))):
-            if any(entry["anchor"] == name for entry in headings for name in (paragraph_node.find(kit.q("bookmarkStart")).get(kit.q("name")),) if paragraph_node.find(kit.q("bookmarkStart")) is not None):
+            start = paragraph_node.find(kit.q("bookmarkStart"))
+            if start is not None and start.get(kit.q("name")) in anchors:
                 back = paragraph("Caption")
                 back.append(link_run("Back to contents", TOC_BOOKMARK))
                 paragraph_node.addnext(back)

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

@@ -173,6 +173,101 @@ def remap_relationships(base: kit.Docx, append: kit.Docx, nodes: list) -> int:
     return copied
 
 
+NOTE_PARTS = (
+    ("word/footnotes.xml", kit.REL_FOOTNOTES, "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml", kit.q("footnote"), (kit.q("footnoteReference"),)),
+    ("word/endnotes.xml", kit.REL_ENDNOTES, "application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml", kit.q("endnote"), (kit.q("endnoteReference"),)),
+    ("word/comments.xml", kit.REL_COMMENTS, "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml", kit.q("comment"), (kit.q("commentReference"), kit.q("commentRangeStart"), kit.q("commentRangeEnd"))),
+)
+
+
+def remap_part_relationships(base: kit.Docx, append: kit.Docx, append_part: str, base_part: str, nodes: list) -> int:
+    """Remap r:embed/r:id/r:link inside nodes, copying targets into the base package."""
+    source_rels = {entry["id"]: entry for entry in append.relationships(append_part)}
+    attributes = (kit.q("embed", kit.R), kit.q("id", kit.R), kit.q("link", kit.R))
+    mapping = {}
+    copied = 0
+    for node in nodes:
+        for element in node.iter():
+            for attribute in attributes:
+                rid = element.get(attribute)
+                if not rid:
+                    continue
+                if rid not in mapping:
+                    rel = source_rels.get(rid)
+                    if rel is None:
+                        mapping[rid] = rid
+                        continue
+                    if rel["mode"] == "External":
+                        mapping[rid] = base.ensure_rel(base_part, rel["type"], rel["target"], external=True)
+                    elif append.exists(rel["resolved"]):
+                        target = copy_part(base, append, rel["resolved"])
+                        relative = posixpath.relpath(target, posixpath.dirname(base_part))
+                        mapping[rid] = base.ensure_rel(base_part, rel["type"], relative)
+                        copied += 1
+                    else:
+                        mapping[rid] = rid
+                element.set(attribute, mapping[rid])
+    return copied
+
+
+def merge_note_part(base: kit.Docx, append: kit.Docx, part: str, rel_type: str, content_type: str, note_tag: str) -> dict[str, str]:
+    """Merge a footnotes/endnotes/comments part into the base, returning old→new ids."""
+    if not append.exists(part):
+        return {}
+    source_root = append.xml(part)
+    if base.exists(part):
+        target_root = base.xml(part)
+    else:
+        target_root = etree.Element(source_root.tag, nsmap=source_root.nsmap)
+        for note in source_root.findall(note_tag):
+            raw = note.get(kit.q("id"))
+            if raw is not None and raw.lstrip("-").isdigit() and int(raw) <= 0:
+                target_root.append(etree.fromstring(etree.tostring(note)))
+        base.set_xml(part, target_root)
+        base.ensure_override(part, content_type)
+        base.ensure_rel("word/document.xml", rel_type, posixpath.relpath(part, "word"))
+
+    used = {
+        int(node.get(kit.q("id")))
+        for node in target_root.findall(note_tag)
+        if (node.get(kit.q("id")) or "").lstrip("-").isdigit()
+    }
+    next_id = max(used, default=0) + 1
+    mapping: dict[str, str] = {}
+    for note in source_root.findall(note_tag):
+        raw = note.get(kit.q("id"))
+        if raw is None or not raw.lstrip("-").isdigit() or int(raw) <= 0:
+            continue
+        clone = etree.fromstring(etree.tostring(note))
+        clone.set(kit.q("id"), str(next_id))
+        remap_part_relationships(base, append, part, part, [clone])
+        target_root.append(clone)
+        mapping[raw] = str(next_id)
+        next_id += 1
+    return mapping
+
+
+def bind_note_references(clones: list, ref_tags: tuple, mapping: dict[str, str], target_exists: bool) -> int:
+    """Point body references at the merged notes; drop references that have no note."""
+    dropped = 0
+    for clone in clones:
+        for ref_tag in ref_tags:
+            for element in list(clone.iter(ref_tag)):
+                raw = element.get(kit.q("id"))
+                if raw is None:
+                    continue
+                if raw in mapping:
+                    element.set(kit.q("id"), mapping[raw])
+                elif target_exists and raw.isdigit() and int(raw) <= 0:
+                    continue
+                else:
+                    parent = element.getparent()
+                    if parent is not None:
+                        parent.remove(element)
+                        dropped += 1
+    return dropped
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="Append one .docx body to another, copying media, numbering and styles.")
     parser.add_argument("base", help="Document to append to")
@@ -220,6 +315,13 @@ def main(argv: list[str] | None = None) -> int:
                 if num_id is not None and num_id.get(kit.q("val")) in number_map:
                     num_id.set(kit.q("val"), number_map[num_id.get(kit.q("val"))])
     media_copied = remap_relationships(base, append, clones)
+    notes_merged = 0
+    references_dropped = 0
+    for part, rel_type, content_type, note_tag, ref_tags in NOTE_PARTS:
+        exists = append.exists(part)
+        mapping = merge_note_part(base, append, part, rel_type, content_type, note_tag) if exists else {}
+        notes_merged += len(mapping)
+        references_dropped += bind_note_references(clones, ref_tags, mapping, exists)
     copy_defaults(base, append)
 
     body = base.body()
@@ -237,6 +339,8 @@ def main(argv: list[str] | None = None) -> int:
             "styles_copied": styles_copied,
             "media_copied": media_copied,
             "numbering_remapped": len(number_map),
+            "notes_merged": notes_merged,
+            "references_dropped": references_dropped,
         }
     )
     return 0

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

@@ -98,7 +98,11 @@ def fix_table(table, target: int) -> None:
     if not columns:
         columns = [1]
     total = sum(columns) or len(columns)
-    scaled = [max(1, round(target * value / total)) for value in columns]
+    scaled = [max(1, target * value // total) for value in columns]
+    remainder = target - sum(scaled)
+    order = sorted(range(len(columns)), key=lambda index: (target * columns[index]) % total, reverse=True)
+    for index in range(max(0, remainder)):
+        scaled[order[index % len(order)]] += 1
     grid = table.find(kit.q("tblGrid"))
     if grid is None:
         grid = etree.Element(kit.q("tblGrid"))
@@ -163,8 +167,14 @@ def main(argv: list[str] | None = None) -> int:
             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
+        remaining = []
+        for index, info in enumerate((table_info(table) for table in tables), start=1):
+            if info["grid_total"] and info["grid_total"] > target:
+                remaining.append({"kind": "grid_wider_than_text", "table": index, "grid_total": info["grid_total"], "text_width": target})
+            if info["layout"] != "fixed":
+                remaining.append({"kind": "not_fixed_layout", "table": index})
+        kit.emit({"ok": not remaining, "fixed": True, "output": str(Path(out)), "tables": len(tables), "text_width": target, "findings": remaining})
+        return 0 if not remaining else 1
 
     kit.emit({"ok": not findings, "text_width": target, "tables": rows, "findings": findings})
     return 1 if findings else 0

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

@@ -1,9 +1,10 @@
 #!/usr/bin/env python
-"""Add a diagonal text watermark to the page background.
+"""Add a 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.
+The watermark is a DrawingML text box in the default header: Word rotates it
+-45 degrees, while VML-only renderers that drop VML shapes still show the mark.
+It prints behind the body on every page and can be removed again by deleting
+the header paragraph.
 
 Exit codes: 0 success, 2 bad input.
 """
@@ -26,7 +27,7 @@ for _stream in (sys.stdout, sys.stderr):
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="Add a VML text watermark to the document header.")
+    parser = argparse.ArgumentParser(description="Add a DrawingML 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")

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

@@ -1,8 +1,10 @@
 #!/usr/bin/env python
-"""Find and remove VML text watermarks from headers.
+"""Find and remove 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.
+Both DrawingML watermarks (what ``watermark_add.py`` writes) and legacy VML
+``v:textpath`` shapes are detected. 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.
 """
@@ -25,7 +27,7 @@ for _stream in (sys.stdout, sys.stderr):
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="Report or remove watermarks stored as VML shapes in headers.")
+    parser = argparse.ArgumentParser(description="Report or remove watermarks stored as DrawingML or 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")

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

@@ -1,8 +1,6 @@
 # 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`.
+Accessibility comes from structure, not appearance: bold announces as bold, `Heading 1` announces as a heading and appears in the navigation pane. Alt text lives in `wp:docPr @descr`.
 
 ## Audit
 
@@ -10,36 +8,32 @@ The accessibility tree in Word comes from structure, not appearance. Bold text a
 "<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.
+Checks images without description or title, tables without a repeating header row, heading levels that jump, empty headings, link text that is only "click here", "here" or "link", and a missing core title. Exit 1 means at least one finding.
 
-## Fix the mechanical parts
+## Mechanical fixes
 
 ```bash
-"<python>" "<skill>/scripts/a11y_audit.py" "<file.docx>" \
-  --fix_image_alt from_filename --fix_table_headers first_row \
-  --out "<file-a11y.docx>"
+"<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.
+These are honest placeholders, not substitutes for real text.
 
-## Fix the parts that need judgement
+## Judgement fixes
 
-- **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.
+- **Alt text** describes what the reader loses, e.g. "Bar chart: revenue by region, EMEA 4.1M ahead of APAC 3.2M". Decorative rules and dividers get an empty description.
+- **Link text** names the destination: "Download the Q2 ledger", not "click here".
+- **Reading order:** decorative text boxes and floating images land awkwardly; convert them to inline.
+- **Colour alone** (red = bad) fails colour-blind readers; add a word.
+- **Layout tables** announce as data tables; restructure them as paragraphs.
 
-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.
+Longer documents also want a TOC (`tasks/toc_workflow.md`) and language tags.
 
 ## 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.
+Re-run the audit to zero findings and render. Heading hierarchy is visible; alt text is metadata and stays invisible; the header row must be distinct. With a screen reader available, navigate by heading.
 
 ## 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.
+- Alt text on a decorative image is worse than none: use an empty description plus `title` to mark it decorative.
+- A header row is `w:tblHeader` on the row, not a bold first row.
+- Images inside table cells still need descriptions.

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

@@ -1,49 +1,46 @@
-# Captions and cross-references
+# Captions and numbered 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.
+A caption is a paragraph with a `SEQ` field (`SEQ Table \* ARABIC`) plus a bookmark; the prose reaches that bookmark with a `REF` field. Without the bookmark a `REF` has no target.
 
 ## Add captions
 
 ```bash
-"<python>" "<skill>/scripts/captions_and_crossrefs.py" "<file.docx>" "<file-captioned.docx>" \
-  --tables --figures --bookmarks --caption_text "Source: finance ledger"
+"<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.
+- `--tables` adds `Table N` under each table; `--figures` adds `Figure N` under each picture.
+- Neither flag runs both.
+- `--bookmarks` names them `tbl1`, `tbl2`, `fig1`, … — the `tblN`/`figN` pattern `insert_ref_fields.py` expects.
+- `--materialize` writes literal numbers: for a frozen PDF export, not for a document that will change.
+- `--caption_text` appends a fixed note.
 
-The bookmarks the script creates (`tblN`, `figN`) are what `insert_ref_fields.py` expects by default.
+Captions use the `Caption` style and stay in the same visual block as the object, so a page break cannot orphan them.
 
-## Add cross-references
+## Cross-reference
 
-Write placeholders in your content, then convert them:
+Write `[[REF:tbl1]]` placeholders in the prose, then:
 
 ```bash
-"<python>" "<skill>/scripts/insert_ref_fields.py" "<file.docx>" "<file-refs.docx>"
+"<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.
+That produces a `REF tbl1 \h` field, so the number follows the table. `--pattern` accepts your own regex with the named group `bookmark`; `--prefix` prepends text such as `Table `.
 
-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.
+If a reference should read "Table 2" rather than "2", set the REF field's `\n` behaviour off and put the label in the prose: a field cannot know whether it points at a table or a figure.
 
-## Order of operations
+## Order
 
-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.
+1. Add or restructure the tables and figures.
+2. Run `captions_and_crossrefs.py`.
+3. Run `insert_ref_fields.py`.
+4. Re-render.
 
 ## 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.
+Run `fields_report.py`: one SEQ per caption, one REF per reference, and no REF with an empty result. Then render. The usual defects are a caption above its table, or a caption separated from it by a page break.
 
 ## 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.
+- Numbering changes on field update, so two captions can claim `Table 2` until Word recalculates.
+- A hand-typed caption number never renumbers.
+- 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

@@ -1,49 +1,44 @@
-# Tracked changes
+# Proposed and 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: an insertion wraps runs in `w:ins`, a deletion wraps `w:delText` in `w:del`, a move is `w:moveFrom`/`w:moveTo` paired by `w:name`, and a formatting change is `w:rPrChange`/`w:pPrChange`. `w:trackRevisions` in `word/settings.xml` makes Word record new edits.
 
-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
+## Propose
 
 ```bash
-"<python>" "<skill>/scripts/add_tracked_replacements.py" "<file.docx>" --out "<file-tracked.docx>" \
-  --author "Review" --replace "18%=21%" --replace "flat=steady"
+"<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.
+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.
+Limit: one replacement per pattern per paragraph. A match split across runs is still found because the split is computed on paragraph text; reword if a paragraph repeats the phrase.
 
-## Inspect what is proposed
+## Inspect
 
 ```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.
+The report counts insertions, deletions, move pairs and format changes.
 
 ## 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>"
+"<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
+Accept keeps inserted text and drops deleted text; reject reverses that and restores `w:delText` as ordinary text. Format-only changes are discarded either way. `--keep_tracking_on` leaves `trackRevisions` enabled.
 
-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.
+Before delivery: rendered pages contain no markup, so a file can look finished while carrying redlines. Always run `--mode report` on a file about to be sent, then 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.
+After accepting, `docx_kit.py text` shows the new wording and `word/document.xml` contains no `w:ins`/`w:del`. Render 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`.
+- `w:del` contains `w:delText`, not `w:t`; extraction that reads only `w:t` loses deletions.
+- Tables, headers and footnotes can each carry tracked changes. The script covers every text part; a hand edit can miss one.
+- Accepting a move pair as two unrelated edits duplicates content. The script treats them as a pair.
+- Comments are not tracked changes; see `comments_manage.md`.