@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/office-artifacts/references/docx/GUIDE.md

@@ -0,0 +1,196 @@
+---
+name: docx
+description: Create, read, edit, template, and review Word .docx files.
+version: 1.1.0
+author: Nous Research
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [word, docx, documents, office, templates, revisions, comments]
+    category: productivity
+    related_skills: [pdf, xlsx, powerpoint]
+---
+
+# Docx Skill
+
+Create, read, edit, and template Microsoft Word `.docx` files with
+python-docx via small CLIs. It handles text, styles, lists, tables,
+images, headers/footers, `{{token}}` templating, tracked changes
+(list/accept/reject), comments (list/add/delete), TOC and page-number
+fields, and package health checks. It does not render documents itself
+(PDF needs LibreOffice — see Converting to PDF) or edit legacy `.doc`.
+
+## When to Use
+
+- The user asks to generate a Word document (report, letter, contract).
+- You need the text, outline, styles, or embedded images of a `.docx`.
+- You must change an existing `.docx`: replace text, edit table cells,
+  insert/delete paragraphs, apply styles, merge fragmented runs.
+- You have a `.docx` template with `{{placeholders}}` to fill from data.
+- The document has tracked changes to review, accept, or reject.
+- You need to read reviewers' comments, or add/delete comments.
+- A `.docx` won't open or behaves oddly and you need corruption triage.
+- The document needs a table of contents or "Page X of Y" footers.
+- Not for: `.doc` (legacy), `.odt`, or WYSIWYG layout work.
+
+## Prerequisites
+
+- Python 3.10+ with `python-docx` installed:
+  `pip install python-docx` (import name is `docx`; lxml comes with it).
+- Comments `add` uses the native API on python-docx >= 1.2 and an XML
+  fallback on older versions — both are automatic.
+- For image blocks: the image files must exist locally (PNG/JPEG).
+
+## How to Run
+
+All helpers live in `scripts/` next to this file. Run them with the
+`terminal` tool; each supports `--help` and prints JSON to stdout.
+
+```bash
+python scripts/docx_create.py spec.json out.docx
+python scripts/docx_read.py out.docx --text
+python scripts/docx_edit.py replace out.docx --find old --replace new
+python scripts/docx_template.py tpl.docx values.json filled.docx
+python scripts/docx_revisions.py list out.docx
+python scripts/docx_comments.py list out.docx
+python scripts/docx_validate.py out.docx
+```
+
+## Quick Reference
+
+| Task | Command |
+| --- | --- |
+| Create from JSON spec | `docx_create.py spec.json out.docx` |
+| Full text (body+tables+headers/footers) | `docx_read.py f.docx --text` |
+| Heading outline + table shapes | `docx_read.py f.docx --structure` |
+| Styles actually used | `docx_read.py f.docx --styles` |
+| Extract embedded images | `docx_read.py f.docx --images outdir/` |
+| Detect tracked changes/comments | `docx_read.py f.docx --revisions` |
+| Find/replace (formatting kept) | `docx_edit.py replace f.docx --find A --replace B -o out.docx` |
+| Set a table cell | `docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X` |
+| Insert paragraph before index N | `docx_edit.py insert f.docx --index N --text X --style Normal` |
+| Delete paragraph N | `docx_edit.py delete f.docx --index N` |
+| Apply style to paragraph N | `docx_edit.py style f.docx --index N --style "Heading 1"` |
+| Merge equal-format adjacent runs | `docx_edit.py normalize f.docx -o out.docx` |
+| Insert TOC field before para N | `docx_edit.py toc f.docx --index N -o out.docx` |
+| "Page X of Y" footer fields | `docx_edit.py page-numbers f.docx` |
+| Fill `{{tokens}}` | `docx_template.py tpl.docx values.json out.docx --strict` |
+| List revisions (id/author/date/text) | `docx_revisions.py list f.docx` |
+| Accept / reject all revisions | `docx_revisions.py accept-all f.docx -o out.docx` (or `reject-all`) |
+| Accept / reject one revision | `docx_revisions.py accept f.docx --id 3 -o out.docx` |
+| List comments (+anchored text) | `docx_comments.py list f.docx` |
+| Add comment anchored to text | `docx_comments.py add f.docx --target "phrase" --text "note" --author You` |
+| Delete comment by id | `docx_comments.py delete f.docx --id 0` |
+| Health-check the package | `docx_validate.py f.docx` (exit 1 on errors) |
+
+## Procedure
+
+1. **Create.** Write a JSON spec with `write_file`, then run
+   `scripts/docx_create.py`. The spec supports: `page` (size + margins in
+   mm), `header`/`footer` strings, `footer_page_numbers` (adds a
+   "Page X of Y" field footer), `styles` (custom paragraph styles with
+   font, size, bold/italic, hex `color`), and `blocks` — `heading`
+   (level 1-9), `paragraph` (either `text` or a `runs` list where each run
+   may set `bold`/`italic`/`underline`), `bullet_list`, `numbered_list`,
+   `table` (`header` row rendered bold, `rows`, optional built-in table
+   `style` such as `Table Grid`), `image` (`path`, optional `width_mm`),
+   `toc` (Table of Contents field), and `page_break`. The full spec
+   format is documented at the top of `scripts/docx_create.py`.
+2. **Read.** Use `scripts/docx_read.py` with exactly one mode flag.
+   `--text` returns body paragraphs, all table cell text, and
+   header/footer text as JSON. `--structure` returns the heading outline
+   plus paragraph/table/section counts. `--images DIR` copies every file
+   under `word/media/` out of the package.
+3. **Edit.** Use `scripts/docx_edit.py`. `replace` walks body, tables
+   (nested included), headers and footers, and preserves run formatting;
+   add `--body-only` to skip headers/footers. Pass `-o out.docx` to keep
+   the original; omit it to edit in place. Paragraph indices for
+   `insert`/`delete`/`style`/`toc` refer to `--structure`/`--text` body
+   order. Run `normalize` first on documents that came out of heavy Word
+   editing — it merges adjacent runs with identical formatting so later
+   find-replace matches reliably.
+4. **Review revisions.** `docx_revisions.py list` reports every `w:ins`
+   and `w:del` (id, author, date, affected text) anywhere in body,
+   tables, headers, or footers. `accept-all` / `reject-all` resolve them
+   in bulk; `accept`/`reject --id N` handles a single revision. Accept
+   keeps insertions and drops deleted text; reject does the reverse.
+5. **Comments.** `docx_comments.py list` returns each comment's id,
+   author, date, body text, and the document text it is anchored to.
+   `add --target "some phrase"` anchors a new comment to the first
+   occurrence of that phrase (runs are split as needed; formatting is
+   preserved). `delete --id N` removes the comment and its markers
+   without touching document text.
+6. **Template.** Put `{{name}}`-style tokens in the document. Run
+   `scripts/docx_template.py` with a JSON object of values. Use
+   `--strict` to fail when tokens remain unfilled; the JSON output lists
+   `filled` counts and `unfilled_tokens` either way.
+7. **Verify** (always): re-read the output with `--text` or
+   `--structure`, and run `docx_validate.py` on anything you produced
+   via revision/comment surgery.
+
+## Converting to PDF
+
+No script needed. When LibreOffice is installed, convert headlessly:
+
+```bash
+soffice --headless --convert-to pdf --outdir outdir/ file.docx
+```
+
+Check availability first (`command -v soffice || command -v
+libreoffice`). If neither exists, tell the user PDF conversion is
+unavailable in this environment rather than improvising — python-docx
+cannot render PDFs, and layout fidelity requires a real renderer.
+
+## Pitfalls
+
+- **Tokens split across runs.** Word often fragments text into several
+  runs. The replace helpers collapse matched runs (replacement inherits
+  the first run's formatting); running `docx_edit.py normalize` first
+  reduces fragmentation for all later edits.
+- **Revision coverage.** `docx_revisions.py` resolves run-level
+  insertions and deletions (the overwhelming majority). Paragraph-mark
+  and table-row revisions, format-change records, and moves are detected
+  by `--revisions` but not auto-resolved — see
+  `references/revisions-and-comments.md` and hand those to Word.
+- **Comment threading.** Replies and "resolved" status live in
+  `commentsExtended.xml`, which this skill ignores; comments it adds are
+  plain top-level comments.
+- **Field results are computed by Word.** `toc`, `page-numbers`, and the
+  `toc`/`footer_page_numbers` spec options write *field codes*.
+  Word/LibreOffice populates the actual entries and numbers when the
+  file is opened (Word may prompt to update fields); python-docx never
+  computes them, so placeholder text shows until then.
+- **Validation is a health check, not schema validation.**
+  `docx_validate.py` verifies the zip, required parts, relationship
+  targets, image magic bytes, and referenced styles. It is NOT XSD
+  validation — a file can pass and still contain XML Word dislikes.
+- **Style names must exist.** Applying a style that isn't defined in the
+  document raises `KeyError`. Built-ins like `Heading 1`, `List Bullet`,
+  `List Number`, `Table Grid` exist in the default template; custom
+  styles must be declared in the create spec first.
+- **Numbered lists restart.** `List Number` relies on Word's default
+  numbering; separate lists in one document may continue numbering
+  instead of restarting. Warn users needing precise multi-list numbering.
+- **Cell writes replace formatting.** `set-cell` uses `cell.text = ...`,
+  which resets runs in that cell to plain formatting.
+- **Encoding.** All JSON specs/values files are read as UTF-8 explicitly;
+  never rely on locale defaults when writing your own glue code.
+- **Don't unzip-and-sed the XML.** Edit through the scripts (or
+  python-docx); raw text substitution in `document.xml` corrupts files
+  easily. Use `patch`/`write_file` only for the JSON inputs, never on the
+  `.docx` itself.
+
+## Verification
+
+- After create/edit/template, run `docx_read.py out.docx --text` and
+  check the expected strings appear (and old strings are gone).
+- After accept/reject, `docx_revisions.py list` should return `[]` (or
+  only the ids you intentionally left); after comment surgery,
+  `docx_comments.py list` should reflect the change and `--text` output
+  must be unchanged.
+- `docx_validate.py out.docx` exits 0 with `"ok": true` on a healthy
+  package — run it after any revision/comment/field manipulation.
+- For templates run with `--strict`, or check `unfilled_tokens == []`.
+- Structure checks: `--structure` should show the expected heading
+  outline and table shapes; `--styles` confirms custom styles applied.

