dsh-office-kit 0.4.2 → 0.4.3

package/assets/skills/office-spreadsheets/tasks/recalc-and-check.md

@@ -1,25 +1,15 @@
 # Recalculate and gate consistency
 
-A workbook written by openpyxl or by a script has formula text and no cached
-results. Open it in a viewer that does not calculate and every formula cell shows
-blank. `xlsx recalc` runs the real engine to fill the cache; the gate then proves
-every formula cell got a value and none of them is an error.
+A workbook written by openpyxl or by a script has formula text and no cached results. Open it in a viewer that does not calculate and every formula cell shows blank. `xlsx recalc` runs the real engine to fill the cache; the gate then proves every formula cell got a value and none is an error.
 
 ```bash
 "<python>" "<cli>" xlsx recalc --input "<book.xlsx>" --out "<book-recalculated.xlsx>"
 "<python>" "<skill>/container_tools/recalc_gate.py" --input "<book-recalculated.xlsx>"
 ```
 
-- `recalc` needs the DSH LibreOffice kit (the same renderer used for images);
-  it runs on Windows, macOS and Linux. Without the kit the verb fails with a
-  plain message and changes nothing.
-- `recalc_gate.py` runs `recalc` for you when given `--cli`: it takes
-  `--input`, writes `<stem>-recalculated.xlsx` unless `--out` is given, then
-  scans every formula cell.
-- It exits `0` clean, `1` with failures, `2` on a usage or file error, and `3`
-  when recalculation was requested but no engine exists. Exit `3` with
-  `verdict: unverified` is an honest result — report it as "structure verified,
-  numbers not recalculated", never as "numbers verified".
+- `recalc` needs the DSH LibreOffice kit (the same renderer used for images) and runs on Windows, macOS and Linux. Without the kit the verb fails with a plain message and changes nothing.
+- `recalc_gate.py --cli` runs `recalc` for you: it takes `--input`, writes `<stem>-recalculated.xlsx` unless `--out` is given, then scans every formula cell.
+- It exits `0` clean, `1` with failures, `2` on a usage or file error, and `3` when recalculation was requested but no engine exists. Exit `3` with `verdict: unverified` is an honest result — report it as "structure verified, numbers not recalculated", never as "numbers verified".
 
 ## What the gate flags
 
@@ -30,28 +20,18 @@ every formula cell got a value and none of them is an error.
 | `dangling` | Formula references a sheet that does not exist | Renaming a sheet without updating formulas does this; restore the name or repoint the reference |
 | `ignored` | Cells you passed with `--ignore` | Pre-existing errors the user asked you to leave alone |
 
-`--strict` treats missing values as failures instead of notes, which is what you
-want after a successful recalc. `--ignore 'Rates!B7,B9'` keeps a known,
-user-accepted error out of the verdict without hiding the rest.
+`--strict` treats missing values as failures instead of notes, which is what you want after a successful recalc. `--ignore 'Rates!B7,B9'` keeps a known, user-accepted error out of the verdict without hiding the rest.
 
 ## Consistency checks the gate cannot do
 
 Recalculation proves formulas evaluate, not that they are right. Check by hand:
 
-- Totals equal the sum of the rows above them, and detail rows add to the
-  summary — not just that both computed something.
+- Totals equal the sum of the rows above them, and detail rows add to the summary — not just that both computed something.
 - Percentages are stored as fractions and formatted, not typed as `6.4`.
-- A case selector drives every tab that claims to follow the case. Two tabs
-  showing different cases is the most expensive defect in a model.
-- Hard-coded overrides are visible (a different fill or a comment) and the
-  formula path still exists. If an override replaced a formula, the workbook can
-  no longer update.
-- Every input the user expects to change is in a cell they can find, not inside a
-  formula constant.
+- A case selector drives every tab that claims to follow the case. Two tabs showing different cases is the most expensive defect in a model.
+- Hard-coded overrides are visible (a different fill or a comment) and the formula path still exists. If an override replaced a formula, the workbook can no longer update.
+- Every input the user expects to change is in a cell they can find, not inside a formula constant.
 
 ## When there is no engine
 
-Report exactly what happened: the file was created and structurally verified, the
-numbers are formulas, and they will populate the first time the user opens the
-file in Excel, LibreOffice, or Sheets. Offer to render so the user sees the layout
-and labels. Do not invent values to make the preview look complete.
+Report exactly what happened: the file was created and structurally verified, the numbers are formulas, and they will populate the first time the user opens the file in Excel, LibreOffice, or Sheets. Offer to render so the user sees the layout and labels. Do not invent values to make the preview look complete.

