dsh-office-kit 0.4.1 → 0.4.3

package/assets/skills/excel-live-control/style_guidelines.md

@@ -1,87 +1,79 @@
 # Style guidelines for a live sheet
 
-Style is subordinate to content and to the user's own file. Precedence, strongest first:
+Style is subordinate to content and the user's file. Precedence, strongest first:
 
-1. What the user asked for, in this conversation.
+1. What the user asked for in this conversation.
 2. The workbook's existing conventions — fonts, colours, borders, tab colours, number
    formats. Match them; do not impose a house style on someone else's document.
-3. The domain guidance for the kind of model (`domain_guidance/`).
+3. The domain guidance for the model (`domain_guidance/`).
 4. The defaults below.
 
-Look before you paint: `info` for tab colours and structure, `read_range` for the formats
-a neighbouring block already uses. Restyling a user's sheet because your defaults are
-tidier is a defect, not a service.
+Look before you paint: `info` for tab colours and structure, `read_range` for neighbouring
+formats. Restyling because your defaults are tidier is a defect, not a service.
 
 ## Defaults that are safe anywhere
 
-- **Font family**: one per workbook. If it has none, Helvetica Neue → Helvetica → Arial →
-  Aptos. **Two sizes**: 10 pt body, 14 pt title, 16 pt ceiling. Never introduce a third
-  family or a decorative size.
+- **Font**: one family per workbook. If it has none, Helvetica Neue → Helvetica → Arial →
+  Aptos. Two sizes: 10 pt body, 14 pt title, 16 pt ceiling. Never a third family or a
+  decorative size.
 - **Alignment**: text left, numbers right, headers centred horizontally and middle
-  vertically. Do not centre numbers to look neat; they lose their decimal alignment.
+  vertically. Never centre numbers — they lose decimal alignment.
 - **Headers**: bold, one rule under the last header row (`border: "outline"` on the header
-  block, or a bottom border on the row). No merged cells in working headers — merge only a
-  single spanning title, and prefer Center Across Selection for that.
-- **Inputs vs calculations**: an input cell the user is expected to type into gets a light
-  fill (`#FFF2CC` amber) and a thin border; calculated cells keep a plain fill. If the
-  whole block is inputs, one header note beats painting every cell.
-- **Gridlines**: a clean output or dashboard sheet hides them (`ActiveWindow.DisplayGridlines
-  = $false`, a view setting, not a cell format) and uses thin structural borders instead.
-  A working sheet keeps them.
+  block, or a bottom border on the row). No merged cells in working headers; merge only a
+  single spanning title, preferring Center Across Selection.
+- **Inputs vs calculations**: cells the user types into get a light fill (`#FFF2CC` amber)
+  and thin border; calculated cells stay plain. If the whole block is inputs, one header
+  note beats painting every cell.
+- **Gridlines**: a clean output or dashboard hides them
+  (`ActiveWindow.DisplayGridlines = $false`, a view setting, not a cell format) and uses
+  thin structural borders; a working sheet keeps them.
 - **Borders**: outline a block, hairline between header and body. No box around every cell,
-  no double lines, no thick decorative frames.
-- **Column widths**: set them once per block (`column_width` in `style_range`), not per
-  cell. Widen for the formatted value, then check with `read_range --display` for `###`.
-- **Conditional formatting**: bounded to the data range, one or two rules. Never a whole
-  column, never a rule that paints a user input cell.
-- **Freeze panes** are not a styling nicety; the tool cannot set them on a hidden window.
-  If scrolling is the complaint, say so and let the user freeze the row.
+  no double or thick decorative frames.
+- **Column widths**: once per block (`column_width` in `style_range`), not per cell; widen
+  for the formatted value, then check `###` with `read_range --display`.
+- **Conditional formatting**: bounded to the data range, one or two rules; never a whole
+  column, never paint a user input cell.
+- **Freeze panes** are a view setting, not styling. The tool cannot set them on a hidden
+  window; if scrolling is the complaint, say so and let the user freeze the row.
 
 ## Model layouts
 
