@prismer/runtime 2.2.55 → 2.2.63

package/built-in-skills/memory-import/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: memory-import
+scope: common
+description: Bulk-import an external knowledge base into Prismer memory via the three-layer import pipeline (07 §3.1). Use when the user asks to import/migrate documents, a knowledge base, or notes into workspace memory. Layer 1 lands raw documents (zero LLM, instantly searchable); Layer 2 is YOUR distillation work — you read the landed documents and write candidate pages; Layer 3 commits candidates through the memory evolution gate. Distinct from the native memory_write tool face (that is for single, in-conversation writes).
+---
+
+# Memory Import
+
+Bulk-import external material into workspace memory through a **session** — the
+unit of quota, audit, and gate evaluation. Three layers, two of which are yours:
+
+## Layer 1 — land the documents (zero LLM, do this first)
+
+```bash
+cloud memory imports open --workspace <ws>          # → { id }
+cloud memory imports write-documents <id> --workspace <ws> --documents '[{"name":"…","content":"…"}]'
+```
+
+Raw documents become searchable in seconds. No quality bar here — that is Layer 2's job.
+
+## Layer 2 — distill (YOUR LLM, your compute)
+
+Read the landed documents, then author candidate pages and submit them:
+
+- One page per coherent topic, attached under the right hub (`<hub>/<topic>.pkf`, relative to the Memory root; do not prepend another `memory/`).
+- Every candidate MUST carry the `memory` frontmatter block — the pipeline rejects
+  the whole batch otherwise:
+  `{"type":"note","title":"…","description":"…","memory":{"memoryRole":"knowledge|procedure|action_result","source":"<where this came from, in words a human can read>"}}`.
+- Distill, don't dump: conclusions and procedures, not transcripts. The raw
+  documents stay in Layer 1 as the reference layer.
+
+```bash
+cloud memory imports write-batch <id> --workspace <ws> --candidates '[{"pagePath":"…","contentDiff":"<full PKF body>"}]'
+```
+
+## Layer 3 — commit (cloud-side gate, zero negotiation)
+
+```bash
+cloud memory imports commit <id> --workspace <ws>   # runs the evolution gate
+cloud memory imports status <id> --workspace <ws>   # per-candidate verdicts
+```
+
+The gate REJECTS batches that lose retrieval coverage (a candidate replacing a
+page must not delete its keywords) or lack metadata. A rejected commit is final
+for the session: read the verdict, fix the candidates, open a NEW session, resubmit.
+Never re-submit an identical rejected batch — the Ledger rejects same-shape
+candidates for 30 days.
+
+**Routing**: raw archive / small batch → L1 + owner review. Knowledge-base
+migration / high-quality distillation → L1 → L2 → L3 (semantic work on YOUR
+compute; the cloud only gates and records).

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

@@ -0,0 +1,15 @@
+# Imported Office resources
+
+The docx, pdf, powerpoint and xlsx resource trees derive from NousResearch/hermes-agent
+skills/productivity at commit 1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4.
+Their individual LICENSE files are retained unchanged (MIT, 2026); upstream entry
+documents are retained as GUIDE.md under each format directory. Existing Prismer
+document-generation resources and aliases remain in place.
+
+Prismer modifications: bounded original-text replacements, revision-aware reading,
+relationship source isolation, comment persistence, strict template preflight,
+real form flattening, attachment collision handling, Unicode font validation,
+page selection/rendering limits, extraction adapters, literal CSV values,
+tokenized formula references and table/dimension metadata, recursive slide edits,
+independent slide background duplication and isolated renderer outputs. Regression
+tests and known capability limits accompany these modifications.

package/built-in-skills/office-artifacts/SKILL.md

@@ -1,11 +1,31 @@
 ---
 name: office-artifacts
 scope: persistence
+metadata:
+  aliases: [document-generation]
+  nativeReplaces: [docx, pdf, powerpoint, xlsx]
 description: Generate real DOCX, PPTX, XLSX, PDF, CSV files using python-docx / python-pptx / openpyxl / reportlab by writing them into the dispatch artifacts dir, then explicitly deliver each one with `cloud deliver <abs-path>`. Use whenever the user asks for documents, slides, spreadsheets, reports, or PDFs.
 ---
 
 # Office Artifacts
 