package/assets/skills/shared/annotation-recipes.md

@@ -1,9 +1,9 @@
 # Annotation recipes
 
-The user may reply to a rendered preview with an `office-annotations` block: a
+The user may reply to a rendered preview with an `office-annotations` payload: a
 JSON array wrapped in `<office-annotations>` … `</office-annotations>` tags.
-Each format sends a slightly different item; the shapes below are what the
-client actually emits.
+Each format sends a slightly different item; these are the shapes the client
+emits.
 
 | Format | Item keys | `page` means |
 | --- | --- | --- |
@@ -23,50 +23,53 @@ client actually emits.
 Rules that apply everywhere:
 
 1. Render the *current* file first and look at the same page the user annotated.
-   Annotation geometry is only meaningful against a render you can reproduce.
+   Geometry is only meaningful against a render you can reproduce.
 2. Locate the concrete object, then apply the smallest edit that satisfies
-   `requirement`. Do not restyle the document, do not rewrite neighbours.
-3. Re-render and look at the edited page again. The item is done when the region
-   shows the requested change and the layout still holds.
+   `requirement`. Do not restyle the document or rewrite neighbours.
+3. Re-render and look at the edited page. The item is done when the region shows
+   the requested change and the layout still holds.
 4. If the payload cannot be tied to an object (empty region, no geometry, no
    matching text), say what you could not locate. Never guess and never move the
    region to make it fit.
 
-Worked examples below use `report.docx`, `report.pdf`, `deck.pptx` and
-`book.xlsx` and the `python`/`cli` values from the `## Office runtime` block.
+Worked examples use `report.docx`, `report.pdf`, `deck.pptx`, and `book.xlsx`,
+plus the `python`/`cli`/`skill` values from the `## Office runtime` block.
 
-## docx — rendered-PDF page plus text matching
-
-`page` is the page of the **rendered PDF preview**, not a Word page number.
-
-```bash
-"<python>" "<cli>" docx render --input "report.docx" --out-dir "render"
-```
-
-This writes `render/page-1.png` and keeps `render/report.pdf`. In the example
-the user circled a sentence on preview page 1 and asked to round it.
-
-Locate it from the text, not from the pixels:
+## Turn a region into page text
 
-- `"<python>" "<cli>" docx read --input "report.docx"` lists every paragraph with
-  its style. Find the paragraph containing `text`.
-- Use `region` only to break ties between two similar paragraphs, or to confirm
-  the preview page number. If they disagree, trust `text` and say so.
-
-Extract the words under the region when you need confirmation. Save this as
-`locate.py` and run it with the runtime python:
+Save this as `region_text.py`; it prints the page rect and the words under the
+region. Run it with the runtime python.
 
 ```python
 import sys, pymupdf
 pdf, page_no, l, t, w, h = sys.argv[1], int(sys.argv[2]), *map(float, sys.argv[3:7])
 page = pymupdf.open(pdf)[page_no - 1]
 r = page.rect
-clip = pymupdf.Rect(r.x0 + l * r.width, r.y0 + t * r.height,
+rect = pymupdf.Rect(r.x0 + l * r.width, r.y0 + t * r.height,
                     r.x0 + (l + w) * r.width, r.y0 + (t + h) * r.height)
-print(" ".join(word[4] for word in page.get_text("words", clip=clip)))
+print(rect, " ".join(word[4] for word in page.get_text("words", clip=rect)))
 ```
 
-Apply the edit and write `<original>-edited.docx`:
+## docx — rendered-PDF page plus text matching
+
+`page` is the page of the **rendered PDF preview**, not a Word page number.
+
+```bash
+"<python>" "<cli>" docx render --input "report.docx" --out-dir "render" --pdf
+```
+
+Writes `render/page-1.png` and `render/report.pdf`.
+
+Locate it from the text, not the pixels:
+
+- `docx read --input "report.docx"` lists paragraphs with styles. Find the one
+  containing `text`.
+- Use `region` only to break ties or confirm the preview page; if they disagree,
+  trust `text` and say so.
+- `region_text.py` on `render/report.pdf` confirms the words under the region.
+
+Apply the edit and write `<original>-edited.docx` with the pack's replacement
+tool:
 
 ```json
 {
@@ -78,63 +81,55 @@ Apply the edit and write `<original>-edited.docx`:
 ```
 
 ```bash
-"<python>" "<cli>" docx edit --input "report.docx" --spec "edit.json" --out "report-edited.docx"
+"<python>" "<skill>/scripts/replace_text.py" --input "report.docx" --spec "edit.json" --out "report-edited.docx" --require-all
 ```
 
