dsh-office-kit 0.4.2 → 0.4.3

package/assets/skills/office-presentations/tasks/charts-tables-notes.md

@@ -1,7 +1,6 @@
 # Task: charts, tables and speaker notes
 
-Three things that look like one job and share one rule: the numbers must be
-checkable from the file.
+One rule across all three: the numbers must be checkable from the file.
 
 ## Charts
 
@@ -11,19 +10,18 @@ Native, always:
 "<python>" "<cli>" pptx create --spec with-chart.json --out charted.pptx
 ```
 
-or the recipe when you need control of axis, labels or legend:
-[native-charts](../recipes/native-charts.md).
+Or the [native-charts recipe](../recipes/native-charts.md) when you need control
+of axis, labels or legend.
 
-Spec keys the builder accepts: `type` (`bar`/`column`/`line`/`pie`, where bar and
-column both render as a clustered column), `title`, `categories`,
-`series[{name, values}]`, `left`, `top`, `width`, `height`.
+Spec keys: `type` (`bar`/`column`/`line`/`pie`; bar and column both render as a
+clustered column), `title`, `categories`, `series[{name, values}]`, `left`,
+`top`, `width`, `height`.
 
 - The chart title says what the chart means; the slide title states the
   conclusion. If both say the same thing, drop the chart title.
-- Categories in the order the reader thinks in.
-- Bars start at zero.
-- A chart that duplicates a table on a neighbouring slide is a review finding,
-  not a second view — pick one.
+- Categories in the order the reader thinks in. Bars start at zero.
+- A chart duplicating a table on a neighbouring slide is a review finding, not a
+  second view — pick one.
 
 Verify:
 
@@ -35,8 +33,8 @@ Verify:
 ## Tables
 
 Spec form (`{"headers": [...], "rows": [[...]]}`) puts the table at the cursor,
-full width; the [tables recipe](../recipes/tables.md) gives you the rect, column
-widths, alignment and the total row styling.
+full width; the [tables recipe](../recipes/tables.md) gives the rect, column
+widths, alignment and total-row styling.
 
 Rules: numbers right-aligned, units in the header, total row computed not typed,
 seven rows maximum on a slide.
@@ -47,8 +45,8 @@ Declare each total so it can be proved:
 "<python>" "<skill>/container_tools/native_table_arithmetic_gate.py" --input charted.pptx --contracts totals.json
 ```
 
-A mismatch exit code is a data bug or a rounding bug. Fix the number or declare
-the rounding; never lower the tolerance to make it pass.
+A mismatch is a data bug or a rounding bug. Fix the number or declare the
+rounding; never lower the tolerance to make it pass.
 
 ## Speaker notes
 
@@ -65,15 +63,14 @@ confirm they landed:
 "<python>" "<skill>/container_tools/inspect_presentation_package_integrity.py" --input deck-notes.pptx
 ```
 
-`notesSlides` in the part counts should equal the number of slides you wrote
-notes for.
+`notesSlides` must equal the number of slides you wrote notes for.
 
-Notes carry: the sentence you will say, the provenance of any non-obvious
-number, and the answer to the question the slide invites. Nothing that belongs
-on the slide.
+Notes carry: the sentence you will say, the provenance of any non-obvious number,
+and the answer to the question the slide invites. Nothing that belongs on the
+slide.
 
 ## Putting them together
 
-A results slide usually wants: one claim as the title, one chart as the
-evidence, one caption as the source, and the detail in notes. If it needs a
-chart *and* a table, it is two slides — or the table is an appendix.
+A results slide wants one claim as the title, one chart as the evidence, one
+caption as the source, and the detail in notes. If it needs a chart *and* a
+table, it is two slides — or the table is an appendix.

package/assets/skills/office-presentations/tasks/create-deck.md

@@ -5,10 +5,10 @@
 - Audience and setting: live talk, read-on-its-own PDF, or both. A read-only
   deck needs more words; a live deck needs fewer.
 - Length: number of slides or minutes.
-- Brand: a template file, a colour, or nothing (then use the defaults in
-  [style-guidelines](../references/style-guidelines.md)).
-- Evidence: numbers, charts, tables and images the user already has. Never
-  invent a metric — if a number is needed and missing, say so.
+- Brand: a template file, a colour, or the defaults in
+  [style-guidelines](../references/style-guidelines.md).
+- Evidence: numbers, charts, tables, images the user has. Never invent a metric —
+  if a number is needed and missing, say so.
 
 ## Route
 
@@ -65,21 +65,20 @@ For the ordinary deck (cover, bullets, section, table, chart, image, closing):
 }
 ```
 
