dsh-office-kit 0.4.2 → 0.4.4

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

@@ -1,64 +1,54 @@
-# Tables and spreadsheets
+# Tables and layout geometry
 
-**Goal.** A table that fits the page, repeats its header row across pages, and survives an edit without cells drifting out of alignment.
-
-A table's geometry is three things that must agree: the grid (`w:tblGrid`, one `w:gridCol` per column), the table width (`w:tblW`), and each cell width (`w:tcW`). When they disagree Word shows a table wider than the text block or columns that jump on the first edit.
+Table geometry is three things that must agree: the grid (`w:tblGrid`, one `w:gridCol` per column), the table width (`w:tblW`) and each cell width (`w:tcW`). When they disagree, Word shows a table wider than the text block, or columns that jump on the first edit.
 
 ## Create
 
-```bash
-"<python>" "<cli>" docx create --spec "<spec.json>" --out "<out.docx>"
-```
+Use `docx create --spec` with a table block:
 
 ```json
-{
-  "type": "table",
-  "headers": ["Region", "Revenue", "Growth"],
-  "rows": [["EMEA", "4.1M", "12%"], ["APAC", "3.2M", "9%"]],
-  "style": "Table Grid"
-}
+{ "type": "table", "headers": ["Region", "Q1"], "rows": [["North", "10"]], "style": "Table Grid" }
 ```
 
-Header cells are bold. For a document with the header repeating on every page, follow up with the a11y fix, which writes `w:tblHeader` on row 1:
+Header cells are bold. To repeat the header row on every page:
 
 ```bash
-"<python>" "<skill>/scripts/a11y_audit.py" "<out.docx>" --fix_table_headers first_row --out "<out-fixed.docx>"
+"<python>" "<skill>/scripts/a11y_audit.py" "<out.docx>" --fix_table_headers first_row --out "<out-fixed.docx"
 ```
 
+That writes `w:tblHeader` on row 1.
+
 ## Inspect and fix geometry
 
 ```bash
 "<python>" "<skill>/scripts/table_geometry.py" "<file.docx>"
-"<python>" "<skill>/scripts/table_geometry.py" "<file.docx>" --fix --out "<file-fixed.docx>"
+"<python>" "<skill>/scripts/table_geometry.py" "<file.docx>" --fix --out "<file-fixed.docx"
 ```
 
-The audit reports `tblW`, layout mode, every grid column in twips and the sum, plus the narrowest and widest cell. `--fix` writes a fixed-layout table at the text width (page width minus margins), rescales the grid proportionally and rewrites each `tcW` including `gridSpan`.
-
-Text width on Letter with 1in margins is 9360 twips — that is the number a full-width table should total.
+The audit reports `tblW`, the layout mode, every grid column in twips with their sum, and the narrowest and widest cell. `--fix` writes a fixed-layout table at the text width (page width minus margins), rescales the grid proportionally and rewrites each `tcW`, including `gridSpan`. On Letter with 1in margins the text width is 9360 twips.
 
-## Convert
+## Move data between formats
 
 ```bash
-"<python>" "<skill>/scripts/docx_table_to_csv.py" "<file.docx>" --table_index 0 --out "<table.csv>"
+"<python>" "<skill>/scripts/docx_table_to_csv.py" "<file.docx>" --table_index 0 --out "<table.csv"
 "<python>" "<skill>/scripts/xlsx_to_docx_table.py" "<book.xlsx>" --sheet Revenue --out "<table.docx>" --title "Revenue by region"
 ```
 
-The first flattens a Word table (expanding horizontal spans, repeating vertically merged values) for data work. The second imports a worksheet as a Word table with a bold header row and `w:tblHeader`, which is the route for "put this spreadsheet in the report" — not a screenshot and not an embedded object.
+`docx_table_to_csv.py` flattens the table, expands horizontal spans and repeats vertically merged values. `xlsx_to_docx_table.py` writes a bold header row plus `w:tblHeader`; it is the route for "put this spreadsheet in the report", not a screenshot or an embedded object.
 
 ## Design
 
-- Bold header row, light grey `#D9D9D9` borders, no shading inside the body.
-- Numeric columns right-aligned; text left-aligned. Thousands separators in the cells themselves.
-- Two or three columns of prose at most; a wide table wants landscape, and that means a section break (`tasks/sections_layout.md`), not a smaller font.
-- Caption above the table (`tasks/captions_crossrefs.md`), and keep it with the table.
-- Avoid vertical merges: they look fine in the file and confuse every downstream reader.
+- Bold header row, light grey `#D9D9D9` borders, no shading in the body.
+- Numeric right-aligned, text left-aligned, thousands separators inside the cells.
+- Two or three prose columns at most. A wide table wants landscape through a section break (`tasks/sections_layout.md`), not a smaller font.
+- Caption above the table (`tasks/captions_crossrefs.md`). Avoid vertical merges.
 
 ## Verify
 