-The report returns `replacements`. `0` means `find` did not match verbatim —
-re-read the paragraph text instead of guessing. Then re-render
-`report-edited.docx` and `read_image` page 1. Note that one longer sentence can
-reflow the rest of the page: check the paragraphs below the edit, not just the
-edited line.
+The report returns `replacements` (total), per-pair counts in `pairs`, and
+`misses`; `--require-all` exits 1 when any `find` did not match. Zero means the
+text split across runs or differs verbatim — re-read the paragraph instead of
+guessing. Re-render `report-edited.docx` and `read_image` page 1. A longer
+sentence can reflow the page: check the paragraphs below the edit too.
 
 ## pdf — convert the region and work on the converted rect
 
 `page` is a 1-based page of the PDF itself. `region × page.rect` is the real
-place in the file, so convert once and use the device rect directly.
-
-```python
-import sys, pymupdf
-pdf, page_no, l, t, w, h = sys.argv[1], int(sys.argv[2]), *map(float, sys.argv[3:7])
-page = pymupdf.open(pdf)[page_no - 1]
-r = page.rect
-rect = pymupdf.Rect(r.x0 + l * r.width, r.y0 + t * r.height,
-                    r.x0 + (l + w) * r.width, r.y0 + (t + h) * r.height)
-print(rect, " ".join(word[4] for word in page.get_text("words", clip=rect)))
-```
+place in the file, so convert once and use the device rect directly. Run
+`region_text.py` on `report.pdf`.
 
 Example: page 1, region over the title, `text` "Field report", requirement
-"make the title say Field report (revised), keep the author". The converted rect
-confirms the words under the mark are `Field report`. `imageName`, when present,
-is a screenshot of that region — open it with `read_image` if the text layer is
-ambiguous or the page is scanned.
+"make the title say Field report (revised), keep the author". If `imageName` is
+present, `read_image` it when the text layer is ambiguous or the page is
+scanned.
 
-Choose the edit that the helper actually supports:
+Choose the edit the pack scripts support:
 
-- Metadata, rotation, page order, merge, page removal → `pdf edit`:
+- Metadata → `metadata.py`. Repeat `--set`; unset fields keep their old values.
 
-  ```json
-  { "metadata": { "title": "Field report (revised)" } }
+  ```bash
+  "<python>" "<skill>/scripts/metadata.py" --input "report.pdf" --set "title=Field report (revised)" --out "report-edited.pdf"
   ```
 
+- Rotation, page order, merge, page removal → `page_ops.py`. Indices are
+  zero-based.
+
   ```bash
-  "<python>" "<cli>" pdf edit --input "report.pdf" --spec "edit.json" --out "report-edited.pdf"
+  "<python>" "<skill>/scripts/page_ops.py" --input "report.pdf" --out "report-edited.pdf" --merge "cover.pdf" --order "2,0,1"
   ```
 
-- Text or graphics **on** the page → the helper has no in-place content edit.
-  Rebuild the page from a `pdf create` spec using the text from `pdf read`, then
-  say plainly that the PDF was rebuilt rather than patched. Do not describe a
-  rebuild as a surgical edit.
+- Text or graphics **on** the page → no in-place edit. Rebuild from a
+  `pdf create` spec using `pdf read` text, and say the PDF was rebuilt, not
+  patched. Never call a rebuild a surgical edit.
 
-Verify with `<cli> pdf render --input "report-edited.pdf" --out-dir "render"` and
+Verify with `pdf render --input "report-edited.pdf" --out-dir "render"` and
 `read_image render/page-1.png`. `pdf render` uses PyMuPDF and works without the
 LibreOffice kit, so a PDF annotation is never blocked by a missing renderer.
 
 ## pptx — select the shapes that overlap the region
 
-`page` is the rendered PDF page, and the deck renders one slide per page, so
-page N is slide N. `pptx read` returns slide text but **no shape geometry**, so
-compute overlap yourself with python-pptx. Shape boxes and the payload region are
-both fractions of the slide, so the comparison is direct.
+`page` is the rendered PDF page; one slide per page, so page N is slide N.
+`pptx read` returns slide text but **no shape geometry**, so compute overlap
+yourself with python-pptx. Shape boxes and the payload region are both
+fractions of the slide, so the comparison is direct.
 
 ```python
 import sys