-Layouts map to `title`, `bullets`, `section`, `title_only`, `blank`. Tables are
-placed at 0.8 in from the left at the running cursor and cannot be positioned —
-put a table on its own slide, or use the [tables recipe](../recipes/tables.md).
+Layouts: `title`, `bullets`, `section`, `title_only`, `blank`. Tables sit 0.8 in
+from the left at the running cursor and cannot be positioned — give a table its
+own slide, or use the [tables recipe](../recipes/tables.md).
 
 ### Everything else: build it with the recipes
 
-Anything at a coordinate, any crop, any connector, any master change is a
-`python-pptx` snippet:
-
-- [textbox at a coordinate](../recipes/textbox-at-coordinate.md)
-- [auto-layout rules](../recipes/autolayout.md)
-- [tables](../recipes/tables.md) · [native charts](../recipes/native-charts.md)
-- [images](../recipes/images.md) · [connectors](../recipes/connectors.md)
-- [rich text runs](../recipes/rich-text-runs.md) · [theme tokens](../recipes/theme-tokens.md)
-- [speaker notes](../recipes/speaker-notes.md) · [masters and layouts](../recipes/master-and-layouts.md)
+Anything at a coordinate, any crop, connector or master change is a `python-pptx`
+snippet: [textbox at a coordinate](../recipes/textbox-at-coordinate.md),
+[auto-layout](../recipes/autolayout.md), [tables](../recipes/tables.md) ·
+[native charts](../recipes/native-charts.md), [images](../recipes/images.md) ·
+[connectors](../recipes/connectors.md), [rich text
+runs](../recipes/rich-text-runs.md) · [theme tokens](../recipes/theme-tokens.md),
+[speaker notes](../recipes/speaker-notes.md) · [masters and
+layouts](../recipes/master-and-layouts.md).
 
 Extending a deck you already built:
 
@@ -100,7 +99,8 @@ template's look by hand.
 
 ## Writing the slides
 
-Story first. Write the one-sentence claim for every slide, in order, then fill
-the frames. If a claim needs two sentences, it is two slides. Keep bullets as
-claims ([native-bullets](../references/native-bullets.md)) and evidence native
+Story first: the one-sentence claim for every slide, in order, then fill the
+frames (loop in [authoring-workflow](../references/authoring-workflow.md)). A
+claim needing two sentences is two slides. Bullets are claims
+([native-bullets](../references/native-bullets.md)); evidence is native
 ([native-evidence](../references/native-evidence.md)).

package/assets/skills/office-presentations/tasks/edit-deck.md

@@ -2,7 +2,7 @@
 
 Editing is mutation, and mutation lives in this pack's tools, not in the helper
 CLI: `container_tools/replace_text.py`, `add_slides.py`, `core_properties.py`,
-plus the recipes for everything structural.
+plus the recipes for anything structural.
 
 **Never write over the original.** Every tool defaults to
 `<original>-edited.pptx`; keep that default unless the user names a path.
@@ -14,9 +14,8 @@ plus the recipes for everything structural.
 "<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx
 ```
 
-`pptx read` gives titles, text, tables and chart data per slide. The geometry
-gate gives every shape's rect in inches, which is what you need to decide
-whether a new block fits.
+`pptx read` gives titles, text, tables and chart data per slide; the geometry
+gate gives every shape's rect in inches, to decide whether a new block fits.
 
 ## 2. Text changes: run-level replace
 
@@ -41,11 +40,11 @@ Batch form:
 "<python>" "<skill>/container_tools/replace_text.py" --input deck.pptx --spec replacements.json
 ```
 
-Semantics that matter: a pattern only matches **inside a single run**. Text that
-PowerPoint split for formatting ("**Q4** 2025") will not match "Q4 2025" and the
-report lists it under `unmatched`. When a pattern cannot match, that is the
-signal to edit that paragraph with a run-level snippet
-([rich text runs](../recipes/rich-text-runs.md)) rather than widening the match.
+A pattern matches **inside a single run** only. Text PowerPoint split for
+formatting ("**Q4** 2025") will not match "Q4 2025" and the report lists it under
+`unmatched`. When a pattern cannot match, edit that paragraph with a run-level
+snippet ([rich text runs](../recipes/rich-text-runs.md)) rather than widening the
+match.
 
 Exit code 1 means a pattern matched nothing; the file is still written, so read
 `unmatched` before delivering.
