dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/excel-live-control/workflows/create_workflows.md

@@ -0,0 +1,78 @@
+# Creating content in a live workbook
+
+The user is watching, so the order you do things in is visible. Plan on paper first, then
+make a small number of writes.
+
+## 1. Decide what is actually being created
+
+Before you write a cell, you should be able to answer:
+
+- **Who reads it, and what decision does it support?** A one-page summary for a committee
+  and a working model for an analyst are different sheets.
+- **What are the outputs?** Name them. Each output is a number with a label, a period and
+  a unit.
+- **What are the inputs?** Name them, with their sources. Inputs nobody will update are
+  decoration.
+- **What is calculated in between?** The steps between input and output are what a reviewer
+  audits; if you cannot name them, the model is not designed yet.
+- **What would make it wrong?** A check or a reconciliation, even one line: totals tie,
+  parts sum to the whole, cash ends at the right balance.
+
+If the request leaves two of these open, ask one short question rather than guessing —
+a live edit is expensive to unpick.
+
+## 2. Where it goes
+
+- Roles, not a fixed tab count: inputs, assumptions, calculations, outputs. A small sheet
+  can carry several roles; a large model separates them.
+- Outputs at the left of the tab strip, workings in the middle, inputs at the right; a
+  check/audit tab last if the model warrants one. Do not add a Checks tab to a simple
+  sheet — a labelled verification row is enough.
+- Keep inputs next to the calculations they feed when the model is small; move them to a
+  dedicated input sheet only when more than one sheet consumes them.
+- Calculate once, link everywhere else. Two cells computing the same number is a future
+  disagreement.
+- Insights (a short comment or a highlighted conclusion) go next to the result they
+  explain, not in a separate "insights" area.
+
+**Adding a tab is not an operation of this skill.** The tool writes into sheets that
+already exist. If the job needs a new sheet, ask the user to insert one (Right-click a tab
+→ Insert), or use the file route in `../../office-spreadsheets/SKILL.md` and tell them to
+reopen. Do not repurpose an existing sheet as scratch space.
+
+## 3. Write it
+
+```
+info                                             # confirm workbook, sheet, used range
+write_range --sheet "Inputs" --range B4:C9 --data-file inputs.json
+set_formula --sheet "Inputs" --range D4:D9 --formula "=B4*C4"   # fills down with relative rows
+style_range --sheet "Inputs" --range B3:D3 --style '{"bold":true,"border":"outline"}'
+recalc
+read_range --sheet "Inputs" --range B3:D9 --formulas
+```
+
+- One `write_range` per block with its real shape. The array is rows × columns; do not pad
+  with empty strings to make it rectangular — use `null` for a genuinely empty cell.
+- Write the labels and the units with the numbers. A block of bare numbers is not done.
+- Default formats in the write step, not afterwards: `number_format` in `style_range`
+  applied to the whole block is one call and keeps every cell consistent.
+- Formulas as text starting with `=`, absolute where they must stay put (`$C$4`), relative
+  where the fill should walk (`D5`). Test one cell before filling a column.
+- If the sheet already has content, check the used range first and write beside it, not
+  over it.
+
+## 4. Check it, then say what you did
+
+- `read_range --formulas` over everything you wrote; `errors` must be empty.
+- `recalc`, then read the outputs again — a formula that never calculated proves nothing.
+- `info` if you added tables or charts, to confirm they landed on the sheet you meant.
+- Report the ranges and the state of the document (unsaved, or saved where). See the
+  Delivery section of `../SKILL.md`.
+
+## 5. Sizing and layout
+
+- Set column widths after the content exists, from the widest formatted value, then
+  re-read with `--display` to catch `###`.
+- Wrap long text labels instead of widening a column to half the screen.
+- Helper calculations go in their own block or sheet, labelled, not buried between two
+  output rows.

package/assets/skills/excel-live-control/workflows/edit_workflows.md