-- Summary above detail, outputs before workings, assumptions grouped in one block rather
-  than scattered. A reader should be able to look at the top-left and understand the sheet.
-- One blank row at the top of a new output sheet, the title in an unfilled cell on the
-  left, a thin rule under it. No logo, no merged banner, no slogan.
-- Rows of commentary go to the right of the numbers, separated by one blank column; they
-  never sit between a label and its value.
-- Helper rows: italic, grouped under the block they serve, collapsed if the workbook
-  already uses grouping. Helper columns live outside the printed range or on a separate
-  helper sheet.
-- A case or scenario selector is a visible label plus a validated cell: `Case Selected:`
-  and the value on display. Do not hide the control in a defined name.
-- Section bands (a filled row spanning the table) get one outline around the whole
-  section, not per row.
-- Dark header fill with white text, or plain text with a rule. Pick one per workbook.
+- Summary above detail, outputs before workings, assumptions grouped in one block. The
+  top-left should explain the sheet.
+- New output sheet: one blank row at the top, title in an unfilled left cell, thin rule
+  under it. No logo, merged banner or slogan.
+- Commentary goes right of the numbers, separated by one blank column; never between a
+  label and its value.
+- Helper rows: italic, grouped under their block, collapsed if the workbook already groups.
+  Helper columns outside the print range or on a separate helper sheet.
+- Scenario selector: a visible label plus a validated cell (`Case Selected:` and the value);
+  never hidden in a defined name.
+- Section bands: one outline around the whole section, not per row.
+- Dark header fill with white text, or plain with a rule — one per workbook.
 
 ## Finance conventions
 
-These are long-standing reader expectations in financial models; a reviewer notices when
-they are violated.
-
-- **Colour encodes provenance.** Blue font for editable hard-coded inputs, black for
-  formulas on the same sheet, green for links to another sheet, red for links to an
-  external workbook. Results on an output view stay black or the brand dark colour.
-- **Number formats**: `#,##0` for amounts, `#,##0.00` for per-share and price data,
-  `0.0%` for rates, `( )` for negatives and `-` for zero in accounting views
-  (`#,##0;(#,##0);"-"`). Currency symbol on the first monetary row and on totals, not on
-  every row.
-- **Indent formats** (`  @` for text labels, `_(`-style spacing) map a hierarchy without
-  empty columns.
-- **Totals** sit flush left in the label column, bold, with the rule above them. A total
-  that is a hard number rather than a formula is a finding, not a style choice.
-- **Period labels** follow `mmm-yy`, `d-mmm`, `yyyy`, `Q#:YY`, `FY:YY` as the workbook
-  already does. A date column has one format down its whole length.
-- **Actuals vs forecast**: the change of basis is visible — a divide, a different fill, or
-  a label — and never inferred from a colour alone.
-- A model that needs a gutter between the row labels and the numbers gets columns A:B
-  reserved for it. Do not retrofit a gutter onto a sheet that does not have one.
+- **Colour = provenance**: blue font for hard-coded inputs, black for same-sheet formulas,
+  green for links to another sheet, red for links to an external workbook. Output views
+  stay black or brand dark.
+- **Number formats**: `#,##0` amounts, `#,##0.00` per-share/price, `0.0%` rates,
+  `#,##0;(#,##0);"-"` for accounting (parentheses for negatives, dash for zero). Currency
+  symbol on the first monetary row and on totals, not every row.
+- **Indent formats** (`  @` for text labels, `_(`-style spacing) map hierarchy without empty
+  columns.
+- **Totals** flush left in the label column, bold, rule above. A hard-number total instead
+  of a formula is a finding.
+- **Period labels** follow `mmm-yy`, `d-mmm`, `yyyy`, `Q#:YY`, `FY:YY` as the workbook does;
+  one date format down a column.
+- **Actuals vs forecast**: a visible change of basis (divide, fill, label), never colour
+  alone.
+- A needed gutter between row labels and numbers gets columns A:B reserved; do not retrofit
+  one onto a sheet that lacks it.
 
 ## Warning colour, used sparingly
 
 - Input that must be refreshed: amber fill (`#FFF2CC`), normal font.
-- Critical error or failed check: light red fill (`#FFC7CE`) plus bold red text
-  (`#9C0006`).
-- Passing checks: neutral. A green wash over every PASS makes the one red row invisible.
-- Never encode a value only in colour — a reader with a monochrome printout, or a colour
-  vision deficiency, must still see the meaning. Put the flag in a cell.
+- Critical error or failed check: light red fill (`#FFC7CE`) plus bold red text (`#9C0006`).
+- Passing checks: neutral. A green wash over every PASS hides the one red row.
+- Never encode meaning in colour alone; put the flag in a cell so a monochrome printout or
+  colour-vision deficiency still reads it.

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