-Render and look at the page the table lands on: nothing spills past the right margin, header row intact, no split row across pages, and the last column not truncated. A table that fits in the XML but overflows the page is a real defect, and only the render shows it.
+Render the page: nothing past the right margin, header row intact, no row split across pages, last column not truncated. A table that fits in XML but overflows the page is a real defect that only the render shows.
 
 ## Pitfalls
 
-- A table inside a table cell inherits the cell width; check the outer table first.
-- `autofit` is a request, not a guarantee — fixed layout plus explicit widths is the only thing that renders the same everywhere.
-- Cell margins default to 108 twips left/right; that is padding, not missing width.
+- A table inside a cell inherits the cell width, so check the outer table first.
+- `autofit` is a request, not a guarantee.
+- Cell margins default to 108 twips of padding.

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

@@ -1,53 +1,49 @@
 # Templates and style packs
 
-**Goal.** Make a new or existing document look like the house template, without copying the template's content into it.
-
-A `.dotx` is a `.docx` whose package is a template: `styles.xml` defines the look, `numbering.xml` defines lists, and the body is empty. Copying the body would import placeholder text; what you actually need is the styles part, the numbering definitions they reference, and the theme.
+A `.dotx` is a `.docx` whose package is a template: `styles.xml` defines the look, `numbering.xml` defines lists, the body is empty. What you need is the styles part, the numbering definitions they reference, and the theme. Copying the body imports placeholder text.
 
 ## Ask before guessing
 
-Do not invent a house style. Get from the user: heading fonts and sizes, body font and size, accent colour, margins, table style, and whether a logo or cover page is required. `references/template-elicitation.md` has the question set that produces a spec.
+Never invent a house style. Get heading fonts and sizes, body font and size, accent colour, margins, table style, and any logo or cover requirement. `references/template-elicitation.md` holds the question set.
 
-## Apply a template
+## Apply
 
 ```bash
-"<python>" "<skill>/scripts/apply_template_styles.py" --template "<house.dotx>" --target "<draft.docx>" --out "<draft-styled.docx>"
+"<python>" "<skill>/scripts/apply_template_styles.py" --template "<house.dotx>" --target "<draft.docx>" --out "<draft-styled.docx"
 ```
 
