dsh-office-kit 0.4.1 → 0.4.3

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 | `../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.

package/assets/skills/office-spreadsheets/recipes/charts.md

@@ -1,8 +1,6 @@
 # Native charts
 
-A native chart is an object bound to cell ranges: the numbers stay in cells, the
-chart reads them, and editing a cell moves the bar. That is the whole reason to
-add one instead of pasting an image.
+A native chart is an object bound to cell ranges: the numbers stay in cells, the chart reads them, and editing a cell moves the bar. That is the whole reason to add one instead of pasting an image.
 
 ```python
 import sys
@@ -30,37 +28,21 @@ wb.save(sys.argv[2])
 
 ## Orientation is the bug people hit
 
-A one-row source is **one series of many points**, not many series of one point.
-`Reference` cannot express that; `add_data(..., from_rows=True)` can. Without it
-a monthly row becomes twelve invisible one-point series and the chart renders
-blank. The mirror case is a one-column source added with `from_rows=True`: you
-get one series per cell row, so only pass it when the data really is row-wise.
+A one-row source is **one series of many points**, not many series of one point. `Reference` cannot express that; `add_data(..., from_rows=True)` can. Without it a monthly row becomes twelve invisible one-point series and the chart renders blank. The mirror case is a one-column source added with `from_rows=True`: you get one series per cell row, so pass it only when the data really is row-wise.
 
 ## What the helper CLI gives you
 
-`xlsx create` accepts `charts[]` with `type`, `title`, `anchor`,
-`height`/`width`, `data {min_col,min_row,max_col,max_row,titles_from_data}` and
-`categories`. `container_tools/add_chart.py` adds the same chart to an existing
-file and handles the row-oriented case. Neither sets axis number formats, series
-colours, legend position, data labels, or gap width — if the chart needs those,
-use a snippet like the one above.
+`xlsx create` accepts `charts[]` with `type`, `title`, `anchor`, `height`/`width`, `data {min_col,min_row,max_col,max_row,titles_from_data}` and `categories`. `container_tools/add_chart.py` adds the same chart to an existing file and handles the row-oriented case. Neither sets axis number formats, series colours, legend position, data labels, or gap width — if the chart needs those, use a snippet like the one above.
 
 ## Checks before you present
 
 - Series count matches the intent (one line per series, not one per point).
 - Categories are labels, not values and not an empty axis with `1, 2, 3, …`.
-- Bar, column, and area axes start at zero; line and scatter may narrow the
-  range, but the scale must be visible and stated.
-- No default legend on a single series; name each series in `titles_from_data`
-  or the legend reads `Series 1`.
-- Axis number formats are set on the chart, not inherited from cells — a source
-  column formatted as `0.0%` does not format the axis.
-- The chart sits near its data, over empty cells, and is not clipped by the
-  print area when the sheet is printed.
+- Bar, column, and area axes start at zero; line and scatter may narrow the range, but the scale must be visible and stated.
+- No default legend on a single series; name each series in `titles_from_data` or the legend reads `Series 1`.
+- Axis number formats are set on the chart, not inherited from cells — a source column formatted as `0.0%` does not format the axis.
+- The chart sits near its data, over empty cells, and is not clipped by the print area when the sheet is printed.
 
 ## Editing a chart in an existing file
 
-Read the object first (`inspect_workbook.py` lists type, anchor, and series
-refs), change the smallest property, and re-render. Moving a chart a few cells is
-fine; rebuilding it with different styling when the user asked for one number to
-be added is not.
+Read the object first (`inspect_workbook.py` lists type, anchor, and series refs), change the smallest property, and re-render. Moving a chart a few cells is fine; rebuilding it with different styling when the user asked for one number to be added is not.

package/assets/skills/office-spreadsheets/recipes/conditional-formats.md

@@ -1,9 +1,6 @@
 # Conditional formats
 
-Conditional formatting paints a cell from a rule, not from a value. The rule is
-stored separately from the cell format, so a cell can look red while its stored
-fill stays default — and a reader who copies the value out gets the number, not
-the colour.
+Conditional formatting paints a cell from a rule, not from a value. The rule is stored separately from the cell format, so a cell can look red while its stored fill stays default — and a reader who copies the value out gets the number, not the colour.
 
 ```python
 import sys
@@ -39,31 +36,17 @@ ws.conditional_formatting.add(
 wb.save(sys.argv[2])
 ```
 