@@ -0,0 +1,72 @@
+# Editing a workbook the user already built
+
+The existing workbook is the reference. Its structure, formula style, formats, labels and
+navigation are what the user expects to keep seeing; your job is to make one change that
+looks like it was always there.
+
+## Read the ground first
+
+Nothing below works without this step, and it is cheap:
+
+1. `info` — workbook name and path, `saved` flag (unsaved work in progress!), sheets,
+   used ranges, tables, charts, pivots, protection.
+2. `read_range --formulas` over the block you are about to touch **and its neighbours**.
+   You need to know the pattern a formula follows before you extend it.
+3. `read_range --display` when the change is formatting — it tells you the current number
+   format's effect, not just the stored value.
+4. Read the labels around the block: period, unit, actual/forecast. A number is only
+   meaningful with its label, and your new row must match the surrounding convention.
+
+If the target block holds values you cannot explain from the request, stop and ask. On a
+live document, "I thought it was empty" is how an analyst's afternoon disappears.
+
+## Rules of the edit
+
+- **Change the cells the request names, and the formulas those cells feed.** A changed
+  input propagates on its own; do not hand-edit downstream totals.
+- **Do not add, remove, rename, reorder or split sheets/tabs** unless the request says so
+  or the change genuinely cannot be expressed otherwise (a new output with no home).
+- **Preserve everything you did not create**: other sheets, formulas, named ranges,
+  comments, protection, hidden or grouped rows, freeze panes (user-set), native tables and
+  their structured references, pivot sources, shared formulas, filters, external links,
+  `INDIRECT` routing, calculation settings.
+- **Never flatten formulas to values.** Not to "simplify", not to "fix" a display problem.
+- **Extend, do not replace.** When a row or column is added to a block that has a table,
+  conditional format or chart on it, extend the object to cover the new cells instead of
+  building a parallel object beside it. `ListObject.Resize` and the chart's
+  `SetSourceData` are the tools.
+- **Small visual fixes stay local.** Widen the one column that clips. Do not autofit the
+  sheet, do not restyle a header because it is not your default style.
+- **Match the existing formula conventions** — anchoring style, `SUMIFS` vs `SUMPRODUCT`,
+  rounding, the workbook's error handling. A locally "better" formula that reads
+  differently is a maintenance cost the user did not ask for.
+- **Pre-existing errors are not yours to fix.** Report them with the cell and the formula
+  and ask. Silently repairing a `#REF!` can change a number the user relies on.
+
+## Doing it
+
+```
+read_range --sheet "Build" --range D5:F12 --formulas     # understand the pattern
+write_range --sheet "Build" --range D13:F13 --data '[...]'   # the new row only
+set_formula --sheet "Build" --range G5:G13 --formula "=SUM(D5:F5)"
+style_range  --sheet "Build" --range D13:F13 --style '{"number_format":"#,##0"}'
+recalc
+read_range --sheet "Build" --range D5:G13 --formulas     # prove it
+```
+
+- Keep writes to the named rectangle; `--clear` only on a range whose previous contents
+  you have read and can restore.
+- Style by copying the neighbouring block's codes: read a cell you want to match, mirror
+  its `number_format`, and apply it to the new cells. Do not invent a new format for one
+  row.
+- If a formula in the new cell must differ from the pattern (a different anchor, a
+  one-off), say why in the reply — a reviewer will find it.
+
+## When you are done
+
+- `read_range --formulas` over every cell you changed and its immediate neighbours.
+- `recalc` after formulas, then re-read the outputs that depend on them.
+- `info` if tables, charts or pivots were extended, to confirm the objects still exist and
+  cover the new cells.
+- Report: sheet, exact ranges, cell counts, and what the document's saved state is. If the
+  edit touched a formula graph, say which outputs were affected.

package/assets/skills/office-documents/SKILL.md

@@ -1,101 +1,114 @@
 ---
-description: Create, inspect, edit, and render Word .docx documents with the bundled Office helper CLI.
+description: Build, inspect, revise, and visually verify Word .docx files using the Office helper CLI and the bundled XML scripts.
 ---
 
 # Documents (.docx)
 
-Create, read, edit, and render local Word documents. This skill produces Office Open XML files; it does not edit Google Docs and does not use the artifact-tool runtime.
+A `.docx` is a zip of XML parts: `word/document.xml` holds the body, and headers, footers, footnotes, comments, styles and numbering live beside it. Two routes reach every part of it:
+
+- **Fast path** — the helper CLI inspects, renders and creates: `docx create`, `docx read`, `docx render`. It performs no in-place mutation.
+- **Structural path** — `scripts/*.py` in this skill do all editing: replace text, append blocks, set properties, and everything structural — comments, tracked changes, fields, protection, watermarks.
+
+Pick the cheapest route that produces the structure the user asked for, then verify it visually. Never invent content, and never deliver a file you have not looked at.
 
 ## Before any file work
 
 1. Call the `office_status` tool.