@@ -149,42 +144,37 @@ for shape in prs.slides[slide_no - 1].shapes:
         print(shape.shape_id, shape.text_frame.text.replace("\n", " | "))
 ```
 
-Example: page 2 (slide 2), region over the second bullet, `text` "Renewal 92%",
-requirement "make it 94%". Two shapes overlap the region — the title placeholder
-and the body — and `text` picks the body.
+Example: slide 2, region over the second bullet, `text` "Renewal 92%". Two
+shapes overlap; `text` picks the body.
 
-Apply with the run-level replacement:
+Apply with the pack's run-level replacement; `slide` scopes a rule:
 
 ```json
-{ "replace": [{ "find": "Renewal 92%", "replace": "Renewal 94%" }] }
+{ "replacements": [{ "find": "Renewal 92%", "replace": "Renewal 94%", "slide": 2 }] }
 ```
 
 ```bash
-"<python>" "<cli>" pptx edit --input "deck.pptx" --spec "edit.json" --out "deck-edited.pptx"
+"<python>" "<skill>/container_tools/replace_text.py" --input "deck.pptx" --spec "edit.json" --out "deck-edited.pptx"
 ```
 
-This replacement is not scoped to one slide. Check the returned count, and if
-the same string appeared on other slides, fix those with per-slide `slides[]`
-entries in the same spec. Re-render and `read_image` the page PNG for slide 2.
-If type overflows its shape after the change, shrink the run or shorten the text
-rather than leaving it clipped.
+Without `slide`, a rule hits every slide: check `total` and `slides`, then scope
+any unintended match. `unmatched` lists patterns that found nothing. Re-render
+and `read_image` the page PNG for slide 2. If type overflows its shape, shrink
+the run or shorten the text rather than leaving it clipped.
 
 ## xlsx — no cell reference, so resolve it yourself and say so
 
 xlsx items are always `unmapped: true` with `text: ""`: you get a region, a
 screenshot in `imageName`, and a requirement — no page, no sheet, no A1 range.
-The sheet and cells must be resolved from evidence, never invented.
-
-1. **Look at the screenshot.** `read_image` the attachment named `imageName`.
-   Note the visible column headers, row labels and values inside the marked
-   region. If there is no screenshot, you only have `region` and
-   `requirement` — say so instead of guessing.
-2. **Dump the workbook.** `"<python>" "<cli>" xlsx read --input "book.xlsx"
-   --json-out "book.json"`. Each sheet gives `name`, `dimensions`, `rows` (arrays
-   without coordinates) and `formulas`.
-3. **Resolve the cells.** Match the visible values and headers from step 1
-   against the dumped rows, then derive the A1 address from the row/column
-   index:
+Resolve the sheet and cells from evidence, never invent them.
+
+1. **Look at the screenshot.** `read_image` the `imageName` attachment; note
+   headers, row labels, and values in the region. With no screenshot you have
+   only `region` and `requirement` — say so.
+2. **Dump the workbook.** `xlsx read --input "book.xlsx" --json-out "book.json"`.
+   Sheets give `name`, `dimensions`, `rows` (no coordinates), and `formulas`.
+3. **Resolve the cells.** Match the visible values and headers against the rows,
+   then derive A1 from the row/column index:
 
    ```python
    import json, sys
@@ -198,39 +188,27 @@ The sheet and cells must be resolved from evidence, never invented.
                    print(sheet["name"], f"{get_column_letter(c)}{r}", value)
    ```
 
-   Run it with the runtime python. If several sheets have the same label, or the
-   screenshot does not pin the column, ask which one before editing.
-
-4. **State the resolution before editing.** Tell the user which sheet and A1
-   range you resolved, e.g. "Revenue is `Q4!B2:C2` (10, 12); formatting those
-   cells as currency." Only edit after that, so a wrong guess is visible before
-   it touches the file.
-
-5. **Apply and verify.** Example: screenshot shows `Revenue 10 12` and the
-   requirement is "show these as currency with 2 decimals"; `xlsx read` finds
-   `Revenue` in `Q4!A2` with `10` and `12` beside it:
-
-   ```json
-   {
-     "operations": [
-       { "action": "style", "sheet": "Q4", "cells": { "B2:C2": { "number_format": "#,##0.00" } } }
-     ]
-   }
-   ```
+   If several sheets share the label, or the screenshot does not pin the
+   column, ask which one before editing.
+4. **State the resolution before editing.** Say the sheet and A1 range, e.g.
+   "Revenue is `Q4!B2:C2` (10, 12); formatting those cells as currency." A wrong
+   guess is then visible before it touches the file.
+5. **Apply and verify.** Screenshot shows `Revenue 10 12`; requirement is
+   "currency with 2 decimals"; `xlsx read` finds `Revenue` in `Q4!A2` with `10`
+   and `12` beside it:
 
    ```bash