@@ -56,10 +55,9 @@ Exit code 1 means a pattern matched nothing; the file is still written, so read
 "<python>" "<skill>/container_tools/add_slides.py" --input deck.pptx --spec extra-slides.json
 ```
 
-The spec is the same slide object as `pptx create` (`layout`, `title`,
-`subtitle`, `bullets`, `table`, `chart`, `image`). For anything outside that
-vocabulary, add the slide with `add_slides.py` and then place content with a
-recipe.
+The spec uses the same slide object as `pptx create` (`layout`, `title`,
+`subtitle`, `bullets`, `table`, `chart`, `image`). Outside that vocabulary, add
+the slide with `add_slides.py`, then place content with a recipe.
 
 ## 4. Metadata
 
@@ -72,7 +70,7 @@ recipe.
 
 | Change | Route |
 |---|---|
-| Move or resize a shape | recipe: set `.left/.top/.width/.height` on the shape from `slide.shapes` |
+| Move or resize a shape | set `.left/.top/.width/.height` from `slide.shapes` |
 | Restyle a family | [masters and layouts](../recipes/master-and-layouts.md) |
 | Add notes | [speaker notes](../recipes/speaker-notes.md) |
 | Replace a chart's data | [native charts](../recipes/native-charts.md) — edit the series, do not paste a picture |
@@ -89,5 +87,5 @@ relational:
 "<python>" "<skill>/container_tools/render_slides.py" --input deck-edited.pptx --out-dir preview
 ```
 
-Then look at the changed pages. A text replacement that pushes a title onto a
-third line is a layout change, not a text change.
+Then look at the changed pages. A replacement that pushes a title onto a third
+line is a layout change, not a text change.

package/assets/skills/office-presentations/tasks/inspect-and-verify.md

@@ -1,7 +1,7 @@
 # Task: inspect and verify a deck
 
-Verification is reading the artefact back and looking at it. The tools below
-print one JSON object each; `passed` is the decision.
+Verification is reading the file back and looking at it. Each tool prints one
+JSON object; `passed` is the decision.
 
 ## 1. What is in the file
 
@@ -10,8 +10,7 @@ print one JSON object each; `passed` is the decision.
 ```
 
 Per slide: title, all text, tables as rows, charts with type/title/categories/
-series, image count. This is the cheapest sanity check that the content you
-meant to write is the content that was written.
+series, image count. Cheapest check that what was written is what was intended.
 
 ## 2. Is the package coherent
 
@@ -19,10 +18,10 @@ meant to write is the content that was written.
 "<python>" "<skill>/container_tools/inspect_presentation_package_integrity.py" --input deck.pptx
 ```
 
-Checks required parts, slide/master presence, dangling relationships, XML that
-does not parse, slide count drift and duplicate parts, then reports part counts
-(`slides`, `layouts`, `masters`, `charts`, `notesSlides`, `media`,
-`embeddings`). A chart with an `embeddings` count of zero has lost its data.
+Checks required parts, slide/master presence, dangling relationships, unparseable
+XML, slide-count drift, duplicate parts; reports part counts (`slides`, `layouts`,
+`masters`, `charts`, `notesSlides`, `media`, `embeddings`). Zero `embeddings` on a
+chart means lost data.
 
 ## 3. Does the layout hold
 
@@ -30,13 +29,12 @@ does not parse, slide count drift and duplicate parts, then reports part counts
 "<python>" "<skill>/container_tools/inspect_presentation_layout_geometry.py" --input deck.pptx --json-out geometry.json
 ```
 
-`fail` findings (block a delivery): shape outside the slide, degenerate size,
-text that cannot fit its frame, table outside the slide, chart or table covered
-by another shape. `review` findings (read them, then decide): text overlap,
-empty placeholder, title under 28 pt, body under 14 pt, heading ending in a full
-stop, connector across text, a chart duplicating a table's labels.
-
-Add `--strict` to make review findings blocking for a formal deck.
+`fail` blocks delivery: shape outside the slide, degenerate size, text that
+cannot fit its frame, table outside the slide, chart or table covered by another
+shape. `review` needs a decision: text overlap, empty placeholder, title under
+28 pt, body under 14 pt, heading ending in a full stop, connector across text, a
+chart duplicating a table's labels. `--strict` makes review blocking for a formal
+deck.
 
 ## 4. Are the numbers real
 
@@ -51,11 +49,11 @@ Add `--strict` to make review findings blocking for a formal deck.
 - Quantitative charts: every declared chart must be a real chart part with a
   readable series, and in the default `portable` mode must carry its embedded
   workbook.
-- Table arithmetic: only declared totals are enforced, compared against the
-  displayed rounding; columns whose header is not additive (unit price, ratio,
-  percent) are skipped rather than summed wrongly.
+- Table arithmetic: only declared totals are enforced, against displayed
+  rounding; non-additive columns (unit price, ratio, percent) are skipped rather
+  than summed wrongly.
 
-`totals.json` names the contract explicitly:
+`totals.json` names the contract:
 
 ```json
 { "contracts": [{ "slide": 4, "table": 1, "total_row": 6, "columns": [1, 2] }] }