package/built-in-skills/office-artifacts/references/docx/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/built-in-skills/office-artifacts/references/docx/NOTICE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/built-in-skills/office-artifacts/references/docx/references/revisions-and-comments.md

@@ -0,0 +1,88 @@
+# Revisions and Comments — XML details
+
+Deep reference for `docx_revisions.py` and `docx_comments.py`. Read this
+when you need to reason about the raw WordprocessingML, extend the
+scripts, or debug an unusual document. Everyday use only needs SKILL.md.
+
+## Tracked changes (w:ins / w:del)
+
+Word records run-level tracked changes as wrapper elements inside a
+paragraph (`w:p`), in the `w` namespace
+`http://schemas.openxmlformats.org/wordprocessingml/2006/main`:
+
+```xml
+<w:p>
+  <w:r><w:t>Base </w:t></w:r>
+  <w:ins w:id="1" w:author="Editor" w:date="2026-01-02T03:04:05Z">
+    <w:r><w:t>inserted text</w:t></w:r>
+  </w:ins>
+  <w:del w:id="2" w:author="Editor" w:date="2026-01-02T03:04:05Z">
+    <w:r><w:delText>deleted text</w:delText></w:r>
+  </w:del>
+</w:p>
+```
+
+Key facts the script relies on:
+
+- Deleted text lives in `w:delText`, not `w:t` — that is why plain text
+  extraction naturally shows the "accepted" view (insertions visible,
+  deletions hidden).
+- Resolution semantics:
+  - accept `w:ins` → unwrap (move child runs up, drop the wrapper)
+  - reject `w:ins` → remove the wrapper and its contents
+  - accept `w:del` → remove the wrapper and its contents
+  - reject `w:del` → rename each `w:delText` to `w:t`, then unwrap
+- Revisions can appear anywhere block content is allowed: body, table
+  cells (nested tables too), headers, footers, text boxes. The script
+  iterates the body root plus every header/footer part root with
+  `root.iter(W+"ins", W+"del")`, which finds them at any depth.
+- `w:id` values are unique per revision *element*, but one logical edit
+  session may produce several elements. `accept`/`reject --id` acts on
+  exactly the element(s) carrying that id.
+
+Not handled by the script (detected by `docx_read.py --revisions` but
+left alone): paragraph-mark revisions (`w:rPr/w:ins` on `w:pPr`), table
+row insertions/deletions (`w:trPr/w:ins`), format-change records
+(`w:rPrChange`, `w:pPrChange`), and moves (`w:moveFrom`/`w:moveTo`).
+Moves are rare from typical editors; if present, treat the file with
+Word itself rather than guessing.
+
+## Comments
+
+Three cooperating pieces:
+
+1. **`word/comments.xml`** — one `w:comment` element per comment,
+   carrying `w:id`, `w:author`, `w:initials`, `w:date`, and body
+   paragraphs. Related from document.xml via the relationship type
+   `.../comments` and content type
+   `application/vnd...wordprocessingml.comments+xml` (also needs a
+   `[Content_Types].xml` override — python-docx's part machinery adds it
+   when the part is registered).
+2. **Range markers in the story** — `w:commentRangeStart w:id="N"`
+   before the anchored runs, `w:commentRangeEnd w:id="N"` after them.
+3. **The reference run** — a `w:r` containing `w:commentReference
+   w:id="N"`, placed right after the range end; it ties the balloon to
+   the location.
+
+`docx_comments.py` behavior:
+
+- **list / delete** always work at the XML level, so they handle files
+  from any producer. `anchored_text` is reconstructed by walking each
+  part root in document order and collecting `w:t` text between the
+  start and end markers for each id.
+- **add** first isolates the target text into whole runs. If the match
+  starts or ends mid-run, the run is split at the boundary (the split
+  copies `w:rPr`, so formatting is preserved). Then:
+  - python-docx >= 1.2: the native `document.add_comment(runs, ...)`
+    API is used (it creates the comments part, markers, and reference
+    run itself).
+  - older versions or `--xml`: the script builds `word/comments.xml`,
+    registers the part + relationship through the opc layer, and
+    inserts the markers/reference manually.
+- Deleting a comment removes the `w:comment` element and all three
+  marker kinds for that id; the anchored document text is untouched.
+
+Modern Word also writes `commentsExtended.xml` (threading/resolved
+state). The scripts neither read nor produce it: replies and "resolved"
+flags are invisible here, and comments added by this skill are plain
+top-level comments.