-2. Use the `python` and `cli` values from the `## Office runtime` JSON block at the end of this file. These are verified absolute paths; do not assume `python` or `soffice` is on `PATH`.
-3. If the runtime block says no compatible Python was found, stop and tell the user to run the package install/rebuild step. Do not fabricate a document or claim success.
+2. Read the `## Office runtime` block at the end of this file for the verified `python`, `cli`, `skill` and `shared` paths.
+3. If that block says no runtime is available, stop and give the user the `node "..."` remedy command it names, then call `office_status` again. Do not fake a document or claim success.
 
-Quote every path. Windows paths and paths containing spaces, Chinese characters, or `&` are supported.
+Quote every path. Spaces, non-ASCII names and `&` are normal on Windows.
 
-## Create
+## Delivery
 
-Write a JSON spec in the user's workspace, then run:
+Always hand the finished file to the user with the `present` tool, then summarise in one sentence what changed. A bare path is not delivery: the chat transcript renders `.docx`/`.pptx`/`.xlsx`/`.pdf` links as "二进制文件，无法显示改动" and the user cannot open them.
 
-```bash
-"<python>" "<cli>" docx create --spec "<spec.json>" --out "<output.docx>"
-```
+- Creating a file: write it into the user's workspace, verify it, then `present`.
+- Editing an existing file: never overwrite the original. Write `<original>-edited.<ext>` (or a name the user asked for), verify it, `present` it, and state both paths.
 
-Minimal spec:
-
-```json
-{
-  "title": "Quarterly Report",
-  "subtitle": "Internal review",
-  "author": "Prepared by DSH Office Suite",
-  "header": "Confidential",
-  "footer": "Page 1",
-  "page_size": "A4",
-  "orientation": "portrait",
-  "blocks": [
-    { "type": "heading", "level": 1, "text": "Executive summary" },
-    { "type": "paragraph", "text": "Revenue grew 18.4% year over year." },
-    { "type": "bullets", "items": ["Renewal rate 92%", "42 new customers"] },
-    { "type": "table", "headers": ["Metric", "Q3"], "rows": [["Revenue", "12,480,000"], ["Gross margin", "71.2%"]] },
-    { "type": "equation", "latex": "\\frac{a^2+b^2}{c^2}" },
-    { "type": "page_break" }
-  ]
-}
-```
+## Annotations
 
-Supported block types: `heading` (`level` 0–9), `paragraph` (`bold`, `italic`, `size`, `color`, `align`, `style`), `bullets`, `numbered`, `table` (`headers`, `rows`, optional `style`, default `Table Grid`), `image` (`path`, optional `width` in inches), `equation` (`latex`), `quote`, `page_break`, `spacer`. Page fields: `page_size` (`Letter` or `A4`), `orientation`, margins in inches (`top_margin`, `bottom_margin`, `left_margin`, `right_margin`).
+The user may reply with an `office-annotations` block: `[{ page, text, requirement, region: { left, top, width, height } }]`. `region` is normalised 0–1 against the rendered preview page the user drew on; `requirement` is free-form natural language. Treat it as a change request, not as editor state: locate what the region covers, apply the smallest edit that satisfies `requirement`, re-render, and confirm the region now looks right.
 
-LaTeX equations are converted to native OMML. Simple fractions, superscripts, subscripts, roots, and Greek symbols work; unsupported LaTeX silently falls back to italic text and increments `equation_fallbacks`. Check that counter when the equation matters.
+When the payload cannot be mapped to a concrete object (the region is empty or the file has no geometry), do not guess silently — say what you could not locate.
 
-## Read
+For `.docx`, `page` is the page of the *rendered PDF preview*, not a Word page. Use `text` (and the paragraph text near it) to locate the target; the region is a hint for near-misses only. A region that lands on a table row, a caption or a header is ambiguous — state which object you picked before editing.
 