-   "<python>" "<cli>" xlsx edit --input "book.xlsx" --spec "edit.json" --out "book-edited.xlsx"
+   "<python>" "<skill>/container_tools/style_cells.py" --input "book.xlsx" --out "book-edited.xlsx" \
+     --sheet "Q4" --range "B2:C2" --style '{"number_format":"#,##0.00"}'
    ```
 
-   A `style` operation applies to the whole A1:B2 range in one go. Use
-   `set_cells` to write values, `append_rows` to add rows, `add_sheet` /
-   `delete_sheet` / `rename_sheet` for structure. Then read the edited workbook
-   again to confirm the values.
+   One `--range` styles the whole range. `set_cells.py` sets values/formulas,
+   `append_rows.py` adds rows, `sheet_ops.py` edits sheet structure. Read the
+   workbook back to confirm values.
 
-Forbidden, because both produce plausible-looking edits in the wrong place:
+Forbidden — both put a plausible edit in the wrong place:
 
-- converting `region` pixels into a cell address — the spreadsheet preview has
-  its own zoom and scroll;
+- converting `region` pixels to a cell address (the preview zooms and scrolls);
 - naming a sheet the screenshot does not show or `xlsx read` cannot match.
 
 Visual confirmation needs `xlsx render`, which requires the DSH LibreOffice kit;
@@ -242,10 +220,10 @@ platform); do not present openpyxl's empty cache as a computed value.
 
 Ask one short question, listing what you did find, when:
 
-- the region covers text that exists on several pages and `text` is empty;
+- the region covers text on several pages and `text` is empty;
 - two shapes on a slide both match `text`;
 - the xlsx screenshot does not identify the sheet, or the visible values match
   more than one row or column;
-- the requirement needs an operation the helper does not support (page-content
-  editing in PDF, animation, comments) — offer the rebuild path instead of a
-  silent partial change.
+- the requirement needs an operation the pack scripts do not support
+  (page-content editing in PDF, animation, comments) — offer the rebuild path
+  instead of a silent partial change.

package/assets/skills/shared/common-workflow.md

@@ -1,139 +1,129 @@
 # Shared workflow
 
-Every format pack follows this loop. The helper CLI is an accelerator for common
-operations, not the boundary of what is possible: it shortens the common path,
-and the skill teaches the rest. The format router adds the spec keys and the
-commands; the order, the checks and the failure handling are the same.
+Every format pack follows this loop. The helper CLI is an accelerator, not the
+boundary: the format router adds spec keys and commands; the order, checks, and
+failure handling below are the same.
 
 ## 0. Read the runtime block first
 
-Call the `office_status` tool, then read the `## Office runtime` section that is
-appended to the end of the active `SKILL.md`. It is a fenced JSON block:
+Call `office_status`, then read the `## Office runtime` section appended to the
+active `SKILL.md`. It is a fenced JSON block:
 
 ```json
 { "python": "...\\python.exe", "cli": "...\\python\\office_cli.py", "skill": "...\\assets\\skills\\office-documents", "shared": "...\\assets\\skills\\shared", "version": "3.13.12" }
 ```
 
 - `python` and `cli` are verified absolute paths. Use them verbatim and quote
-  them in commands. Never call a bare `python`, `py`, or `pdftoppm`.
-- `skill` is the directory of the format pack; its scripts live under
-  `<skill>/scripts/`.
-- `shared` is this directory (workflow and annotation recipes).
-- If the block is missing entirely and the skill body instead says *No working
-  Python runtime is available*, stop: do not run any helper command and do not
-  fabricate a document.
+  them. Never call a bare `python`, `py`, or `pdftoppm`.
+- `skill` is the format pack; its scripts live under `<skill>/scripts/`,
+  `container_tools/` (pptx, xlsx), or the pack root.
+- `shared` is this directory (cross-format workflow, recipes, shared scripts).
+- A missing block plus *No working Python runtime is available* means stop: run
+  no helper command and fabricate no document.
 
-`office_status` returns the same facts as JSON with `runtime.state`, the package
-list and `renderers`. Use it when a command fails and you need to know why.
+`office_status` reports `runtime.state`, `python`, `cli`, `packages`, and the
+kit `renderers` facts (`available`, `backend`, `remedy`). Use it when a command
+fails. `<cli> status` additionally reports `can_render` per format.
 
 ## 1. Decide: create or edit
 