@@ -67,32 +65,31 @@ Add `--strict` to make review findings blocking for a formal deck.
 "<python>" "<skill>/container_tools/render_slides.py" --input deck.pptx --out-dir preview
 ```
 
-Writes `slide-NN.png` plus `render.json`. Then `read_image` every PNG — an
-unlooked-at render is not verification.
+Writes `slide-NN.png` plus `render.json`; `read_image` every PNG — an unlooked-at
+render is not verification.
 
-To see the whole deck at once:
+Whole deck at once:
 
 ```bash
 "<python>" "<skill>/template_following_scripts/make_contact_sheet.py" --dir preview --out sheet.png --columns 3
 ```
 
-or `"<skill>/container_tools/create_montage.py` with an explicit file list.
+Or `"<skill>/container_tools/create_montage.py` with an explicit file list.
 
-Look for: clipped text, overlapping blocks, a title that reflowed, a chart whose
-point is invisible at thumbnail size, a photograph stretched, a slide with no
-title.
+Look for: clipped text, overlapping blocks, a reflowed title, a chart point
+invisible at thumbnail size, a stretched photograph, a slide with no title.
 
 ## 6. When nothing can render
 
-With the DSH LibreOffice kit missing (`office_status` → `renderers.kit` /
-`renderers.can_render`), `render_slides.py` falls back to `--engine draft`, a
-PyMuPDF geometry preview. It shows placement, overflow and overlap — not
-typography or theme chrome. Say so when reporting: "verified as a geometry
-preview" is honest, "looks great" from an approximate render is not.
+Without the DSH LibreOffice kit (`office_status` → `renderers.available: false`,
+with a `remedy`), `render_slides.py` falls back to `--engine draft`, a
+PyMuPDF geometry preview: placement, overflow, overlap — not typography or theme
+chrome. Say so: "verified as a geometry preview" is honest; "looks great" from an
+approximate render is not.
 
-If even the preview cannot run, the delivery is unverified: report the failing
-command, the file's slide count from `pptx read`, and the gate results, and tell
-the user which renderer to install for a visual check.
+If even the preview cannot run, report the failing command, the slide count from
+`pptx read`, and the gate results; name the renderer to install for a visual
+check.
 
 ## Gate summary
 

package/assets/skills/office-presentations/tasks/template-following.md

@@ -1,8 +1,7 @@
 # Task: follow a supplied template
 
 Use this when the user hands over a `.pptx` and says "use our template" or "match
-this deck". The design is already decided; your job is to put content into its
-own slides.
+this deck". The design is decided; put content into its own slides.
 
 ## 1. Inspect
 
@@ -10,16 +9,14 @@ own slides.
 "<python>" "<skill>/template_following_scripts/inspect_template_deck.py" --template brand.pptx --out-dir template-inspect
 ```
 
-Outputs:
-
 - `template-inspect.ndjson` — one JSON line per slide: layout name, layout
   placeholders, slide placeholders (index, kind, rect in inches, text), shape
-  counts, text excerpt, whether the slide has full-bleed background art.
+  counts, text excerpt, full-bleed background art flag.
 - `template-manifest.json` — slide size, aspect ratio, layout names, theme font
-  names, and `backgroundArtSlides`.
+  names, `backgroundArtSlides`.
 
-Read `backgroundArtSlides` before adding anything: those slides already carry
-artwork, so a new opaque panel will cover it.
+Read `backgroundArtSlides` first: those slides already carry artwork, so a new
+opaque panel covers it.
 
 ## 2. Plan
 
@@ -65,13 +62,13 @@ Write `frame-map.json`:
 
 Allowed actions: `rewrite`, `rewrite-and-reposition`, `replace`, `delete`,
 `keep`, `fill-placeholder`. `target.zone` is `[x, y, w, h]` in 0–1 slide
-fractions, used with `rewrite-and-reposition`. Elements whose `role` is
-`brand`, `logo`, `bumper`, `divider`, `section`, `chrome` or `footer` must stay
-`keep` — they are the template.
+fractions, used with `rewrite-and-reposition`. Elements whose `role` is `brand`,
+`logo`, `bumper`, `divider`, `section`, `chrome` or `footer` must stay `keep` —
+they are the template.
 
-Adding new shapes is opt-in: set `newPrimitives.allowed` and write a
-justification. The validator rejects shapes added without it, because "one extra
-box" is how a branded deck stops matching brand.
+New shapes are opt-in: set `newPrimitives.allowed` and justify it. The validator
+rejects additions without that, because "one extra box" is how a branded deck
+stops matching brand.
 
 ## 3. Validate
 
@@ -79,10 +76,10 @@ box" is how a branded deck stops matching brand.
 "<python>" "<skill>/template_following_scripts/validate_template_plan.py" --plan frame-map.json
 ```
 