-```bash
-"<python>" "<cli>" docx read --input "<file.docx>"
-```
-
-Returns title, author, paragraphs with styles, headings, tables, image count, equation count, and page dimensions. Use it to verify a file you did not create.
-
-## Edit
+## Verify
 
-Copy-then-edit: the CLI never modifies the input in place.
-
-```bash
-"<python>" "<cli>" docx edit --input "<file.docx>" --spec "<edit.json>" --out "<file-edited.docx>"
-```
-
-```json
-{
-  "replace": [{ "find": "37 customers", "replace": "42 customers" }],
-  "blocks": [{ "type": "heading", "level": 1, "text": "Appendix" }],
-  "core": { "title": "Quarterly Report (final)", "author": "Finance" }
-}
-```
-
-`replace` works on runs and falls back to rebuilding a paragraph when the text spans runs. It cannot reliably edit headers/footers, comments, tracked changes, content controls, or fields; those are unsupported (see below). Adding blocks appends them at the end of the body.
-
-## Render and verify
+Rendering is the only proof that a document looks right.
 
 ```bash
 "<python>" "<cli>" docx render --input "<file.docx>" --out-dir "<render-dir>"
 ```
 
-The renderer prefers Microsoft Word COM on Windows and LibreOffice otherwise. It writes a PDF and one PNG per page. Open the PNGs with your image-viewing tool and inspect: title/heading hierarchy, table geometry, page breaks, missing glyphs, overflowing text, header/footer, and equation rendering.
-
-If no renderer is available, report "not visually verified" and offer the file. Do not claim layout quality you did not see.
-
-## Quality rules
-
-- Write real content from the user's request; never invent metrics, citations, or names.
-- Use one consistent heading hierarchy. Do not skip levels.
-- Keep tables narrow enough for the page; abbreviate long headers.
-- Verify a non-Latin script renders in the chosen fonts before delivering.
-- Prefer native Word structures (headings, tables, lists) over hand-positioned text.
-
-## Not supported
-
-- Google Docs / Google Drive import or native online editing.
-- Comments, tracked changes, redlining, accept/reject workflows.
-- Existing headers/footers, footnotes, TOC fields, cross-references, content controls, protection, watermarks, redaction.
-- In-place editing, macros, encrypted documents, `.doc` input.
-- Word-perfect pagination or template cloning. `render` is a fidelity check, not a guarantee that Word and LibreOffice paginate identically.
+The command writes a PDF plus one PNG per page and prints the paths. Open each PNG with `read_image` and check: heading hierarchy, table width and cell wrapping, page breaks, header/footer, clipped or overflowing text, missing glyphs (dashes, CJK, symbols), equation rendering, and caption placement.
+
+- Iterate until the pages look correct, then deliver. "It parses" is not verification.
+- If the runtime reports no renderer (none of Microsoft Word, WPS Writer, or LibreOffice), ask the user to install one, or fall back to `docx read` plus the audit scripts. Say plainly that layout was not visually verified — do not describe a page you did not see.
+- After a script edits XML, re-render. A package can stay valid while the page it produces is broken.
+
+## Choosing a route
+
+| Job | Fast path | Structural path |
+|---|---|---|
+| New document from scratch | `docx create --spec` | `python-docx` snippet in `tasks/create_edit.md` |
+| Replace or append text and blocks | — | `scripts/replace_text.py`, `scripts/append_blocks.py` |
+| Document properties | — | `scripts/core_properties.py` |
+| Read structure | `docx read` | `scripts/docx_kit.py text`, `style_lint`, audits |
+| Comments, tracked changes | — | `scripts/comments_*.py`, `scripts/*tracked*.py` |
+| Fields, TOC, cross-references | — | `scripts/insert_toc.py`, `insert_ref_fields.py`, `fields_*.py` |
+| Footnotes, endnotes | — | `scripts/insert_note.py`, `footnotes_report.py` |
+| Tables, layout geometry | `docx create` table block | `scripts/table_geometry.py`, `docx_table_to_csv.py` |
+| Styles, templates | — | `scripts/style_*.py`, `apply_template_styles.py` |
+| Protection, watermarks, privacy | — | `scripts/set_protection.py`, `watermark_*.py`, `privacy_scrub.py`, `redact_docx.py` |
+
+Where no verb exists, the fallback is the listed script or a short `python-docx`/`lxml` snippet. Both are runnable with the runtime `python`; neither needs a new dependency.
+
+## Task index
+
+| Task | Read | Main tool |
+|---|---|---|
+| Create or edit a document | `tasks/create_edit.md` | CLI create, `replace_text.py`, `append_blocks.py`, `core_properties.py` |
+| Read and review a file | `tasks/read_review.md` | CLI read, `docx_kit.py text` |
+| Comments | `tasks/comments_manage.md` | `comments_add/extract/apply_patch/strip.py` |
+| Tracked changes | `tasks/clean_tracked_changes.md` | `accept_tracked_changes.py`, `add_tracked_replacements.py` |
+| Fields and updates | `tasks/fields_update.md` | `fields_report.py`, `fields_materialize.py` |
+| Table of contents | `tasks/toc_workflow.md` | `insert_toc.py`, `fields_*.py` |
+| Captions and cross-references | `tasks/captions_crossrefs.md` | `captions_and_crossrefs.py`, `insert_ref_fields.py` |
+| Navigation links | `tasks/navigation_internal_links.md` | `internal_nav.py` |
+| Footnotes and endnotes | `tasks/footnotes_endnotes.md` | `insert_note.py`, `footnotes_report.py` |
+| Headings and numbering | `tasks/headings_numbering.md` | `heading_audit.py` |
+| Tables | `tasks/tables_spreadsheets.md` | `table_geometry.py`, `docx_table_to_csv.py`, `xlsx_to_docx_table.py` |
+| Images and figures | `tasks/images_figures.md` | `images_audit.py` |
+| Sections and page setup | `tasks/sections_layout.md` | `section_audit.py` |
+| Styles | `tasks/style_lint_normalize.md` | `style_lint.py`, `style_normalize.py` |
+| Templates | `tasks/templates_style_packs.md` | `apply_template_styles.py`, `references/template-elicitation.md` |
+| Accessibility | `tasks/accessibility_a11y.md` | `a11y_audit.py` |
+| Content controls | `tasks/forms_content_controls.md` | `content_controls.py` |
+| Editing protection | `tasks/protection_restrict_editing.md` | `set_protection.py` |
+| Watermarks | `tasks/watermarks_background.md` | `watermark_add.py`, `watermark_audit_remove.py` |
+| Privacy and metadata | `tasks/privacy_scrub_metadata.md` | `privacy_scrub.py` |
+| Redaction | `tasks/redaction_anonymization.md` | `redact_docx.py` |
+| Merging documents | `tasks/multi_doc_merge.md` | `merge_docx_append.py` |
+| Comparing versions | `tasks/compare_diff.md` | `render_and_diff.py` |
+| Equations | `tasks/equations.md` | CLI `equation` block |
+| Visual verification | `tasks/verify_render.md` | `render_docx.py` (skill root) |
+| Fixtures and edge cases | `tasks/fixtures_edge_cases.md` | `make_fixtures.py` |
+
+## Document defaults
+
+- Letter 8.5×11 portrait (A4 when the user or template says so), 1in margins, body 11–12pt, single column.
+- Black headings and body text; colour only for deliberate emphasis, links and chart series.
+- Tables: light grey `#D9D9D9` borders, a bold header row, `w:tblHeader` so the header repeats across pages, no vertical merges in wide tables.
+- No decorative callout boxes, drop shadows or coloured sidebars. Structure comes from headings, lists and tables.
+- Captions sit under figures and above tables, in the `Caption` style, and stay with their object.
+- Prefer native structures — heading styles, real lists, real tables, OMML equations — over hand-positioned runs, because the next edit depends on that structure.
+
+## Writing quality
+
+Write the content the user asked for, in plain sentences, without filler. `references/writing-quality.md` holds the checklist; `references/docx-structure.md` explains which package part each feature lives in before you touch XML.
+
+## Shared workflow
+
+Cross-format habits, the review loop and how to read annotation payloads live in `"<shared>/common-workflow.md"` and `"<shared>/annotation-recipes.md"`; read them when the job spans more than one Office format.