-- `ColorScaleRule`/`DataBarRule` take a range, not a cell; one rule covers the
-  rectangle and scales against the values inside it.
-- `CellIsRule` compares one cell: `operator` in `lessThan`, `greaterThan`,
-  `between`, `equal`, `notEqual`, …
-- `FormulaRule` evaluates a formula with the range's **top-left** cell, so write
-  the reference for that cell (`$F2` with row relative) and Excel fills the rest.
-- A whole-column range (`D:D`) is cheap to write and slow to render; bound the
-  range to the current data (`D2:D13`) and extend it when rows are added.
-- Rules stack in priority order; later rules win only when the earlier ones do
-  not match. `stopIfTrue=True` ends the chain — use it when a second rule must
-  not repaint an already-flagged cell.
-- Do not also set a static fill on the same cells: the static fill shows through
-  where no rule matches and the sheet looks half-formatted.
+- `ColorScaleRule`/`DataBarRule` take a range, not a cell; one rule covers the rectangle and scales against the values inside it.
+- `CellIsRule` compares one cell: `operator` in `lessThan`, `greaterThan`, `between`, `equal`, `notEqual`, …
+- `FormulaRule` evaluates a formula with the range's **top-left** cell, so write the reference for that cell (`$F2` with row relative) and Excel fills the rest.
+- A whole-column range (`D:D`) is cheap to write and slow to render; bound the range to the current data (`D2:D13`) and extend it when rows are added.
+- Rules stack in priority order; later rules win only when the earlier ones do not match. `stopIfTrue=True` ends the chain — use it when a second rule must not repaint an already-flagged cell.
+- Do not also set a static fill on the same cells: the static fill shows through where no rule matches and the sheet looks half-formatted.
 
 ## Editing an existing file
 
-Replace a rule, do not add a near-duplicate: iterate
-`ws.conditional_formatting` and rebuild the collection for that range. Two rules
-covering `D2:D13` with slightly different thresholds give a result nobody can
-explain. Keep the rule count per sheet small — a dashboard with forty rules is a
-compatibility minefield in other engines.
+Replace a rule; do not add a near-duplicate. Iterate `ws.conditional_formatting` and rebuild the collection for that range — two rules covering `D2:D13` with slightly different thresholds give a result nobody can explain. Keep the rule count per sheet small: a dashboard with forty rules is a compatibility minefield in other engines.
 
 ## Verify
 
-Read the file back with `container_tools/inspect_workbook.py`; it lists each
-range and rule type. Then render and look: a data bar that never appears is
-usually a range that does not overlap the data, and a rule that fires on the
-wrong cells is almost always an absolute/relative mistake in `FormulaRule`.
+Read the file back with `container_tools/inspect_workbook.py`; it lists each range and rule type. Then render and look: a data bar that never appears is usually a range that does not overlap the data, and a rule that fires on the wrong cells is almost always an absolute/relative mistake in `FormulaRule`.

package/assets/skills/office-spreadsheets/recipes/data-tables.md

@@ -1,10 +1,6 @@
 # Data tables (Excel Tables)
 
-An Excel Table (`ListObject`) is the object behind `Insert > Table`: a name, a
-structured reference, banded rows, an optional totals row, and header filters.
-It is not a pivot table and not a formatted range. Use it when the user asks for
-a table, when a filter row helps, or when formulas should read
-`Sales[Amount]` instead of `$D$2:$D$900`.
+An Excel Table (`ListObject`) is the object behind `Insert > Table`: a name, a structured reference, banded rows, an optional totals row, and header filters. It is not a pivot table and not a formatted range. Use it when the user asks for a table, when a filter row helps, or when formulas should read `Sales[Amount]` instead of `$D$2:$D$900`.
 
 ```python
 import sys
@@ -23,19 +19,14 @@ wb.save(sys.argv[2])
 
 Rules that survive contact with the user:
 
-- `displayName` has no spaces, no hyphens, and must be unique in the workbook — it
-  becomes the structured reference name (`PipelineTable[Amount]`).
-- `ref` must start at the header row and match the real data rectangle. A table
-  whose `ref` is off by one row shows a phantom header and breaks the filter.
+- `displayName` has no spaces, no hyphens, and must be unique in the workbook — it becomes the structured reference name (`PipelineTable[Amount]`).
+- `ref` must start at the header row and match the real data rectangle. A table whose `ref` is off by one row shows a phantom header and breaks the filter.
 - One table per rectangle, one header row, no merged cells inside it.
-- Give it a style from `TableStyleLight*`/`Medium*`/`Dark*`; a bare table with no
-  style looks like an unstyled range and the user asks why the stripes went away.
+- Give it a style from `TableStyleLight*`/`Medium*`/`Dark*`; a bare table with no style looks like an unstyled range and the user asks why the stripes went away.
 
 ## Appending rows to a table
 
-Rows written below the last table row are outside the table until you widen
-`ref`. Widen it in the same pass, or the new records will not filter, will not
-band, and structured references will not see them.
+Rows written below the last table row are outside the table until you widen `ref`. Widen it in the same pass, or the new records will not filter, will not band, and structured references will not see them.
 
 ```python
 table = ws.tables["PipelineTable"]