-- No existing file → create. Write the output into the user's workspace, not a
-  temp directory, unless the user names a location.
-- Existing file to change → edit. **Never write back over the original.** The
-  output is `<original>-edited.<ext>` next to the original (or the name the user
-  asked for): `report.docx` → `report-edited.docx`. State both paths in the
-  final summary.
+- No existing file → create, in the user's workspace unless they name a location.
+- Existing file → edit. **Never write over the original.** Write
+  `<original>-edited.<ext>` beside it (or the name the user asked for):
+  `report.docx` → `report-edited.docx`.
 - "Improve this document" means read it first (`read` verb) and edit the real
-  content; do not rebuild it from scratch and drop its formatting.
+  content; do not rebuild it and drop its formatting.
+- Never delete the original or "clean up" a temp copy over it. State both paths
+  in the final summary, original first.
 
-## 2. Understand the file, choose the route, then change it
+## 2. Read, choose a route, change
 
-Read or inspect the file before changing it (`read` verb first), then pick the
-cheapest route that actually does the job:
+Read the file first (`read` verb), then take the cheapest route that works:
 
-1. **CLI verb** — the common case. The helper CLI is spec-driven and prints
-   exactly one JSON object on stdout. Failures print
-   `{ "ok": false, "error": "..." }` on stderr and exit non-zero.
+1. **CLI verb** — the common case. Spec-driven; prints one JSON object on stdout.
+   Failures print `{ "ok": false, "error": "..." }` on stderr and exit non-zero.
 
    ```bash
    "<python>" "<cli>" docx|pptx|xlsx|pdf create --spec "<spec.json>" --out "<file>"
    "<python>" "<cli>" docx|pptx|xlsx|pdf read   --input "<file>"
-   "<python>" "<cli>" docx|pptx|xlsx|pdf edit   --input "<file>" --spec "<spec.json>" --out "<file-edited>"
-   "<python>" "<cli>" docx|pptx|xlsx|pdf render --input "<file>" --out-dir "<dir>"
+   "<python>" "<cli>" docx|pptx|xlsx|pdf render --input "<file>" --out-dir "<render-dir>"
    "<python>" "<cli>" xlsx recalc --input "<file>" --out "<file>"
    ```
 
+   There is no `edit` verb: mutation belongs to a pack script or a snippet.
    Write the spec as a JSON file in the workspace; quote absolute paths.
-   `xlsx read` accepts `--data-only`; every command accepts `--json-out <path>`
-   when you want the report on disk instead of stdout.
+   `xlsx read` accepts `--data-only`; `create` (except `pdf`), `read`, `render`,
+   and `xlsx recalc` accept `--json-out <path>`.
 
 2. **Pack script** — a specialised job the CLI has no verb for. Use the script
-   listed in the format router (`<skill>/scripts/`, or `container_tools/` for
-   pptx/xlsx). Scripts are argparse-based, support `--help`, and take absolute
-   paths; run them with the same `"<python>"`.
+   named by the format router (`<skill>/scripts/`, `container_tools/` for
+   pptx/xlsx, or the pack root). Scripts are argparse-based, support `--help`,
+   take absolute paths, and run with the same `"<python>"`.
 
-3. **Library snippet** — the long tail. When neither the CLI nor a pack script
-   covers the change, write a short runnable script in the workspace using the
-   installed libraries (`python-docx`, `openpyxl`, `python-pptx`, `pypdf`,
-   `PyMuPDF`, `reportlab`, `pdfplumber`), run it with `"<python>"`, then verify
-   the file through the same render step. Keep it small and keep the user's
-   original untouched.
+3. **Library snippet** — the long tail. When neither covers the change, write a
+   small runnable script in the workspace with the installed libraries
+   (`python-docx`, `openpyxl`, `python-pptx`, `pypdf`, `PyMuPDF`, `reportlab`,
+   `pdfplumber`), run it with `"<python>"`, then verify through the render step.
+   Keep it small; keep the original untouched.
 
-Never answer "the CLI does not support this, so it cannot be done". A missing
-verb is a missing shortcut, not a missing capability: give the library-level
-route, run it, and verify the result like any other change.
+Never say "the CLI does not support this, so it cannot be done". A missing verb
+is a missing shortcut, not a missing capability: use the script or library
+route, run it, and verify the result.
 
-`check_runtime.py` in this directory validates the interpreter: it imports every
-package from `python/requirements.txt` and runs `<cli> status`. A non-zero exit
-means the environment is broken, not the spec.
+`check_runtime.py` validates the interpreter: it imports every package in
+`python/requirements.txt` and runs `<cli> status`. Non-zero means a broken
+environment, not a bad spec.
 