package/assets/skills/office-documents/examples/end_to_end_smoke_test.md

@@ -0,0 +1,86 @@
+# End-to-end smoke test
+
+A short job that touches creation, inspection, structural changes and verification. Run it once after a runtime change, or as a template for "is this environment healthy".
+
+```bash
+PY="<python>"; CLI="<cli>"; S="<skill>/scripts"; R="<skill>"; W="/tmp/docx-smoke"
+mkdir -p "$W"
+```
+
+## 1. Create a document
+
+```bash
+cat > "$W/spec.json" <<'JSON'
+{
+  "title": "Smoke Test",
+  "author": "Runtime Check",
+  "page_size": "Letter",
+  "header": "Smoke test",
+  "blocks": [
+    { "type": "paragraph", "text": "This file exercises the DOCX path end to end." },
+    { "type": "paragraph", "text": "[[TOC]]" },
+    { "type": "heading", "level": 1, "text": "Findings" },
+    { "type": "paragraph", "text": "Revenue grew 18% year over year." },
+    { "type": "bullets", "items": ["Hardware flat", "Services up"] },
+    { "type": "table", "headers": ["Region", "Q1", "Q2"], "rows": [["North", "10", "12"], ["South", "8", "9"]], "style": "Table Grid" },
+    { "type": "equation", "latex": "E = mc^2" }
+  ]
+}
+JSON
+"$PY" "$CLI" docx create --spec "$W/spec.json" --out "$W/base.docx"
+```
+
+Expect `ok: true` and non-zero `headings`, `tables`, `equations`.
+
+## 2. Inspect
+
+```bash
+"$PY" "$CLI" docx read --input "$W/base.docx"
+"$PY" "$S/docx_kit.py" parts "$W/base.docx"
+"$PY" "$S/section_audit.py" "$W/base.docx"
+"$PY" "$S/style_lint.py" "$W/base.docx"
+```
+
+Expect the sections, the parts list to include `word/document.xml`, Letter 8.5×11 portrait, and an empty style-lint `counts`.
+
+## 3. Change it structurally
+
+```bash
+"$PY" "$S/replace_text.py" --input "$W/base.docx" --out "$W/replaced.docx" \
+  --find "Revenue grew 18%" --replace "Revenue climbed 21%" --require-all
+"$PY" "$S/captions_and_crossrefs.py" "$W/replaced.docx" "$W/captioned.docx" --tables --figures --bookmarks
+"$PY" "$S/insert_toc.py" "$W/captioned.docx" --placeholder "[[TOC]]" --out "$W/with-toc.docx"
+```
+
+`replace_text.py` prints `misses: []`; captions report one table caption; the TOC step reports whether the placeholder was found.
+
+## 4. Audit
+
+```bash
+"$PY" "$S/heading_audit.py" "$W/with-toc.docx"
+"$PY" "$S/a11y_audit.py" "$W/with-toc.docx" --out_json "$W/a11y.json"
+"$PY" "$S/fields_report.py" "$W/with-toc.docx"
+"$PY" "$S/table_geometry.py" "$W/with-toc.docx"
+```
+
+Audits may exit 1 with findings — that is a report, not a failure of the environment. Every finding should be explainable.
+
+## 5. Verify visually
+
+```bash
+"$PY" "$R/render_docx.py" "$W/with-toc.docx" --output_dir "$W/render" --dpi 150
+```
+
+Then open each PNG with `read_image`. Without a renderer the command exits 3 with `no_renderer`; that is the expected result on a machine with neither LibreOffice nor Word, and the rest of the test still stands.
+
+## 6. Deliver
+
+Copy the final file into the user's workspace, `present` it, and state what changed in one sentence. Never present a temp path.
+
+## Teardown
+
+```bash
+rm -rf "$W"
+```
+
+Nothing under the workspace should be left behind from a smoke test.