-Rejects: unknown action, preserved role edited, zone outside 0–1, non-sequential
+Rejects unknown action, edited preserved role, zone outside 0–1, non-sequential
 slide numbers, missing justification for new primitives, and duplicate source
-slides (a warning — it means two output slides share artwork, usually fine for a
-repeated section divider, usually a copy-paste mistake otherwise).
+slides (a warning: shared artwork — fine for a repeated divider, usually a
+copy-paste mistake otherwise).
 
 ## 4. Build
 
@@ -90,12 +87,11 @@ repeated section divider, usually a copy-paste mistake otherwise).
 "<python>" "<skill>/template_following_scripts/prepare_template_starter_deck.py" --template brand.pptx --plan frame-map.json --out starter.pptx
 ```
 
-The starter deck keeps only the mapped source slides, in plan order, and applies
-the actions. It refuses duplicate source slides (it reuses slides rather than
-cloning parts). The report lists applied actions and any placeholder left empty.
-
-From here, extend with `container_tools/add_slides.py` or the recipes when the
-template has no family for a slide you need.
+Keeps only the mapped source slides in plan order and applies the actions. It
+refuses duplicate source slides (reuses slides rather than cloning parts). The
+report lists applied actions and any empty placeholder. Extend with
+`container_tools/add_slides.py` or the recipes when the template has no family
+for a slide you need.
 
 ## 5. Check fidelity
 
@@ -118,8 +114,8 @@ template has no family for a slide you need.
 }
 ```
 
-Both print `passed`. With no requirements, the fidelity gate is a deliberate
-no-op pass — pass a requirements file or you have not checked anything.
+Both print `passed`. No requirements → deliberate no-op pass: pass a file or you
+have checked nothing.
 
 ## 6. Look at it
 