@@ -1,44 +1,39 @@
 # 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.
+The user sees every step. Plan on paper first, then write in a few batches.
 
-## 1. Decide what is actually being created
+## 1. Decide what is being created
 
-Before you write a cell, you should be able to answer:
+Answer these before writing a cell:
 
-- **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
+- **Who reads it, and what decision does it support?** A committee summary and an analyst's
+  working model are different sheets.
+- **What are the outputs?** Name each one: a number with a label, a period and a unit.
+- **What are the inputs?** Name them with their sources. Inputs nobody updates 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.
+- **What is calculated in between?** A reviewer audits these steps; if you cannot name them,
+  the model is not designed yet.
+- **What would make it wrong?** At least one check: 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.
+If two are still open, ask one short question — 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.
+- Organise by role, not tab count: inputs, assumptions, calculations, outputs. Small sheets
+  merge roles; large models separate them.
+- Outputs left of the tab strip, workings middle, inputs right; a check/audit tab last if
+  warranted.
+- No separate Checks tab on a simple sheet — a labelled verification row is enough.
+- Keep inputs beside their calculations; use a dedicated input sheet once several sheets
+  consume 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.
+- Put insights next to the result they explain, never in a separate 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.
+**This skill cannot add a tab** — it writes into existing sheets. 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. Never repurpose a sheet as scratch space.
 
 ## 3. Write it
 
@@ -51,28 +46,26 @@ 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.
+- One `write_range` per block, in its real shape (rows × columns). No empty-string padding;
+  use `null` for an empty cell.
+- Write labels and units with the numbers. Bare numbers are not done.
+- Apply `number_format` in one `style_range` over the block, not cell by cell.
+- Formulas start with `=`: absolute where fixed (`$C$4`), relative where the fill walks
+  (`D5`). Test one cell before filling.
+- If the sheet has content, check the used range 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`.
+- `read_range --formulas` over everything written; `errors` must be empty.
+- `recalc`, then re-read the outputs — an uncalculated formula proves nothing.
+- `info` after adding tables or charts, to confirm the target sheet.
+- Report the ranges and document state (unsaved, or saved where). See Delivery in
+  `../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.
+- Set widths after content, sized to the widest formatted value; check `###` with
+  `--display`.
+- Wrap long labels instead of widening a column to half the screen.
+- Give helper calculations their own labelled block or sheet, never a row buried between
+  outputs.

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

@@ -1,47 +1,41 @@
 # 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.
+The existing workbook is the reference. Keep its structure, formula style, formats, labels
+and navigation; make one change that looks native.
 
 ## Read the ground first
 
-Nothing below works without this step, and it is cheap:
+Cheap, and nothing below works without it:
 
-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.
+1. `info` — workbook name/path, `saved` flag (unsaved work!), sheets, used ranges, tables,
+   charts, pivots, protection.
+2. `read_range --formulas` over the target block **and its neighbours**. Know the formula
+   pattern before extending it.
+3. `read_range --display` when changing formatting: it shows the format's effect, not the
+   stored value.
+4. Read the surrounding labels: period, unit, actual/forecast. Match the 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.
+If the block holds values you cannot explain from the request, stop and ask.
 
 ## 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).