package/assets/skills/office-documents/ooxml/comments.md

@@ -0,0 +1,40 @@
+# Comments in the package
+
+A comment is three pieces that must agree: `word/comments.xml` holds the content, `word/document.xml` holds a range marking which text is discussed, and the relationship plus content-type override make the part exist at all.
+
+## The markup
+
+```xml
+<w:commentRangeStart w:id="1"/>
+<w:r><w:t>the sentence under discussion</w:t></w:r>
+<w:commentRangeEnd w:id="1"/>
+<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr>
+  <w:commentReference w:id="1"/></w:r>
+```
+
+```xml
+<w:comment w:id="1" w:author="Reviewer" w:date="2026-10-21T00:00:00Z" w:initials="R">
+  <w:p><w:r><w:t>Please double-check this number.</w:t></w:r></w:p>
+</w:comment>
+```
+
+Rules that matter in practice:
+
+- `w:id` must be unique across comments **and** match in all three places. A range start without an end leaves Word showing a comment with no anchor; an end without a start can make the file refuse to open.
+- The comment reference run belongs at the end of the range, not somewhere else in the paragraph.
+- `word/comments.xml` needs an override in `[Content_Types].xml` and a relationship from `word/document.xml`; without both, the part is ignored or the file is corrupt.
+- The file's root has `mc:Ignorable` listing `w14`/`w15` etc.; a `w15:done` attribute (the "resolved" flag) is only legal when those namespaces are declared.
+
+## Resolved versus deleted
+
+`w15:done="1"` on the `w:comment` keeps the comment in the file and shows it as resolved. Removing the comment is a different operation: delete the `w:comment`, both range markers and the reference run. Resolving hides it from the default pane; it does not remove the text from the file.
+
+## Where comments hide
+
+- Replies are comments too, linked by `w15:paraIdParent`; a strip that removes the parent leaves an orphan.
+- Anchors can sit in headers, footnotes and text boxes as well as the body.
+- A comment deleted in Word leaves no trace; a comment whose range was deleted may remain in `comments.xml` with nothing anchoring it. That is why extraction reports anchors: a comment with empty anchored text is evidence of drift.
+
+## Working from the scripts
+
+`comments_extract.py` reads the pairing and prints anchored text per comment; `comments_add.py` writes all three pieces; `comments_apply_patch.py` edits content and the resolved flag; `comments_strip.py` removes every trace and the part itself. Use `docx_kit.py xml '<file.docx>' word/comments.xml` when you need to see the raw part.