package/built-in-skills/office-artifacts/references/docx/scripts/docx_comments.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""List, add, and delete comments in a .docx.
+
+Subcommands:
+  list    JSON per comment: id, author, initials, date, text, anchored_text
+  add     add a comment anchored to the first occurrence of --target
+  delete  remove a comment (and its range markers) by --id
+
+Examples:
+  docx_comments.py list report.docx
+  docx_comments.py add report.docx --target "Q3 revenue" \
+      --text "Needs a source" --author "Reviewer" -o out.docx
+  docx_comments.py delete report.docx --id 0 -o out.docx
+
+Uses the native python-docx comments API (>= 1.2) when available; falls
+back to building word/comments.xml and the range markers directly for
+older versions (or when --xml is passed). Listing and deletion always
+work at the XML level so they handle documents from any producer.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import sys
+from copy import deepcopy
+
+from docx import Document
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from lxml import etree
+
+from docx_common import iter_part_roots
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+COMMENTS_CT = ("application/vnd.openxmlformats-officedocument"
+               ".wordprocessingml.comments+xml")
+
+
+def q(tag: str) -> str:
+    return f"{{{W}}}{tag}"
+
+
+# ---------------------------------------------------------------- reading
+
+def _comments_root(doc):
+    """Return the XML root of the comments part, or None."""
+    for rel in doc.part.rels.values():
+        if rel.reltype == RT.COMMENTS:
+            part = rel.target_part
+            el = getattr(part, "_element", None)
+            if el is not None:
+                return el
+            from docx.opc.part import XmlPart
+            part._element = etree.fromstring(part.blob)
+            part.__class__ = XmlPart
+            return part._element
+    return None
+
+
+def _anchored_texts(doc) -> dict:
+    """Map comment id -> document text between its range markers."""
+    anchored: dict[str, list[str]] = {}
+    for root in iter_part_roots(doc):
+        active: set[str] = set()
+        for el in root.iter():
+            if el.tag == q("commentRangeStart"):
+                cid = el.get(q("id"))
+                active.add(cid)
+                anchored.setdefault(cid, [])
+            elif el.tag == q("commentRangeEnd"):
+                active.discard(el.get(q("id")))
+            elif el.tag == q("t") and active:
+                for cid in active:
+                    anchored[cid].append(el.text or "")
+    return {cid: "".join(parts) for cid, parts in anchored.items()}
+
+
+def list_comments(doc) -> list:
+    root = _comments_root(doc)
+    if root is None:
+        return []
+    anchored = _anchored_texts(doc)
+    out = []
+    for c in root.iter(q("comment")):
+        cid = c.get(q("id"))
+        text = "\n".join(
+            "".join(t.text or "" for t in p.iter(q("t")))
+            for p in c.iter(q("p")))
+        out.append({"id": cid, "author": c.get(q("author")),
+                    "initials": c.get(q("initials")),
+                    "date": c.get(q("date")), "text": text,
+                    "anchored_text": anchored.get(cid, "")})
+    return out
+
+
+# ---------------------------------------------------------------- anchoring
+
+def _split_run(para, run_el, offset: int):
+    """Split a run element at text offset; return the new right-hand run."""
+    text = "".join(t.text or "" for t in run_el.iter(q("t")))
+    right = deepcopy(run_el)
+    run_el.addnext(right)
+    for el, s in ((run_el, text[:offset]), (right, text[offset:])):
+        for t in list(el.iter(q("t"))):
+            el.remove(t)
+        t = etree.SubElement(el, q("t"))
+        t.text = s
+        t.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+    return right
+
+
+def find_anchor_runs(doc, target: str):
+    """Isolate `target`'s first occurrence into whole runs; return them."""
+    from docx_common import iter_all_paragraphs
+    for para in iter_all_paragraphs(doc):
+        full = para.text
+        start = full.find(target)
+        if start < 0:
+            continue
+        end = start + len(target)
+        pos = 0
+        covered = []
+        for run_el in para._p.iter(q("r")):
+            rtext = "".join(t.text or "" for t in run_el.iter(q("t")))
+            r_start, r_end = pos, pos + len(rtext)
+            pos = r_end
+            if r_end <= start or r_start >= end:
+                continue
+            if r_start < start:  # split off the left part
+                run_el = _split_run(para, run_el, start - r_start)
+                r_start = start
+            if r_end > end:      # split off the right part
+                _split_run(para, run_el, end - r_start)
+            covered.append(run_el)
+        return para, covered
+    return None, []
+
+
+# ---------------------------------------------------------------- adding
+
+def _next_id(doc) -> int:
+    root = _comments_root(doc)
+    if root is None:
+        return 0
+    ids = [int(c.get(q("id"), "0")) for c in root.iter(q("comment"))
+           if c.get(q("id"), "").isdigit()]
+    return max(ids) + 1 if ids else 0
+
+
+def add_comment_native(doc, runs, text, author, initials):
+    from docx.text.run import Run
+    run_objs = [Run(r, None) for r in runs]
+    comment = doc.add_comment(run_objs, text=text, author=author,
+                              initials=initials or "")
+    return str(comment.comment_id)
+
+
+def add_comment_xml(doc, runs, text, author, initials) -> str:
+    cid = str(_next_id(doc))
+    root = _comments_root(doc)
+    if root is None:
+        root = etree.fromstring(
+            f'<w:comments xmlns:w="{W}"/>'.encode("utf-8"))
+        from docx.opc.packuri import PackURI
+        from docx.opc.part import Part
+        blob = etree.tostring(root, xml_declaration=True,
+                              encoding="UTF-8", standalone=True)
+        part = Part(PackURI("/word/comments.xml"), COMMENTS_CT, blob,
+                    doc.part.package)
+        doc.part.relate_to(part, RT.COMMENTS)
+        # keep a live element on the part so edits reach save()
+        part._element = root
+        part.blob_ = None
+
+        def _blob(self=part):
+            return etree.tostring(self._element, xml_declaration=True,
+                                  encoding="UTF-8", standalone=True)
+        part.__class__ = type("CommentsXmlPart", (Part,),
+                              {"blob": property(lambda self: _blob(self))})
+    now = _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    comment = etree.SubElement(root, q("comment"))
+    comment.set(q("id"), cid)
+    comment.set(q("author"), author)
+    if initials:
+        comment.set(q("initials"), initials)
+    comment.set(q("date"), now)
+    p = etree.SubElement(comment, q("p"))
+    r = etree.SubElement(p, q("r"))
+    t = etree.SubElement(r, q("t"))
+    t.text = text
+    # range markers around the anchor runs + reference run after them
+    first, last = runs[0], runs[-1]
+    start = first.makeelement(q("commentRangeStart"), {q("id"): cid})
+    first.addprevious(start)
+    end = last.makeelement(q("commentRangeEnd"), {q("id"): cid})
+    last.addnext(end)
+    ref_run = last.makeelement(q("r"), {})
+    ref = etree.SubElement(ref_run, q("commentReference"))
+    ref.set(q("id"), cid)
+    end.addnext(ref_run)
+    return cid
+
+
+# ---------------------------------------------------------------- deleting
+
+def delete_comment(doc, cid: str) -> bool:
+    root = _comments_root(doc)
+    found = False
+    if root is not None:
+        for c in list(root.iter(q("comment"))):
+            if c.get(q("id")) == cid:
+                c.getparent().remove(c)
+                found = True
+    for part_root in iter_part_roots(doc):
+        for tag in ("commentRangeStart", "commentRangeEnd",
+                    "commentReference"):
+            for el in list(part_root.iter(q(tag))):
+                if el.get(q("id")) == cid:
+                    parent = el.getparent()
+                    # remove the wrapping run for reference marks
+                    if tag == "commentReference" and parent.tag == q("r"):
+                        parent.getparent().remove(parent)
+                    else:
+                        parent.remove(el)
+                    found = True
+    return found
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="List, add, or delete comments in a .docx.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("list", help="list comments as JSON")
+    p.add_argument("path", help="input .docx")
+
+    p = sub.add_parser("add", help="add a comment anchored to text")
+    p.add_argument("path", help="input .docx")
+    p.add_argument("-o", "--output", help="output path (default: in place)")
+    p.add_argument("--target", required=True,
+                   help="anchor: first occurrence of this text")
+    p.add_argument("--text", required=True, help="comment body")
+    p.add_argument("--author", default="Hermes")
+    p.add_argument("--initials", default="")
+    p.add_argument("--xml", action="store_true",
+                   help="force the XML fallback (skip native API)")
+
+    p = sub.add_parser("delete", help="delete a comment by id")
+    p.add_argument("path", help="input .docx")
+    p.add_argument("-o", "--output", help="output path (default: in place)")
+    p.add_argument("--id", required=True, help="comment id")
+
+    args = ap.parse_args()
+    doc = Document(args.path)
+
+    if args.cmd == "list":
+        print(json.dumps({"ok": True, "comments": list_comments(doc)},
+                         ensure_ascii=False))
+        return 0
+
+    if args.cmd == "add":
+        para, runs = find_anchor_runs(doc, args.target)
+        if not runs:
+            print(json.dumps({"ok": False,
+                              "error": f"target not found: {args.target}"}))
+            return 1
+        native = hasattr(doc, "add_comment") and not args.xml
+        if native:
+            cid = add_comment_native(doc, runs, args.text, args.author,
+                                     args.initials)
+        else:
+            cid = add_comment_xml(doc, runs, args.text, args.author,
+                                  args.initials)
+        result = {"ok": True, "comment_id": cid,
+                  "native_api": native, "anchored_to": args.target}
+    else:  # delete
+        if not delete_comment(doc, args.id):
+            print(json.dumps({"ok": False,
+                              "error": f"no comment with id {args.id}"}))
+            return 1
+        result = {"ok": True, "deleted_id": args.id}
+
+    out = args.output or args.path
+    doc.save(out)
+    result["output"] = out
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())