+- **Change the cells the request names and the formulas those cells feed.** A changed input
+  propagates; do not hand-edit downstream totals.
+- **Do not add, remove, rename, reorder or split sheets** unless requested, or the change
+  cannot otherwise be expressed (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,
+  comments, protection, hidden/grouped rows, user freeze panes, 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.
+- **Never flatten formulas to values** — not to "simplify", not to "fix" a display problem.
+- **Extend, do not replace.** A row or column added under a table, conditional format or
+  chart extends that object (`ListObject.Resize`, `SetSourceData`), never a parallel one.
+- **Keep visual fixes local.** Widen the one clipped column. No sheet-wide autofit, no
+  restyle because it is not your default.
+- **Match formula conventions**: anchoring style, `SUMIFS` vs `SUMPRODUCT`, rounding, error
+  handling. A "better" formula that reads differently costs maintenance.
+- **Pre-existing errors are not yours to fix.** Report the cell, its formula and ask;
+  silently repairing `#REF!` can change a number the user relies on.
 
 ## Doing it
 
@@ -54,19 +48,17 @@ 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.
+- Keep writes to the named rectangle. `--clear` only a range whose contents you have read
+  and can restore.
+- Copy style codes from the neighbouring block: read a matching cell, mirror its
+  `number_format`, apply to the new cells. Do not invent a format for one row.
+- A formula that must differ from the pattern (different anchor, one-off): say why in the
+  reply.
 
 ## 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.
+- `read_range --formulas` over every changed cell and its neighbours.
+- `recalc` after formulas, then re-read dependents.
+- `info` if tables, charts or pivots were extended, to confirm coverage of the new cells.
+- Report sheet, exact ranges, cell counts and saved state. If the formula graph changed,
+  name the affected outputs.

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

@@ -1,77 +1,39 @@
 ---
-description: Build, inspect, revise, and visually verify Word .docx files using the Office helper CLI and the bundled XML scripts.
+description: Create, read, edit, render, and verify Word documents (.docx) — build new files, revise existing ones, and check the rendered pages.
 ---
 
 # Documents (.docx)
 
-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.
+A `.docx` is a zip of XML parts: `word/document.xml` holds the body, with headers, footers, footnotes, comments, styles and numbering beside it. Two routes reach them: the helper CLI (`docx create`, `docx read`, `docx render`, no in-place mutation) and `scripts/*.py`, which edits everything structural — text, blocks, properties, comments, tracked changes, fields, protection, watermarks. Pick the cheapest route that yields the requested structure, then look at the pages. Never invent content; never deliver a file you have not looked at.
 
 ## Before any file work
 
-1. Call the `office_status` tool.
-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. Spaces, non-ASCII names and `&` are normal on Windows.
+Call `office_status`, then read the `## Office runtime` block at the end of this file — it holds the verified `python`, `cli`, `skill` and `shared` paths for this install. If there is no runtime, stop, give the user the `node "..."` remedy command, and call `office_status` again — never fake a document or claim success. Quote every path: spaces, non-ASCII names and `&` are normal on Windows.
 
 ## 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.
-
-- 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.
+Deliver with `present` plus a one-sentence summary. A bare path is not delivery: the transcript renders `.docx`/`.pptx`/`.xlsx`/`.pdf` links as "二进制文件，无法显示改动". Write new files into the workspace, verify, `present`. Never overwrite an original — write `<original>-edited.<ext>` (or the user's name), verify, `present`, 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.
-
-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.
+An `office-annotations` payload is `[{ page, text, requirement, region: { left, top, width, height } }]`: `region` normalised 0–1 against the rendered preview page, `requirement` free-form. Treat it as a change request, not editor state — find what the region covers, apply the smallest edit that satisfies `requirement`, re-render, confirm. Unmappable payload (empty region, no geometry): say what you could not locate; never guess. For `.docx`, `page` is a rendered PDF page, not a Word page: locate by `text` and its neighbouring paragraphs, use the region only for near-misses, and name the object you picked when a region lands on a table row, caption or header.
 
 ## Verify
 
-Rendering is the only proof that a document looks right.
-
 ```bash
 "<python>" "<cli>" docx render --input "<file.docx>" --out-dir "<render-dir>"
 ```
 
-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 (`renderers.can_render.docx: false` — the DSH LibreOffice kit is missing), ask the user to fix the install, 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.
+Writes a PDF and one PNG per page and prints the paths. Open each PNG with `read_image`; check heading hierarchy, table width and cell wrapping, page breaks, header/footer, clipped or overflowing text, missing glyphs (dashes, CJK, symbols), equations, caption placement. Iterate, then deliver — "it parses" is not verification. Without a renderer (`office_status` reports `renderers.available: false`, with a `remedy`) ask the user to fix the install or fall back to `docx read` plus the audit scripts; say layout was not visually verified and never describe an unseen page. Re-render after every script edit: a package can be valid while its page is broken. Details: `tasks/verify_render.md`. Setup: `troubleshooting/libreoffice_headless.md`.
 
 ## Task index
 
-| Task | Read | Main tool |
+| Job | Task doc | CLI or 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` |
+| Create a document | `tasks/create_edit.md` | `docx create --spec`, `python-docx` snippet, `append_blocks.py` |
+| Read and review a file | `tasks/read_review.md` | `docx read`, `docx_kit.py text`, `style_lint`, audits |
+| Edit text, blocks or properties | `tasks/create_edit.md` | `replace_text.py`, `append_blocks.py`, `core_properties.py` |
+| Comments | `tasks/comments_manage.md` | `comments_*.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` |
@@ -79,7 +41,7 @@ Where no verb exists, the fallback is the listed script or a short `python-docx`
 | 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` |
+| Tables and geometry | `tasks/tables_spreadsheets.md` | `docx create` table block, `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` |
@@ -91,24 +53,26 @@ Where no verb exists, the fallback is the listed script or a short `python-docx`
 | 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) |
+| Comparing versions | `tasks/compare_diff.md` | `docx render`, `render_and_diff.py` |
+| Equations | `tasks/equations.md` | `docx create` `equation` block |
+| Visual verification | `tasks/verify_render.md` | `docx render`, `render_docx.py` (skill root) |
 | Fixtures and edge cases | `tasks/fixtures_edge_cases.md` | `make_fixtures.py` |
 
+Where no verb exists, use the listed script or a short `python-docx`/`lxml` snippet — both run on the runtime `python` without a new dependency.
+
 ## 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.
+- Black headings and body; colour only for deliberate emphasis, links and chart series.
+- Tables: `#D9D9D9` borders, bold header row, `w:tblHeader` repeat, no vertical merges in wide tables.
+- No callout boxes, drop shadows or coloured sidebars — structure comes from headings, lists and tables.
+- Captions under figures and above tables, `Caption` style, staying with the object.
+- Prefer native headings, lists, tables and OMML equations over hand-positioned runs: 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.
+Plain sentences, no filler. Checklist `references/writing-quality.md`; package parts `references/docx-structure.md`.
 
 ## 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.
+Cross-format habits and annotation payloads: `"<shared>/common-workflow.md"`, `"<shared>/annotation-recipes.md"`.

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

@@ -1,6 +1,6 @@
 # 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".
+A short job touching creation, inspection, structural change and verification. Run it 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"
@@ -41,7 +41,7 @@ Expect `ok: true` and non-zero `headings`, `tables`, `equations`.
 "$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`.
+Expect the sections, `word/document.xml` in the parts list, Letter 8.5×11 portrait, and an empty style-lint `counts`.
 
 ## 3. Change it structurally
 
@@ -63,7 +63,7 @@ Expect the sections, the parts list to include `word/document.xml`, Letter 8.5×
 "$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.
+Audits may exit 1 with findings: that is a report, not an environment failure. Every finding should be explainable.
 
 ## 5. Verify visually
 
@@ -71,7 +71,7 @@ Audits may exit 1 with findings — that is a report, not a failure of the envir
 "$PY" "$R/render_docx.py" "$W/with-toc.docx" --output_dir "$W/render" --dpi 150
 ```
 
-Then open each PNG with `read_image`. Without the DSH LibreOffice kit the command exits 3 with `no_renderer`; that is a setup problem, not a document problem, and the rest of the test still stands.
+Open each PNG with `read_image`. Without the DSH LibreOffice kit the command exits 3 with `no_renderer`: a setup problem, not a document problem, and the rest of the test still stands.
 
 ## 6. Deliver
 
@@ -83,4 +83,4 @@ Copy the final file into the user's workspace, `present` it, and state what chan
 rm -rf "$W"
 ```
 
-Nothing under the workspace should be left behind from a smoke test.
+Nothing under the workspace should be left behind by a smoke test.

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

@@ -1,6 +1,6 @@
 # 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.
+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 a relationship plus content-type override make the part exist at all.
 
 ## The markup
 
@@ -20,21 +20,21 @@ A comment is three pieces that must agree: `word/comments.xml` holds the content
 
 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.
+- `w:id` is unique across comments **and** matches 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 elsewhere 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.
+- The file root lists `w14`/`w15` in `mc:Ignorable`; the `w15:done` "resolved" attribute is only legal with those namespaces 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.
+`w15:done="1"` on `w:comment` keeps the comment in the file and shows it as resolved. Removing it is a different operation: delete the `w:comment`, both range markers and the reference run. Resolving hides the comment 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.
+- Replies are comments too, linked by `w15:paraIdParent`; removing 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.
+- A comment deleted in Word leaves no trace, but 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.
+`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` for the raw part.