package/assets/skills/office-documents/ooxml/hyperlinks_and_fields.md

@@ -0,0 +1,66 @@
+# Hyperlinks and fields
+
+A hyperlink and a field are both "a run that looks like text but is a pointer", and both break in the same way: the visible result is cached, so editing the text does not update anything.
+
+## Hyperlinks
+
+```xml
+<w:hyperlink r:id="rId7">
+  <w:r><w:rPr><w:rStyle w:val="Hyperlink"/></w:rPr><w:t>the report</w:t></w:r>
+</w:hyperlink>
+```
+
+- The target is a relationship in `word/_rels/document.xml.rels` with `TargetMode="External"` for a URL, or a bare relative path for a file inside the package.
+- An internal link uses `w:anchor="bookmarkName"` and no relationship at all.
+- `w:hyperlink` is a wrapper around runs; a link that spans paragraphs is not legal — put one link per paragraph.
+
+A link whose relationship is missing renders as blue underlined text that goes nowhere. That is also what a copy-paste between documents produces.
+
+## Simple fields
+
+```xml
+<w:fldSimple w:instr=" REF tbl1 \h ">
+  <w:r><w:t>Table 1</w:t></w:r>
+</w:fldSimple>
+```
+
+The `w:t` inside is a cache, not the truth. Change the text and the next field update overwrites it.
+
+## Complex fields
+
+```xml
+<w:r><w:fldChar w:fldCharType="begin"/></w:r>
+<w:r><w:instrText xml:space="preserve"> TOC \o "1-3" \h \z \u </w:instrText></w:r>
+<w:r><w:fldChar w:fldCharType="separate"/></w:r>
+<w:r><w:t>Cached entries go here</w:t></w:r>
+<w:r><w:fldChar w:fldCharType="end"/></w:r>
+```
+
+The begin/instrText/separate/result/end sequence must stay in that order inside one paragraph. Word shows the result between `separate` and `end`, or recomputes on open when `w:updateFields` is set in `settings.xml`:
+
+```xml
+<w:updateFields w:val="true"/>
+```
+
+Setting it makes Word prompt or update on open. A viewer that ignores it (a PDF export, some libraries) keeps showing the cache — which is why a document delivered as PDF can show "1" for every page number.
+
+## Which field for which job
+
+| Need | Instruction |
+|---|---|
+| Page number | `PAGE` / `NUMPAGES` |
+| Table or figure number | `SEQ Table \* ARABIC` |
+| Reference to a number | `REF tbl1 \h` |
+| Table of contents | `TOC \o "1-3" \h \z \u` |
+| Document title from properties | `TITLE` / `AUTHOR` |
+
+## Editing fields safely
+
+- To freeze a result, replace the whole field span with a plain run (`fields_materialize.py`, `flatten_ref_fields.py`).
+- To renumber, update the cached result and leave the instruction alone; do not delete the begin/end markers.
+- `w:instrText` is where the instruction lives — a search-and-replace over `w:t` will not find `TOC`.
+- Bookmarks referenced by `REF` must exist (`w:bookmarkStart`/`w:bookmarkEnd` with matching `w:id`); a missing bookmark shows "Error! Reference source not found."
+
+## See also
+
+`tasks/fields_update.md`, `tasks/toc_workflow.md`, `tasks/captions_crossrefs.md`, and `ooxml/rels_and_content_types.md` for the relationship side.