@@ -127,6 +123,5 @@ no-op pass — pass a requirements file or you have not checked anything.
 "<python>" "<skill>/container_tools/render_slides.py" --input starter.pptx --out-dir starter-preview
 ```
 
-Compare against the source slides. A filled placeholder that overflows, a title
-in the wrong family, or a panel over the corner logo is exactly what this step
-exists to catch.
+Compare with the source slides: this catches an overflowed placeholder, a title
+in the wrong family, a panel over the corner logo.

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

@@ -1,24 +1,24 @@
 ---
-description: Create, inspect, edit, recalculate, and verify Excel workbooks (.xlsx/.csv) using openpyxl recipes and the bundled Office helper CLI.
+description: Create, inspect, edit, recalculate, render, and verify Excel spreadsheets (.xlsx/.csv) with openpyxl recipes, formula patterns, and the bundled Office helper CLI.
 ---
 
 # Spreadsheets (.xlsx)
 
-A workbook is cells: each one holds a value, a format, and possibly a formula *string*. openpyxl writes all three and evaluates none of them, so a formula you just wrote has no cached result and `xlsx read` shows `=SUM(B2:B9)` where the user expects `1,950,400`. The calculation happens in an engine — the DSH LibreOffice via `xlsx recalc` (cross-platform), or whatever app the user opens the file in. Everything below follows from that: write values and formulas, then verify structure by reading back, then verify numbers by recalculating, then verify appearance by rendering.
+A cell holds a value, a format, and possibly a formula string. openpyxl writes all three and evaluates none: a new formula has no cached result, so `xlsx read` shows `=SUM(B2:B9)` where the user expects `1,950,400`. Only an engine calculates — `xlsx recalc` through the DSH LibreOffice kit (cross-platform), or the app the user opens the file in. Work in that order: write values and formulas, read back for structure, recalculate for numbers, render for appearance.
 
-| User job | What is really happening | Fast path |
+| User job | What is happening | Fast path |
 | --- | --- | --- |
-| Build a new workbook | Cells written top-left at A1; `=`-prefixed strings become formulas; styles are per-cell objects; sheets get names, widths, freeze panes, merges | `xlsx create` spec, `tasks/create-workbook.md` |
+| Build a new workbook | Cells written from A1; `=`-prefixed strings become formulas; styles are per-cell; sheets get names, widths, freeze panes, merges | `xlsx create` spec, `tasks/create-workbook.md` |
 | Change cells in an existing file | Only the cells you name change; a re-save can drop objects openpyxl does not model (pivots, foreign charts) | `container_tools/set_cells.py` and friends, `tasks/edit-workbook.md` |
-| The workbook is open in Excel/WPS and the user wants it changed live | The target is the window, not the file on disk: unsaved user edits are in play and a COM write is not transactional. **Windows only** — on macOS/Linux the live tool exits 3 with a remedy; edit the file instead | `../excel-live-control/SKILL.md` |
-| Inventory a file you did not write | Iterate sheets, used range, formulas vs values, merged ranges, conditional formats, defined names, charts | `container_tools/inspect_workbook.py` |
-| Compare two versions | Cell-by-cell walk with formula-aware, format-aware, structure-aware levels | `container_tools/diff_workbooks.py`, `tasks/diff-workbooks.md` |
-| Prove the numbers are real | Recalculate in Excel, then check every formula cell has a value, no error, no dangling sheet | `xlsx recalc` + `container_tools/recalc_gate.py`, `tasks/recalc-and-check.md` |
-| Format numbers, conditions, names, charts, tables | Number formats, conditional-formatting rules, defined names, native chart objects, Excel Tables | `recipes/*.md` (openpyxl patterns, runnable) |
+| Workbook open in Excel/WPS must change live | The target is the window, not the file: unsaved user edits are in play and a COM write is not transactional. **Windows only** — on macOS/Linux the live tool exits 3 with a remedy; edit the file instead | `../excel-live-control/SKILL.md` |
+| Inventory a file you did not write | Sheets, used range, formulas vs values, merged ranges, conditional formats, defined names, charts | `container_tools/inspect_workbook.py` |
+| Compare two versions | Cell-by-cell walk at formula-, format-, and structure-aware levels | `container_tools/diff_workbooks.py`, `tasks/diff-workbooks.md` |
+| Prove the numbers are real | Recalculate, then check every formula cell has a value, no error, no dangling sheet | `xlsx recalc` + `container_tools/recalc_gate.py`, `tasks/recalc-and-check.md` |
+| Format numbers, conditions, names, charts, tables | Number formats, conditional-formatting rules, defined names, native chart objects, Excel Tables | `recipes/*.md` (runnable openpyxl patterns) |
 | Answer a question about a file | Read values, not formulas; quote the cells you read | `tasks/analyze-workbook.md` |
 | Spreadsheet lives in Google Sheets | Not this runtime — see `routing/google-sheets.md` | — |
 
-Sheet and range semantics matter before any edit: `B4:D9` is a rectangle, `'Build'!E14` is a cross-sheet reference whose sheet name needs quotes when it contains spaces, and a merged range is one value plus a lot of emptiness. Number formats are display only — the stored value keeps full precision, so never round data to make it look right.
+Sheet and range semantics come before any edit: `B4:D9` is a rectangle, `'Build'!E14` is a cross-sheet reference whose sheet name needs quotes when it contains spaces, and a merged range is one value plus a lot of emptiness. Number formats are display only — the stored value keeps full precision, so never round data to make it look right.
 
 ## Before any file work
 
@@ -29,54 +29,47 @@ Sheet and range semantics matter before any edit: `B4:D9` is a rectangle, `'Buil
 
 ## 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 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.
+- Editing an existing file: never overwrite the original. Write `<original>-edited.<ext>` (or the 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.
+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; `requirement` is free-form natural language. Treat it as a change request, not editor state.
 
-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 xlsx the payload is `{ target, fileName, text: "", requirement, region, imageName, unmapped: true }`: no `page`, no `sheet`, no `range`. The preview client cannot resolve a cell from the drag and refuses to fake one. So:
-
-1. `read_image` the attachment named `imageName` — it is a screenshot of the area the user marked. Note visible headers, row labels, and values.
-2. Run `"<python>" "<cli>" xlsx read --input "<file>" --json-out "<dump>.json"` and match those values to sheets and A1 addresses; `container_tools/inspect_workbook.py` adds formulas, merged ranges, and names when the match is ambiguous.
-3. State the resolved sheet and range back to the user before editing ("`Pipeline!D2:D13`, the Amount column"), and ask if two sheets or columns match.
-4. Never convert region pixels into a cell address. Full recipe: `tasks/annotations.md` and `"<shared>/annotation-recipes.md"`.
+For xlsx the payload is `{ target, fileName, text: "", requirement, region, imageName, unmapped: true }`: no `page`, no `sheet`, no `range`, because the preview client cannot resolve a cell from the drag and refuses to fake one. So: `read_image` the attachment named `imageName`, match the visible values to sheets and A1 addresses with `"<python>" "<cli>" xlsx read --input "<file>" --json-out "<dump>.json"`, state the resolved sheet and range before editing ("`Pipeline!D2:D13`, the Amount column"), ask when two sheets or columns match, then apply the smallest edit that satisfies `requirement`, re-render, and confirm the region now looks right. Never convert region pixels into a cell address. When the payload cannot be mapped to a concrete object, do not guess silently — say what you could not locate. Full recipe: `tasks/annotations.md` and `"<shared>/annotation-recipes.md"`.
 
 ## Verify
 
 Three checks, in this order, after every mutation:
 
-1. **Structure and values.** `"<python>" "<cli>" xlsx read --input "<file>"` proves the cells you wrote are where you wrote them; `container_tools/inspect_workbook.py` proves charts, tables, conditional formats, names, and merges survived.
-2. **Numbers.** If any formula changed or was added, run `"<python>" "<cli>" xlsx recalc --input "<file>" --out "<file>"` and then `container_tools/recalc_gate.py --input "<file>"`. The kit recalculates on every platform; only when the kit itself is missing does the recalc fail, and `recalc_gate.py` then reports `unverified` — say that plainly instead of presenting an empty cache as a result.
-3. **Appearance.** `"<python>" "<cli>" xlsx render --input "<file>" --out-dir "<render-dir>"`, then `read_image` each PNG. Check titles and labels, `###` columns, clipped numbers, charts cut off by the print area, plots with no categories, legends naming `Series 1`, conditional formatting that never fired, and blank pages. The render goes through the DSH LibreOffice kit; when it is missing the command fails explicitly: report the file as structurally verified but visually unchecked, and offer to rebuild from a spec.
+1. **Structure and values.** `"<python>" "<cli>" xlsx read --input "<file>"` proves the cells you wrote are where you wrote them. `container_tools/inspect_workbook.py` proves charts, tables, conditional formats, names, and merges survived.
+2. **Numbers.** If a formula changed or was added, run `"<python>" "<cli>" xlsx recalc --input "<file>" --out "<file>"`, then `container_tools/recalc_gate.py --input "<file>"`. Recalc fails only when the kit is missing, and `recalc_gate.py` then reports `unverified` — say that plainly instead of presenting an empty cache as a result. Flags, exit codes, and what the gate reports: `tasks/recalc-and-check.md`.
+3. **Appearance.** `"<python>" "<cli>" xlsx render --input "<file>" --out-dir "<render-dir>"`, then `read_image` each PNG. Check titles and labels, `###` columns, clipped numbers, charts cut off by the print area, plots with no categories, legends naming `Series 1`, conditional formatting that never fired, and blank pages. When the LibreOffice kit is missing the command fails explicitly: report the file as structurally verified but visually unchecked, and offer to rebuild from a spec.
 
 Two or three render/fix passes are normal. If a defect survives three, say what still looks wrong.
 
 ## Mutation tools
 
-The CLI is read-only for `.xlsx`: `create`, `read`, `render`, `status`, `recalc` and nothing else. Every change to an existing workbook goes through these openpyxl tools. Each one reads `--input`, writes `<input>-edited.xlsx` unless you pass `--out`, prints one JSON object on stdout, and exits non-zero with a JSON `error` on stderr when it refuses.
+The CLI is read-only for `.xlsx`: `create`, `read`, `render`, `status`, `recalc`, and nothing else. Every change to an existing workbook goes through these openpyxl tools. Each reads `--input`, writes `<input>-edited.xlsx` unless you pass `--out`, prints one JSON object on stdout, and exits non-zero with a JSON `error` on stderr when it refuses.
 
-| Tool | Does | Does not |
-| --- | --- | --- |
-| `sheet_ops.py` | `--add NAME`, `--rename OLD=NEW`, `--delete NAME`, `--order "A,B,C"` | rename the formulas that point at a renamed sheet; deleting the last sheet is refused |
-| `set_cells.py` | `--sheet S --set B2=42 --set C3="=SUM(C2:C9)"`, or `--spec cells.json` | parse dates for you — write `2026-01-31` and format the cell, or pass a serial |
-| `append_rows.py` | `--sheet S --rows '[[...],[...]]'`, or `--rows-file rows.json` | extend an Excel Table, copy the row above's formula, or grow charts and conditional formats |
-| `style_cells.py` | `--sheet S --range A1:D1 --style '{"bold":true}'`, or `--spec styles.json` | autofit columns or restyle cells outside the range |
-| `add_chart.py` | `--sheet S --type line --data-min-col ... --cat-min-row ...`, or `--spec chart.json` | set axis number formats, series colours, or a legend position; a one-row data range is treated as one series of many points |
-| `add_image.py` | `--sheet S --path logo.png --anchor B2 [--width 480]` | update an embedded image when the file on disk changes |
+- `sheet_ops.py` — `--add NAME`, `--rename OLD=NEW`, `--delete NAME`, `--order "A,B,C"`. Renaming a sheet does not update the formulas that point at it; deleting the last sheet is refused.
+- `set_cells.py` — `--sheet S --set B2=42 --set C3="=SUM(C2:C9)"`, or `--spec cells.json`. It does not parse dates for you: write `2026-01-31` and format the cell, or pass a serial.
+- `append_rows.py` — `--sheet S --rows '[[...],[...]]'`, or `--rows-file rows.json`. It does not extend an Excel Table, copy the row above's formula, or grow charts and conditional formats.
+- `style_cells.py` — `--sheet S --range A1:D1 --style '{"bold":true}'`, or `--spec styles.json`. No autofit, and it will not restyle cells outside the range.
+- `add_chart.py` — `--sheet S --type line --data-min-col ... --cat-min-row ...`, or `--spec chart.json`. It cannot set axis number formats, series colours, or a legend position, and a one-row data range is treated as one series of many points.
+- `add_image.py` — `--sheet S --path logo.png --anchor B2 [--width 480]`. It cannot update an embedded image when the file on disk changes.
+
+Chain by naming outputs: `set_cells.py --input book.xlsx --out step1.xlsx`, then `style_cells.py --input step1.xlsx --out step2.xlsx`; without `--out` each tool writes `book-edited.xlsx` next to the input and the next step would read the unedited original.
 
-Chain them by naming the output: `set_cells.py --input book.xlsx --out step1.xlsx`, then `style_cells.py --input step1.xlsx --out step2.xlsx`. Without `--out` each tool writes `book-edited.xlsx` next to the input and the next step would read the unedited original.
+Values: numbers, booleans, `null`, and JSON arrays parse; anything else is text, and a leading `=` is stored as a formula. `--set B3=` stores an empty string, which is not a blank cell — leave a cell out of the assignment to keep it blank.
 
-Values: numbers, booleans, `null`, and JSON arrays parse; anything else is text, and a leading `=` is stored as a formula. `--set B3=` stores an empty string, which is not the same as a blank cell — leave a cell out of the assignment to keep it blank.
+Runnable invocations with real paths: `tasks/edit-workbook.md` `## Mutation tools`.
 
 ## Formulas you will write
 
-Write the formula text a person would type; openpyxl stores it verbatim and never evaluates it.
+Write the formula text a person would type. openpyxl stores it verbatim and never evaluates it.
 
 - Anchoring: `C8` moves when filled, `C$4` pins the row (a period header), `$A8` pins the column (an item label), `$B$3` pins one cell (a rate or case selector). `=SUMIFS(Amount,Month,C$4,Item,$A8)` is the shape a grid needs.
 - Aggregation: `SUM`, `SUMIFS`, `COUNTIFS`, `AVERAGEIFS`, `SUMPRODUCT` for quantity × rate pairs, `PRODUCT` for chained factors (it silently skips blanks, so a missing input looks valid).
@@ -85,7 +78,7 @@ Write the formula text a person would type; openpyxl stores it verbatim and neve
 - No `LET`, no dynamic arrays, no `LAMBDA`: the engines that read these files disagree on them.
 - Cross-sheet references quote the name: `='Build'!E14`, `='Case A'!$B$4`.
 
-After writing formulas, recalculate before anyone reads a number — see `## Verify`.
+Recalculate before anyone reads a number — see `## Verify`. Patterns and dates: `references/formula-patterns.md`.
 
 ## Tasks
 
@@ -107,8 +100,8 @@ Background: `references/workbook-structure.md` (tab roles and layout), `referenc
 
 ## Edit discipline
 
-An existing workbook is the reference: its structure, formula style, formats, and terminology are what the user expects to keep seeing. Change the cells the request names and the formulas those cells feed. Everything else — other sheets, pivot sources, shared formulas, named ranges, conditional formats, data validation, protection, hidden rows, freeze panes, chart contents — stays untouched unless the request or a real dependency forces it. Never flatten formulas to values because it is easier, never autofit whole sheets for a visual tweak, and never quietly repair errors the user did not ask about: list them and ask. Details and failure modes: `tasks/edit-workbook.md`.
+An existing workbook is the reference: its structure, formula style, formats, and terminology are what the user expects to keep seeing. Change the cells the request names and the formulas those cells feed. Everything else — other sheets, pivot sources, shared formulas, named ranges, conditional formats, data validation, protection, hidden rows, freeze panes, chart contents — stays untouched unless the request or a real dependency forces it. Never flatten formulas to values because it is easier, never autofit whole sheets for a visual tweak, and never quietly repair errors the user did not ask about: list them and ask. Failure modes: `tasks/edit-workbook.md`.
 
 ## Shared workflow
 
-Follow `"<shared>/common-workflow.md"` for the create-or-edit decision, the failure ladder, and the edit naming rule, and `"<shared>/annotation-recipes.md"` for the payload shapes the client sends.
+`"<shared>/common-workflow.md"` owns the create-or-edit decision, the failure ladder, and the edit naming rule. `"<shared>/annotation-recipes.md"` owns the payload shapes the client sends.