-The script merges the template's style definitions by `styleId` (replacing same-id definitions, appending missing ones, taking the template's `docDefaults`), and copies `numbering.xml` with its relationship and content-type override. The target's body is untouched, so the content survives and the look changes.
+Merges style definitions by `styleId` (replacing same-id, appending missing, taking the template's `docDefaults`) and copies `numbering.xml` with its relationship and content-type override. The target's body is untouched.
 
-Then normalize so direct formatting does not override the template:
+Then normalise so direct formatting does not override the imported styles:
 
 ```bash
-"<python>" "<skill>/scripts/style_normalize.py" "<draft-styled.docx>" --out "<draft-final.docx>" --clear_paragraph_format
+"<python>" "<skill>/scripts/style_normalize.py" "<draft-styled.docx>" --out "<draft-final.docx" --clear_paragraph_format
 ```
 
 ## Restyle without a template
 
-When the user describes the style instead of supplying a file, set it on the styles rather than on runs:
+Set values on styles, not on runs:
 
-```bash
-"<python>" - <<'PY'
+```python
 from docx import Document
 from docx.shared import Pt, RGBColor
+
 d = Document(r"<draft.docx>")
-normal = d.styles["Normal"]
-normal.font.name = "Calibri"
-normal.font.size = Pt(11)
+d.styles["Normal"].font.name = "Calibri"
+d.styles["Normal"].font.size = Pt(11)
 for level, size in ((1, 18), (2, 14), (3, 12)):
     style = d.styles[f"Heading {level}"]
     style.font.size = Pt(size)
     style.font.color.rgb = RGBColor(0, 0, 0)
-d.save(r"<draft-styled.docx>")
-PY
+d.save(r"<draft-restyled.docx>")
 ```
 
 ## Verify
 
-Render and compare against the template's own preview page by page: heading sizes, body leading, margins, table borders. A style page that looks right in a style list but wrong on the page usually means a direct-formatting run left over — run the lint.
+Render and compare page by page with the template's own preview: heading sizes, body leading, margins, table borders. A style that looks right in the pane but wrong on the page usually has a leftover direct-formatting run — run the lint (`tasks/style_lint_normalize.md`).
 
 ## Pitfalls
 
-- A template applied over content that references missing styles produces the fallback look, not an error; run `style_lint.py` to find undefined references.
-- Themes (`word/theme/theme1.xml`) carry fonts and accent colours; a style that names a theme font changes when the theme does.
-- Keeping the template's `numbering.xml` without its `abstractNum` ids produces lists that all share one counter.
+- A template applied over content that references missing styles produces the fallback look, not an error; run `style_lint.py`.
+- Themes (`word/theme/theme1.xml`) carry fonts and accent colours, so theme-font styles change with the theme.
+- Keeping the template's `numbering.xml` without its abstractNum ids makes lists share one counter.

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

@@ -1,26 +1,22 @@
 # Table of contents
 
-**Goal.** Put a navigable contents list at the front of the document, built from heading styles rather than typed by hand.
+A TOC is a `TOC` field: Word fills it on recalculation and the file stores the last result. A hand-typed list looks identical, then goes wrong on the first edit.
 
-The TOC is a `TOC` field. Word fills it in when it recalculates; the file stores the last result. A hand-typed list looks identical in a screenshot and then goes wrong on the first edit.
-
-## Insert
+Insert:
 
 ```bash
 "<python>" "<skill>/scripts/insert_toc.py" "<file.docx>" --out "<file-toc.docx>" --levels 1-3
 ```
 
-The script looks for a placeholder paragraph containing `[[TOC]]` (override with `--placeholder`). If there is none it inserts the field at the start of the body. It writes `TOC \o "1-3" \h \z \u`, sets `w:updateFields`, and adds a short cached hint so the page is not blank before recalculation.
+The script fills a placeholder paragraph containing `[[TOC]]` (override with `--placeholder`); with no placeholder it inserts the field at the start of the body. It writes `TOC \o "1-3" \h \z \u`, sets `w:updateFields`, and leaves a short cached hint so the page is not blank before recalculation.
 
-Check that every heading you want in the list uses a heading style: `heading_audit.py` finds headings formatted by hand, which the TOC will silently skip.
+Every heading you want listed must use a heading style. `heading_audit.py` finds hand-formatted headings that the TOC silently skips.
 
 ## Rebuild after edits
 
-If headings changed, the cached list is stale. Either ask the user to update the field in Word (right-click → Update Field), or regenerate: strip the old field with `fields_materialize.py`? — no, that freezes it. Instead delete the field paragraphs and run `insert_toc.py` again. Freezing a TOC is almost never what a reader wants.
-
-## Static contents list
+The cached list goes stale after a structural edit. Ask the user to update the field in Word (right-click → Update Field), or delete the field paragraphs and re-run `insert_toc.py`. Do not freeze a TOC with `fields_materialize.py`.
 
-Sometimes the requirement really is a fixed list — a PDF export that will not be recalculated, or a template with a hand-built contents page. `internal_nav.py` builds one: a heading plus hyperlink entries to every heading, with optional back-links.
+For a fixed PDF export or a hand-built template contents page, generate a static list with `internal_nav.py` instead:
 
 ```bash
 "<python>" "<skill>/scripts/internal_nav.py" "<file.docx>" --out "<file-nav.docx>" --levels 1 2
@@ -30,10 +26,10 @@ See `tasks/navigation_internal_links.md`.
 
 ## Verify
 
-Render the first pages and read them. A TOC that shows one line of grey hint text means the field never recalculated in that renderer; a TOC that shows the old headings means the document was rendered before the field updated. Say which one happened instead of claiming the TOC is correct.
+Render the first pages. A line of grey hint text means the renderer never recalculated the field; old headings mean it rendered before the update. Say which happened instead of claiming the contents are correct.
 
 ## Pitfalls
 
-- TOC entries come from outline levels, not from text that merely looks like a heading.
-- A TOC inside a header or a text box does not work; it belongs in the body.
-- Level 4+ headings are excluded unless you widen `--levels`.
+- TOC entries come from outline levels, not from text that looks like a heading.
+- A TOC in a header or text box does not work — body only.
+- Level 4 and deeper are excluded unless you widen `--levels`.

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

@@ -1,50 +1,38 @@
 # Visual verification
 
-**Goal.** See the pages before the user does. A document that parses and a document that looks right are different claims.
-
-## Render
+See the pages before the user does. A document that parses and a document that looks right are different claims.
 
 ```bash
 "<python>" "<cli>" docx render --input "<file.docx>" --out-dir "<render-dir>"
 ```
 
-Writes one PNG per page and prints their paths plus the renderer it used (`libreoffice-kit`); add `--pdf` to also keep a PDF. Use the same command through `render_docx.py` when you want the JSON report and page list:
+Writes one PNG per page and prints the paths plus the renderer it used (`libreoffice-kit`); add `--pdf` to keep a PDF as well. For a JSON report and page list use `render_docx.py`:
 
 ```bash
 "<python>" "<skill>/render_docx.py" "<file.docx>" --output_dir "<render-dir>" --dpi 150
 ```
 
-## Inspect
-
 Open every PNG with `read_image` and check, in this order:
 
 1. **Hierarchy** — does the page show the structure the user asked for, at a glance?
 2. **Fit** — nothing past the right margin, no clipped table column, no text over a watermark.
 3. **Breaks** — no heading alone at the bottom, no orphaned caption, no half-empty page before a section break.
-4. **Text** — the words that were meant to change did change, and nothing else moved.
+4. **Text** — the intended words changed, and nothing else moved.
 5. **Glyphs** — dashes, quotes, CJK, currency symbols and maths render, not as boxes.
-6. **Header and footer** — present, correct, not repeated on a first page that should not have it.
+6. **Header and footer** — present, correct, and not repeated on a first page that should not have one.
 
-## When no renderer exists
+Re-render after any script edit. Package-valid is not page-valid: a caption placed before the paragraph it describes, a table grown past the margin, a style merge that changed heading sizes — all are invisible in the XML and obvious in the image. To compare two revisions, `render_and_diff.py` writes a heatmapped difference page; read the diff images yourself, because a ratio is not a conclusion.
 
-The runtime reports `renderers.can_render.docx: false` because the DSH LibreOffice kit was not found. `render` then exits non-zero with a JSON error naming the missing renderer, and `render_docx.py` exits 3 with `reason: no_renderer`.
+## When no renderer exists
 
-In that state:
+`office_status` reports `renderers.available: false` (with a `remedy`) because the DSH LibreOffice kit was not found. `render` then exits non-zero with a JSON error naming the missing renderer, and `render_docx.py` exits 3 with `reason: no_renderer`.
 
 - Verify structure with `docx read`, `docx_kit.py parts|text|xml` and the audit scripts.
-- Tell the user plainly that layout was not visually verified, and that the fix is a harness install that ships the kit (the plugin records its path in `config.json` when it loads), not installing Word/LibreOffice.
-- Do not claim a file "looks good" from XML evidence alone.
-
-## After any script edit
-
-Re-render. Package-valid is not page-valid: a caption inserted before the paragraph it describes, a table grown past the margin, a style merge that changed heading sizes — all are invisible to the XML and obvious in the image.
-
-## Comparing revisions
-
-`render_and_diff.py` renders two files and writes a heatmapped difference page. Read the diff images yourself; a ratio is not a conclusion.
+- Say plainly that layout was not visually verified, and that the fix is a harness install shipping the kit (the plugin records its path in `config.json` when it loads), not installing Word or LibreOffice.
+- Never claim a file "looks good" from XML evidence alone.
 
 ## Pitfalls
 
 - Different renderers paginate differently. Compare like with like, and do not promise Word-perfect pagination from a LibreOffice render.
-- A render fails silently into a blank page when a font is missing; a blank page is a finding, not a rendering bug. `missing_fonts` / `glyph_fallback` in the render JSON tells you substitution happened.
-- Render into a fresh directory; stale PNGs from an earlier run are the classic false pass.
+- A missing font turns into a blank page: that is a finding, not a rendering bug. `missing_fonts` / `glyph_fallback` in the render JSON shows substitution happened.
+- Render into a fresh directory: stale PNGs from an earlier run are the classic false pass.

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

@@ -1,8 +1,6 @@
-# Watermarks and background text
+# Watermarks and background marks
 
-**Goal.** A diagonal DRAFT / CONFIDENTIAL mark behind the page content, and the ability to find and remove one that a template left behind.
-
-A Word watermark is not a document feature with its own element: it is a VML shape (`v:shape` with `v:textpath`) in a header part, positioned behind the text. That is why it disappears if the header is replaced, and why it can appear on some pages and not others when sections have their own headers.
+A text watermark is a shape inside a header part, behind the body text: Word writes legacy VML (`v:shape` with `v:textpath`), while `watermark_add.py` writes DrawingML (`wps:wsp`) because VML is routinely dropped by non-Word renderers. That is why a watermark disappears when the header is replaced and can differ per section.
 
 ## Add
 
@@ -10,26 +8,24 @@ A Word watermark is not a document feature with its own element: it is a VML sha
 "<python>" "<skill>/scripts/watermark_add.py" "<file.docx>" --out "<file-draft.docx>" --text "DRAFT"
 ```
 
-Writes the shape into the default header, light grey, rotated -45°, behind the body. The script refuses to add a second watermark when it finds one — remove the old one first, or you get two overlapping marks.
-
-For a per-page mark across a document with several sections, each section's header needs the shape; that is a loop over sections, not one insertion.
+Writes the shape into the default header: light grey, centred on the page, tagged with `descr="DSH Office watermark"`. Word rotates it -45°; renderers that ignore the rotation still show a horizontal mark, so it is always visible. The script refuses to add a second watermark when it finds one, so remove the old one first. For a mark on every page across sections, each section's header needs the shape — loop over the sections.
 
 ## Find and remove
 
 ```bash
 "<python>" "<skill>/scripts/watermark_audit_remove.py" "<file.docx>" --mode report
-"<python>" "<skill>/scripts/watermark_audit_remove.py" "<file.docx>" --mode remove --out "<file-clean.docx>"
+"<python>" "<skill>/scripts/watermark_audit_remove.py" "<file.docx>" --mode remove --out "<file-clean.docx"
 ```
 
-The report lists the text of every VML text path and the part it lives in, and exits 1 when any watermark exists. `--contains` narrows to a substring, which is the case "the template says Company Confidential and it should not". Remove deletes the enclosing paragraph from the header.
+The report lists every DrawingML watermark and every legacy VML text path, with the part it lives in, and exits 1 when any watermark exists. `--contains` narrows it to a substring, for the "template says Company Confidential" case. Remove deletes the enclosing paragraph from the header.
 
 ## Verify
 
-Render and read the pages: the mark sits behind the text (not over it), stays inside the page, and appears on every page the user expects. A watermark that vanishes on page two means that section has a different header.
+Render and read the pages: the mark sits behind the text, inside the page, on every expected page. A light grey drawing that covers a line of body text is still a defect; a mark missing on page two means that section has a different header.
 
 ## Pitfalls
 
-- A watermark in a "different first page" header only shows on page one.
-- Removing the header paragraph can leave an empty header that adds vertical space; check the top margin on the rendered page.
-- An image watermark is an `v:imagedata` shape, not a text path — the report will not name it, so inspect the header XML when the visual mark is a logo.
-- Watermarks are not security. See `tasks/protection_restrict_editing.md` for what actually restricts editing.
+- A watermark in a "different first page" header shows only on page one.
+- Removing the header paragraph can leave an empty header that adds vertical space — check the top margin.
+- An image watermark is `v:imagedata`, not a text shape, so the report will not name it; inspect the header XML.
+- A watermark is not security (`tasks/protection_restrict_editing.md`).

package/assets/skills/office-documents/troubleshooting/libreoffice_headless.md

@@ -6,19 +6,19 @@
 "<python>" "<cli>" status
 ```
 
-Look at `renderers.kit` and `renderers.can_render`. `can_render.docx: false` means `docx render` will fail — not with a corrupt file, but with `the LibreOffice renderer is not available`. That is a setup problem, not a document problem.
+Check `renderers.kit` and `renderers.can_render`. `can_render.docx: false` means `docx render` fails with `the LibreOffice renderer is not available` — a setup problem, not a document problem.
 
 ## What renders
 
-Rendering goes through the LibreOffice kit that DeepSeek Harness ships (`@deepseek-ai/libreoffice-kit`). On macOS and Windows it uses the kit's native engine; on Linux it uses the WASM engine. A separately installed Microsoft Office, WPS Office, or system LibreOffice is **not** used and does not make rendering work on its own.
+Rendering goes through the LibreOffice kit DeepSeek Harness ships (`@deepseek-ai/libreoffice-kit`): the kit's native engine on macOS and Windows, the WASM engine on Linux. A separately installed Microsoft Office, WPS Office or system LibreOffice is **not** used and does not make rendering work.
 
 The plugin records the kit's location when the harness loads it, and the helper reads that record before anything else:
 
 1. `DSH_LIBREOFFICE_KIT_CLI` — an explicit override, also handy for a hand-run helper.
-2. `libreofficeKit` in `~/.dsh/office/config.json`. The host half writes this at load, resolving the kit from the harness entry point (`process.argv[1]`, e.g. `<dsh>/node_modules/@deepseek-ai/dsh/lib/bin.js`). This is what makes a profile install work, where the kit lives in the harness tree and not next to the plugin. Configs that pre-0.5 versions wrote in the OS config directory are still read as fallbacks.
+2. `libreofficeKit` in `~/.dsh/office/config.json`. The host half writes it at load, resolving the kit from the harness entry point (`process.argv[1]`, e.g. `<dsh>/node_modules/@deepseek-ai/dsh/lib/bin.js`). This is what makes a profile install work, where the kit lives in the harness tree rather than next to the plugin. Configs that pre-0.5 versions wrote in the OS config directory are still read as fallbacks.
 3. Walking up from the plugin directory through `node_modules/@deepseek-ai/libreoffice-kit/lib/cli.js` — covers a checkout or a plugin-local dependency.
 
-`DSH_OFFICE_CONFIG` points the helper at a different config file; `DSH_NODE` overrides the node binary if `node` is not on `PATH`.
+`DSH_OFFICE_CONFIG` points the helper at a different config file; `DSH_NODE` overrides the node binary when `node` is not on `PATH`.
 
 ## Common failures
 
@@ -33,7 +33,7 @@ The plugin records the kit's location when the harness loads it, and the helper
 
 ## Working without a renderer
 
-Structure, text and metadata are all verifiable headlessly (`docx read`, the audit scripts, `docx_kit.py parts|text|xml`). Layout is not. In that state:
+Structure, text and metadata are verifiable headlessly (`docx read`, the audit scripts, `docx_kit.py parts|text|xml`). Layout is not. In that state:
 
 1. Do the structural verification.
 2. Tell the user that page layout was not visually checked, and why.
@@ -43,4 +43,4 @@ Never describe a page you did not render.
 
 ## Keep renders disposable
 
-Render into a fresh temp directory each time (`--out-dir`). A stale PNG from a previous run reads as a pass and is the most common false confirmation.
+Render into a fresh temp directory each time (`--out-dir`). A stale PNG from an earlier run reads as a pass — the most common false confirmation.

package/assets/skills/office-documents/troubleshooting/run_splitting.md

@@ -1,35 +1,35 @@
 # Splitting a long job
 
-A twenty-section document is not one command. Splitting it into bounded steps keeps each change verifiable and stops one failure from hiding inside a large edit.
+A twenty-section document is not one command. Bounded steps keep each change verifiable and stop one failure hiding inside a large edit.
 
 ## One step per structural change
 
 1. **Plan** — the outline (headings and what each section must establish), written down before any file work.
-2. **Skeleton** — create the file with the outline only: heading blocks, no body text.
-3. **Content, in batches** — a batch per top-level section, appended with `append_blocks.py`.
-4. **Numbers** — captions, cross-references, TOC once the structure is final, never while sections are still moving.
+2. **Skeleton** — the file with the outline only: heading blocks, no body text.
+3. **Content, in batches** — one batch per top-level section, appended with `append_blocks.py`.
+4. **Numbers** — captions, cross-references and TOC once the structure is final, never while sections are still moving.
 5. **Verify** — render, inspect, fix.
 
 ## Why this order
 
-- Captions and TOC are fields over structure; running them after every batch means renumbering noise and a TOC that points at deleted headings.
-- A batch of one section is small enough to redo when the layout is wrong.
-- The skeleton proves the heading hierarchy before the text makes it expensive to change.
+- Captions and TOC are fields over structure; running them after every batch means renumbering noise and a TOC pointing at deleted headings.
+- A one-section batch is small enough to redo when the layout is wrong.
+- The skeleton proves the hierarchy before the text makes changing it expensive.
 
 ## Batch boundaries
 
-- One section per file: `section-01.docx`, `section-02.docx`, then `merge_docx_append.py`. This is the only sane way to draft in parallel or across sessions.
-- Keep a `manifest.json` listing section files in order. Merging is then mechanical and the order is not remembered from chat.
+- One section per file — `section-01.docx`, `section-02.docx` — then `merge_docx_append.py`. This is the only sane way to draft in parallel or across sessions.
+- Keep a `manifest.json` listing the section files in order, so merging is mechanical and the order is not remembered from chat.
 - Merge before numbering, not after.
 
 ## When a batch fails
 
-Do not patch a large edit inside a large document. Discard the failed batch's output, fix the batch, re-apply it to the previous good file. Keep the previous good file until the batch is verified.
+Do not patch a large edit inside a large document. Discard the failed batch's output, fix the batch, re-apply it to the previous good file, and keep that good file until the batch is verified.
 
 ## Context hygiene
 
-- Long sessions lose the document design. Keep the plan and the design defaults (page size, font sizes, table borders) in a file in the workspace and re-read it, rather than trusting recollection.
-- When the user changes a decision mid-job (page size, heading style), record it at the point they said it, and apply it to batches already written.
+- Long sessions lose the document design. Keep the plan and the design defaults (page size, font sizes, table borders) in a workspace file and re-read it instead of trusting recollection.
+- When the user changes a decision mid-job (page size, heading style), record it where they said it and apply it to batches already written.
 
 ## Smoke test after the join
 

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

@@ -1,26 +1,30 @@
 ---
-description: Create, inspect, edit, redact, stamp, and render PDF files with the bundled Office helper CLI and self-contained Python scripts.
+description: Create, extract, fill forms in, merge, split, redact, stamp, render, and verify PDF files with the bundled Office helper CLI and Python scripts.
 ---
 
 # PDF
 
-A PDF page is a content stream of text-showing and path-painting operators behind a page box. Every job in this pack either reads that stream (PyMuPDF, pdfplumber, pypdf), writes a new one (reportlab), or rasterises the result so you can look at it. Work from the mechanics outward: inspect first, choose the smallest operation that changes what the user asked for, then prove the change on a render. The helper CLI and the scripts are fast paths, not limits — each task file carries a runnable snippet for jobs they do not cover yet.
+A PDF page is a content stream of text and path operators behind a page box. Every job here reads that stream (PyMuPDF, pdfplumber, pypdf), writes a new one (reportlab), or rasterises it to check the result. Inspect first, make the smallest change that satisfies the request, then prove it on a render.
 
-| User job | What actually happens | Fast path |
-| --- | --- | --- |
-| Look at a page, crop, or measure geometry | Rasterise the page box with PyMuPDF at a DPI, read page size, rotation, text, drawings, widgets | `scripts/render_pages.py`, `pdf render` |
-| Extract text or tables | pdfplumber reads characters and clusters table rules per page | `scripts/extract_text.py`, `pdf read` |
-| Inspect or fill an AcroForm | pypdf walks `/AcroForm` widgets, then rebuilds each `/AP` appearance from `/V` | `scripts/forms.py`, snippet in `tasks/forms.md` |
-| Remove a region (redaction) | PyMuPDF redaction annotations plus `apply_redactions` strip text and line art inside a rect | `scripts/redact_region.py`, snippet in `tasks/redact.md` |
-| Read or rewrite metadata | The document info dictionary; producer keys cannot change page content | `scripts/metadata.py` |
-| Merge, split, reorder, rotate, delete pages | Page-tree rearrangement; content is copied, not re-flowed | `scripts/page_ops.py`, `scripts/split_pages.py`, snippet in `tasks/edit-pages.md` |
-| Stamp a footer, header, or banner | reportlab draws an overlay page, pypdf merges it over the target pages | `scripts/stamp_overlay.py` |
-| Build a new document | reportlab draws primitives and text into a page | `pdf create`, `tasks/create.md` |
+| User job | Fast path |
+| --- | --- |
+| Look at a page, crop, or measure geometry | `scripts/render_pages.py`, `pdf render` |
+| Extract text, tables, or page images | `scripts/extract_text.py`, `pdf read`, `tasks/read.md` |
+| Inspect or fill an AcroForm | `scripts/forms.py`, `tasks/forms.md` |
+| Remove a region (redaction) | `scripts/redact_region.py`, `tasks/redact.md` |
+| Read or rewrite metadata (info dictionary only, never page content) | `scripts/metadata.py`, `tasks/edit-pages.md` |
+| Merge, split, reorder, rotate, delete pages | `scripts/page_ops.py`, `scripts/split_pages.py`, `tasks/edit-pages.md` |
+| Stamp a footer, header, or label | `scripts/stamp_overlay.py`, `tasks/stamp.md` |
+| Build a new document | `pdf create`, `tasks/create.md` |
+| Resolve an `office-annotations` region | `tasks/annotations.md` |
+| Decide what a PDF cannot do | `references/limits.md` |
+
+Each task file explains the mechanism before giving the command. `references/geometry.md` covers page boxes and normalised regions, `references/layout-quality.md` is the pre-delivery visual checklist, and `references/form-fields.md` covers field flags, appearance streams, and flattening.
 
 ## Before any file work
 
 1. Call the `office_status` tool.
-2. Read the `## Office runtime` JSON block at the end of this file and use its `python`, `cli`, `skill`, and `shared` values verbatim, quoted: `"<python>"`, `"<cli>"`, `"<skill>/scripts/<name>.py"`.
+2. Read the runtime block appended to this file at runtime; use its `python`, `cli`, `skill`, and `shared` values verbatim, quoted: `"<python>"`, `"<cli>"`, `"<skill>/scripts/<name>.py"`.
 3. If that block reports no working runtime, stop. Give the user the `node "..."` remedy command it names, then call `office_status` again. Never fabricate a PDF result you could not verify.
 
 Scripts under `"<skill>/scripts/"` are standalone argparse CLIs. Run `<python> <script> --help` before using one you have not called in this session.
@@ -29,49 +33,45 @@ Scripts under `"<skill>/scripts/"` are standalone argparse CLIs. Run `<python> <
 
 Decide the route before you type a command. Every route ends in the same render check.
 
-- **The file does not exist** → create it from a `pdf create` spec, or with reportlab when the layout does not fit the block model (`tasks/create.md`).
-- **The file exists and must change** → read it first (`pdf read`, and a render), then mutate it with the script named in the task file. The helper CLI has no edit verb: it creates, reads, renders, and reports status only; every change is a `scripts/*.py` call.
-- **A script covers the job** → run it, then verify its JSON report and its rendered pages. Scripts refuse to overwrite their input and exit non-zero on a failed self-check; treat both as hard stops.
+- **No file yet** → create it from a `pdf create` spec, or with reportlab when the layout does not fit the block model (`tasks/create.md`).
+- **Existing file to change** → read it first (`pdf read`, plus a render), then mutate it with the script its task file names. The CLI has no edit verb: it creates, reads, renders, and reports status only, so every change is a `scripts/*.py` call.
+- **A script covers the job** → run it, then check its JSON report and its rendered pages. A refused overwrite or a failed self-check exits non-zero: that is a hard stop.
 - **A read/render verb covers it** → `pdf read`, `pdf render`, or `pdf status`, then verify in the task's own way. Never route a mutation through the CLI.
-- **Neither covers it** → run the runnable snippet in the matching `tasks/*.md` file, or adapt it. Do not invent a CLI verb, and do not tell the user the job is impossible because no verb exists.
-- **Choose the smallest operation** that satisfies the request: metadata change before rebuild, page move before re-creation, one-line patch before re-typing the page.
+- **Neither covers it** → run or adapt the snippet in the matching `tasks/*.md` file. Do not invent a CLI verb, and do not call the job impossible because no verb exists.
+- **Take the smallest operation**: metadata change before rebuild, page move before re-creation, one-line patch before re-typing the page.
 
 ## Failure handling
 
 | Symptom | Meaning | Next step |
 | --- | --- | --- |
-| `{"ok": false, ...}` and non-zero exit | Invalid argument, missing file, or a refused overwrite | Read the `error` field, fix what it names, re-run. Never strip a step to make it pass. |
-| `encrypted` in the error | The file needs a password | Ask the user for a decrypted copy; do not guess passwords or write one into a command. |
-| `the LibreOffice renderer is not available` | Media conversion for docx/pptx/xlsx is unavailable because the DSH LibreOffice kit was not found | PDF rendering still works (PyMuPDF); for a PDF this is harmless. For other formats report that appearance could not be checked. |
+| `encrypted` in the error | The file needs a password | Ask the user for a decrypted copy. Do not guess passwords or write one into a command. |
 | `leftover_chars_in_rect` greater than 0 | The redaction rectangle missed text | Enlarge `--pad` or reconvert the region; re-render before delivering. |
-| `not_applied` is not empty | A form value did not persist after save | Treat as a failure: check the field name, its allowed states, and whether the widget has an appearance stream. |
-| `chars: 0` on a page that shows text | Scanned page, no text layer | Say so; follow `references/limits.md` for the OCR situation. Do not return an empty extraction as success. |
-| Render shows the change, `pdf read` does not | The edit landed in pixels only | Fix the content stream or note the limitation; a visible-only change usually means a cover-up, not an edit. |
+| `not_applied` is not empty | A form value did not persist after save | Treat as a failure: check the field name, its allowed states, and the widget's appearance stream. |
+| `chars: 0` on a page that shows text | Scanned page, no text layer | Say so; follow `references/limits.md`. Never return an empty extraction as success. |
+| Render shows the change, `pdf read` does not | The edit landed in pixels only | Fix the content stream or note the limitation. A visible-only change is usually a cover-up, not an edit. |
+
+General CLI failures, missing runtimes, and the `the LibreOffice renderer is not available` result are covered by `"<shared>/common-workflow.md"`; `pdf render` never needs LibreOffice.
 
 ## Quality rules
 
-- One heading scale, one body size, and one margin system per document (`references/layout-quality.md`).
-- Prove every structural change on a render of the changed page, not only on a text dump.
+- One heading scale, one body size, one margin system per document (`references/layout-quality.md`).
+- Prove every structural change on a render of the changed page, not on a text dump.
 - Keep page geometry consistent when merging or stamping: use each page's own box.
-- Do not claim redaction while the words are still extractable.
-- Preserve the user's original: write `<original>-edited.pdf`, never over it.
-- Mark deliberate shortcuts (a rebuild instead of a reflow, a stamped patch instead of a content edit) in the reply, so the user knows what kind of change they received.
-- Deliver with `present`, then one sentence about what changed and where the file is.
+- Never claim redaction while the words are still extractable.
+- Mark deliberate shortcuts (a rebuild instead of a reflow, a stamped patch instead of a content edit) in the reply.
 
 ## Delivery
 
-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.
+Hand the finished file to the user with the `present` tool, then one sentence on what changed. A bare path is not delivery: the transcript renders `.docx`/`.pptx`/`.xlsx`/`.pdf` links as "二进制文件，无法显示改动", so the user cannot open them.
 
 - 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.
 
 ## Annotations
 
-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.
-
-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.
+An `office-annotations` reply is a change request, not editor state: `[{ 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. Locate what the region covers, apply the smallest edit that satisfies `requirement`, re-render, confirm the region looks right, and say what you could not locate rather than guessing.
 
-For PDF the `page` value is the 1-based page of the file itself, and `region × page.rect` is the real place to operate on: convert once with PyMuPDF and use the device rect directly. `text` is the words under the mark and wins over the region when they disagree; `imageName`, when present, is a screenshot of the marked area that you can open with `read_image`. Full resolution recipe: `tasks/annotations.md` and `"<shared>/annotation-recipes.md"`.
+For PDF, `page` is the 1-based page of the file, and `region × page.rect` is the real rectangle: convert once with PyMuPDF and work in the device rect; `text` wins over the region when they disagree, and `imageName`, when present, is a screenshot of the marked area to open with `read_image`. Full recipe: `tasks/annotations.md`, payload shapes: `"<shared>/annotation-recipes.md"`.
 
 ## Verify
 
@@ -81,22 +81,7 @@ Render before you present, and again after every fix:
 "<python>" "<cli>" pdf render --input "<file.pdf>" --out-dir "<render-dir>" --dpi 110
 ```
 
-Open each PNG with `read_image`, and compare it with the same page rendered before the change. Look for text clipped at the page box, overlapping stamps or form fields, fonts replaced by boxes, rotated pages that now sit sideways, tables spilling past the margin, and scanned pages whose text is an image. Then run `"<python>" "<cli>" pdf read --input "<file.pdf>"` and confirm the text, page count, and form fields match what you edited. Two or three render/patch passes are normal; if a defect survives three, say what still looks wrong instead of calling it fixed.
-
-## Tasks
-
-| Task | Read |
-| --- | --- |
-| Create a PDF from a spec or reportlab | `tasks/create.md` |
-| Extract text, tables, or page images | `tasks/read.md` |
-| Inspect, fill, or flatten an AcroForm | `tasks/forms.md` |
-| Remove a region of a page | `tasks/redact.md` |
-| Merge, split, reorder, rotate, delete pages | `tasks/edit-pages.md` |
-| Stamp a footer, header, or label | `tasks/stamp.md` |
-| Resolve an `office-annotations` region | `tasks/annotations.md` |
-| Decide what a PDF cannot do | `references/limits.md` |
-
-`references/geometry.md` explains page boxes and normalised regions, `references/layout-quality.md` is the pre-delivery visual checklist, `references/form-fields.md` covers field flags, appearance streams, and flattening.
+Open each PNG with `read_image` and compare it with the pre-change render, working through `references/layout-quality.md`. Then run `"<python>" "<cli>" pdf read --input "<file.pdf>"` and confirm the text, page count, and form fields match your edit. Two or three passes are normal; past three, say what still looks wrong instead of calling it fixed.
 
 ## Shared workflow