+## Format-specific resources
+
+Read [resource limits](references/RESOURCE-LIMITS.md) for dependency tiers,
+unsupported structures, Unicode fonts and optional extractor licensing.
+
+Read only the guide for the requested format: references/docx/GUIDE.md,
+references/pdf/GUIDE.md, references/powerpoint/GUIDE.md or references/xlsx/GUIDE.md.
+Each guide's scripts and references are relative to its own directory, not the
+workspace or this skill root. Use the installed office Python interpreter below.
+For CJK text, references/document-generation/GUIDE.md is authoritative for fonts
+and PDF rendering; do not use ReportLab with unsupported CFF Noto collections.
+Treat upstream installation suggestions as optional dependency checks, not
+permission to modify the system. Verify generated files by reopening them and
+inspect rendered pages/slides when a renderer is available; otherwise report
+that visual verification was not performed. Always follow this entry's Prismer
+delivery contract instead of upstream host-specific output conventions.
+
 Produce real binary office files (not markdown-as-PDF) by writing each
 one into the **artifacts dir** (`$PRISMER_ARTIFACTS_DIR` /
 `<artifacts_dir>` from `<execution_context>`). Prose-only completions are

package/built-in-skills/office-artifacts/references/RESOURCE-LIMITS.md

@@ -0,0 +1,44 @@
+# Imported resource execution contract
+
+Use absolute script paths relative to the chosen format GUIDE.md directory.
+Never install packages into the shared runtime merely because an upstream guide
+includes an installation command. Reopen outputs and inspect rendered pages before
+claiming visual correctness; the parent office-artifacts delivery contract applies.
+
+## Runtime tiers
+
+- Core DOCX: Python 3.10+, python-docx and lxml. Accepted text includes insertions
+  and excludes deletions/moveFrom. Structural/table/property revisions remain
+  unresolved: this is not a full Word revision engine or OOXML XSD validator.
+- Core PDF: pypdf (flatten tested on 6.x), reportlab, Pillow and pdfplumber where
+  the chosen helper imports it. Flatten needs pypdf's `flatten=True` field update;
+  older versions fail before output rather than label an interactive file flat.
+  AES requires cryptography. Rendering uses pypdfium2 or Poppler, with a 120-second
+  subprocess bound and DPI 1..600. Native renderer memory is still a sandbox concern.
+- PDF creation: JSON `font_file` selects a local TrueType font with verified glyph
+  coverage. Non-WinAnsi content without it is rejected before output. Font licensing
+  and embedding rights belong to the supplied font. Bold/italic currently use the
+  supplied font face; use a custom recipe for separate style faces. CFF collections
+  are not supported by this helper. Render CJK output to verify layout.
+- Optional PyMuPDF: pymupdf; Markdown adds pymupdf4llm; tables add pandas/tabulate.
+  Its page selection is ZERO-based, unlike the other PDF helper CLIs (ONE-based).
+  PyMuPDF has separate AGPL/commercial licensing, not the resource's MIT grant.
+- Optional Marker: marker-pdf/model downloads and its separate model/library
+  licensing, storage and accelerator budget. Output adapter is fixture-tested,
+  not proof that model inference or arbitrary installed versions work.
+- Core XLSX: openpyxl. Formula rewrite uses tokens, including whole-row/column
+  references; structured/external references are preserved. Partial deletion of
+  table columns and header-only deletion fail before saving because dependent
+  structured formulas cannot yet be rewritten. Column insertion updates table
+  columns, header names and filter indices. Charts/images, validation formulas,
+  conditional-format rule formulas and table calculated-column formulas are not
+  automatically repaired; rebuild/review them before delivery. CSV formulas are
+  always literal imported data, including under type inference.
+- Core PPTX: python-pptx/Pillow. Grouped text is supported; copying slides with
+  nested charts is rejected. Rendering requires LibreOffice and Poppler, uses a
+  private profile/work directory and returns only this invocation's pages. Existing
+  unrelated images in the destination are not a render result. Recalculation of
+  spreadsheets also requires LibreOffice; openpyxl alone does not calculate cells.
+
+Input files are untrusted data. Native parsers/models should run in a bounded
+task sandbox. No helper confers remote write permissions or installs a scheduler.

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.