-## 3. Render and look at the result
+## 3. Render and look
 
 ```bash
-"<python>" "<cli>" docx render --input "<file>" --out-dir "<dir>"
+"<python>" "<cli>" docx render --input "<file>" --out-dir "<render-dir>"
 ```
 
-Output: `<dir>/page-1.png`, `page-2.png`, ... (rasterised at `--dpi`, default
-110). For docx/pptx/xlsx the intermediate PDF is kept at `<dir>/<stem>.pdf` —
-use it for annotation geometry. `pdf render` rasterises with PyMuPDF and needs
-no external renderer.
+Output is `<render-dir>/page-1.png`, `page-2.png`, ... at `--dpi` (default 110).
+For docx/pptx/xlsx, add `--pdf` to also keep `<render-dir>/<stem>.pdf`; use that
+PDF for annotation geometry. `pdf render` uses PyMuPDF and needs no external
+renderer.
 
-Open each page with `read_image`. Look for: text overflowing or clipped at
+Open every page with `read_image`. Check for: text overflowing or clipped at
 margins, overlapping shapes, unexplained blank pages, tables spilling past the
-page, fonts replaced by boxes, missing chart/table content, and numbers that do
-not match what the user asked for.
+page, fonts replaced by boxes, missing chart/table content, numbers that do not
+match the request.
 
-Only after the pages look right do you present the file.
+Present only after the pages look right.
 
 ## 4. Fix, re-render, present
 
-Edit the spec (or the edit spec), re-run the same command, re-render, look
-again. Two or three passes is normal; if a problem survives three passes, say
-what still looks wrong instead of pretending it is fixed.
+Change the spec or script, re-run the same command, re-render, look again. Two
+or three passes is normal. If a problem survives three passes, say what still
+looks wrong instead of pretending it is fixed.
 
 Then call `present` with the final file and reply with one sentence about what
-changed. For an edit, mention the original path and the edited path.
+changed. For an edit, give the original path and the edited path.
 
 ## Rasterizing art
 
-Decks, workbooks and documents embed raster images only, so an SVG or a chosen
-PDF page has to become a PNG first; the same call downscales an oversized raster.
+Documents, decks, and workbooks embed raster images only. Convert an SVG or one
+PDF page to PNG first; the same call downscales an oversized raster.
 
 ```bash
 "<python>" "<shared>/scripts/ensure_raster_image.py" --input "<art.svg>" --dpi 300 --out "<art.png>"
 "<python>" "<shared>/scripts/ensure_raster_image.py" --input "<deck.pdf>" --page 2 --width 1600 --out "<slide-2.png>"
 ```
 
-It prints one JSON object with the PNG's `width`/`height` and never overwrites
-the input. Open that PNG with `read_image` and look at it before embedding it:
-a blank, clipped or miscoloured raster is invisible inside the host file.
+It prints one JSON object with the PNG `width`/`height` and never overwrites the
+input. Open the PNG with `read_image` before embedding: a blank, clipped, or
+miscoloured raster is invisible inside the host file.
 
 ## Failure ladder
 
 | Symptom | Meaning | What you do and say |
 | --- | --- | --- |