@@ -44,15 +35,8 @@ new_last = first_row + added
 table.ref = f"A1:G{new_last}"          # same columns, one row longer
 ```
 
-Copy the format and any formula from the previous row (`ws.cell(r, c)._style =
-ws.cell(r - 1, c)._style`) before widening, so the new row does not appear as a
-plain block inside a banded table.
+Copy the format and any formula from the previous row (`ws.cell(r, c)._style = ws.cell(r - 1, c)._style`) before widening, so the new row does not appear as a plain block inside a banded table.
 
 ## Totals row
 
-`table.totalsRowCount = 1` declares a totals row, and `totalsRowFunction` on a
-column sets `sum`, `count`, `average`, `min`, `max`, `stdDev`, or `var`. The row
-below the last data row must exist and hold the header labels Excel expects; a
-totals row declared without that row renders oddly in some engines. If the user
-only wants a bold total line under a table, a formula row outside the table is
-simpler and less fragile.
+`table.totalsRowCount = 1` declares a totals row, and `totalsRowFunction` on a column sets `sum`, `count`, `average`, `min`, `max`, `stdDev`, or `var`. The row below the last data row must exist and hold the header labels Excel expects; a totals row declared without that row renders oddly in some engines. If the user only wants a bold total line under a table, a formula row outside the table is simpler and less fragile.

package/assets/skills/office-spreadsheets/recipes/named-ranges.md

@@ -1,8 +1,6 @@
 # Named ranges
 
-A defined name is a saved reference with a readable name: `Q4Growth` instead of
-`Model!$B$6`. Formulas that use names survive row and column insertion, and the
-user can select the name box instead of hunting for a cell.
+A defined name is a saved reference with a readable name: `Q4Growth` instead of `Model!$B$6`. Formulas that use names survive row and column insertion, and the user can select the name box instead of hunting for a cell.
 
 ```python
 import sys
@@ -15,27 +13,16 @@ wb.defined_names["PlanRevenue"] = DefinedName("PlanRevenue", attr_text="Model!$B
 wb.save(sys.argv[2])
 ```
 
-- The name must be a legal identifier: letters, digits, underscore, not a cell
-  address (`Q4` alone is a column, so it is refused).
-- `attr_text` is a full sheet reference; quote sheet names with spaces:
-  `'Case A'!$B$4`.
-- Workbook-level names live in `wb.defined_names`. To scope a name to one sheet,
-  put it on the worksheet: `wb["Model"].defined_names["Rate"] = ...` — the same
-  name can then mean different cells on different sheets, which confuses readers
-  unless the workbook already works that way.
-- Read the existing names with `container_tools/inspect_workbook.py` before
-  adding one; a duplicate name is a repair prompt in Excel.
-- Never point a name at a range whose size changes (`A2:A900`) unless the sheet
-  really ends there; prefer the exact used range, or a table reference.
+- The name must be a legal identifier: letters, digits, underscore, not a cell address (`Q4` alone is a column, so it is refused).
+- `attr_text` is a full sheet reference; quote sheet names with spaces: `'Case A'!$B$4`.
+- Workbook-level names live in `wb.defined_names`. To scope a name to one sheet, put it on the worksheet: `wb["Model"].defined_names["Rate"] = ...` — the same name can then mean different cells on different sheets, which confuses readers unless the workbook already works that way.
+- Read the existing names with `container_tools/inspect_workbook.py` before adding one; a duplicate name is a repair prompt in Excel.
+- Never point a name at a range whose size changes (`A2:A900`) unless the sheet really ends there; prefer the exact used range, or a table reference.
 
 ## Using names in formulas
 
-`=PlanRevenue*Q4Growth` is more readable than `=Model!$B$11*Model!$B$6`, and it
-does not break when a row is inserted. Paste the formula text exactly as the user
-would type it; openpyxl never resolves the name.
+`=PlanRevenue*Q4Growth` is more readable than `=Model!$B$11*Model!$B$6`, and it does not break when a row is inserted. Paste the formula text exactly as the user would type it; openpyxl never resolves the name.
 
 ## Removing a name
 
-Deleting a name leaves every formula that used it as `#NAME?`. Find the users
-first (formula text is visible in `inspect_workbook.py` output and
-`xlsx read`), then delete, then recalculate and check the gate.
+Deleting a name leaves every formula that used it as `#NAME?`. Find the users first (formula text is visible in `inspect_workbook.py` output and `xlsx read`), then delete, then recalculate and check the gate.