package/assets/skills/office-documents/ooxml/rels_and_content_types.md

@@ -0,0 +1,62 @@
+# Relationships and content types
+
+A `.docx` is a zip of parts, and every relationship between parts is declared twice: once as a relationship entry, once as a content type. Miss either and the file either loses the feature or refuses to open.
+
+## The two registries
+
+```
+[Content_Types].xml          # what kind of file each part is
+_rels/.rels                  # package -> document, core props
+word/_rels/document.xml.rels # document -> styles, numbering, media, header, footer, comments, hyperlinks
+```
+
+`[Content_Types].xml` has `<Default Extension="xml" ContentType="..."/>` for extension defaults and `<Override PartName="/word/comments.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"/>` for parts that do not follow an extension rule.
+
+A relationship:
+
+```xml
+<Relationship Id="rId5"
+  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments"
+  Target="comments.xml"/>
+```
+
+`Id` is scoped to the part that owns the `.rels` file, so `rId5` in the document and `rId5` in a header are unrelated. `Target` is relative to the owner directory unless it is absolute (`/word/media/image1.png`) or external (`TargetMode="External"`, used for hyperlinks).
+
+## What breaks
+
+| Symptom | Cause |
+|---|---|
+| Word: "unreadable content" | A part exists but has no content-type override |
+| Feature silently ignored | Part and override exist, but no relationship points at it |
+| Duplicate header text | Two header relationships, only one referenced by `sectPr` |
+| Broken link | Relationship removed but `r:id` left in the body |
+| Lost image | Media copied without a new relationship id |
+
+Ids must be unique within a `.rels` part. When adding one, read the existing ids and take `max+1`; reusing an id silently rewires an unrelated reference.
+
+## The parts that exist only when used
+
+`word/comments.xml`, `word/footnotes.xml`, `word/endnotes.xml`, `word/headerN.xml`, `word/footerN.xml`, `word/numbering.xml`, `docProps/custom.xml` — none are required, and each needs three pieces when added: the part, the override, the relationship. Removing one means removing all three (or Word reports corruption).
+
+Headers and footers are referenced from the section properties, not from the document root:
+
+```xml
+<w:sectPr>
+  <w:headerReference w:type="default" r:id="rId8"/>
+  <w:footerReference w:type="default" r:id="rId9"/>
+</w:sectPr>
+```
+
+## Inspecting
+
+```bash
+"<python>" "<skill>/scripts/docx_kit.py" parts '<file.docx>'
+"<python>" "<skill>/scripts/docx_kit.py" xml   '<file.docx>' word/_rels/document.xml.rels
+"<python>" "<skill>/scripts/docx_kit.py" xml   '<file.docx>' '[Content_Types].xml'
+```
+
+`parts` lists what is actually in the package — the fastest way to see whether a feature exists at all. Read the `.rels` part before editing relationships by hand.
+
+## Rebuild rather than regenerate
+
+When a package is broken, unzipping it, fixing the two registries and rezipping with `[Content_Types].xml` first (stored, not deflated) usually recovers it. The kit writes that order on save for this reason.