-| No `## Office runtime` JSON; skill says *No working Python runtime is available* | The plugin cannot install or find a compatible interpreter | Do not run helper commands, do not write a document by hand. Give the user the remedy command from the skill body, ask them to run it, then call `office_status` again. |
-| `office_status` shows `cli.exists: false`, or `python`/`cli` file not found | The bundled helper or its install is incomplete | Report the missing path. Do not substitute another tool that produces a different file. |
-| `render` fails: `the LibreOffice renderer is not available` | The kit that DSH ships with was not found; create/read/edit still work but docx/pptx/xlsx cannot be rasterised | Do not claim you inspected it. Say the file was built and validated structurally (read verb), but the renderer is unavailable on this host so you could not check its appearance. The kit ships with DeepSeek Harness and the plugin records its path in `config.json` when it loads, so this means the harness install lacks the kit or `DSH_LIBREOFFICE_KIT_CLI` points nowhere; a standalone LibreOffice/Office/WPS install does not help. `pdf render` still works. If the user needs visual confidence now, offer to rebuild from a spec or to present the unverified file explicitly labelled as such. |
-| Annotation region does not land on anything, or the payload says `unmapped: true` | The drawn region cannot be tied to an object in the file | Do not silently shift the region or guess a cell/shape. Say what you could identify (preview page, text, resolved cells) and which item you could not locate, then ask the user for the text or cell. |
-| `{"ok": false, "error": "..."}` and non-zero exit | The spec was rejected (unknown key, bad type, missing file) | Read the error text, fix the spec key it names, re-run the same command. Never strip a failing block to make the command pass — that silently deletes user content. |
-| `xlsx recalc` fails because the LibreOffice kit is missing | openpyxl cannot evaluate formulas, and the kit is the only calculation engine this plugin uses | Report formula cells as uncalculated; do not invent computed values. Fix the renderer first (see the row above) and re-run. |
-| The helper has no verb for what the requirement needs | The common path is short; the capability is not limited to it | Take the pack script route, or write a short snippet against `python-docx` / `openpyxl` / `python-pptx` / `pypdf` / `PyMuPDF` / `reportlab`, run it with `<python>`, then `read` the file back and render. Never refuse a job because a verb is missing. |
-| `read` returns an empty structure for a file the user supplied | Unsupported or corrupt input | Say what failed and stop; do not overwrite the user's file with an empty one. |
-
-## Naming rule for edits (restated)
-
-`<original>-edited.<ext>`, in the same directory as the original, unless the
-user asked for a different name. Never overwrite the original, never delete it,
-never "clean up" a temp copy over it. Deliver both paths, original first.
+| No `## Office runtime` JSON; skill says *No working Python runtime is available* | No usable or installable interpreter | Do not run helper commands or write a document by hand. Give the user the remedy command from the skill body, ask them to run it, then call `office_status` again. |
+| `office_status` shows `cli.exists: false`, or the `python`/`cli` path is missing | The bundled helper or its install is incomplete | Report the missing path. Do not substitute another tool that writes a different file. |
+| `render` fails: `the LibreOffice renderer is not available` | The DSH LibreOffice kit was not found. create/read/scripts still work; docx/pptx/xlsx cannot rasterise | Do not claim you inspected it. Say the file was built and validated structurally, but could not be checked visually. The kit ships with DeepSeek Harness and the plugin records its path in `config.json`; a missing kit or a bad `DSH_LIBREOFFICE_KIT_CLI` causes this. A standalone LibreOffice/Office/WPS install does not help. `pdf render` still works. Offer a rebuild from spec or an unverified file labelled as such. |
+| Region lands on nothing, or the payload says `unmapped: true` | The region cannot be tied to an object in the file | Do not shift the region or guess a cell/shape. Say what you identified and what you could not, then ask for the text or cell. |
+| `{"ok": false, "error": "..."}` plus non-zero exit | The spec was rejected (unknown key, bad type, missing file) | Read the error, fix the named spec key, re-run. Never delete a failing block to make the command pass — that silently deletes user content. |
+| `xlsx recalc` fails: kit missing | openpyxl cannot evaluate formulas; the kit is the only calculation engine | Report formula cells as uncalculated; never invent computed values. Fix the renderer and re-run. |
+| No verb for the requirement | The common path is short, not the capability | Take the pack-script or library route, run it, `read` the file back, and render. Never refuse a job because a verb is missing. |
+| `read` returns an empty structure for a supplied file | Unsupported or corrupt input | Say what failed and stop. Never overwrite the user's file with an empty one. |

package/dist/index.js

@@ -610,7 +610,7 @@ function apply(ctx) {
 			const parsed = parseSkill(raw, path);
 			const runtime = await ensureRuntime(paths.configFile);
 			const kitCli = resolveKitCli();
-			const pythonLine = runtime.state === "ok" && runtime.python != null ? `\n\n## Office runtime\n\nUse these verified absolute paths for every helper command. Quote paths that contain spaces. \`skill\` is this skill's own directory: every script it names lives at \`<skill>/scripts/...\`; \`shared\` holds the cross-format workflow notes; the helper finds \`renderer\` on its own, so never pass it.\n\n\`\`\`json\n${JSON.stringify({
+			const pythonLine = runtime.state === "ok" && runtime.python != null ? `\n\n## Office runtime\n\nVerified absolute paths. Use them for every helper command; quote paths that contain spaces.\n\n- \`python\` runs all helper scripts, \`cli\` is the Office helper CLI.\n- \`skill\` is this skill's directory: its scripts live under \`<skill>/scripts/\`.\n- \`shared\` holds the cross-format notes and shared scripts.\n- \`renderer\` is the DSH LibreOffice kit; the helper finds it itself, so never pass it.\n\n\`\`\`json\n${JSON.stringify({
 				python: runtime.python.path,
 				cli: paths.cli,
 				skill: dirname(path).split("\\").join("/"),