dsh-office-kit 0.2.0 → 0.3.0

package/assets/skills/office-spreadsheets/tasks/create-workbook.md

@@ -0,0 +1,66 @@
+# Create a workbook
+
+`"<python>" "<cli>" xlsx create --spec "<spec.json>" --out "<book.xlsx>"` writes one sheet per `sheets[]` entry, top-left at A1, and treats any string starting with `=` as a formula.
+
+## Spec keys (only these exist)
+
+```json
+{
+  "sheets": [{
+    "name": "Model",
+    "rows": [["Revenue (Q3 actual)", 1840000], ["Growth rate", 0.06]],
+    "formulas": { "B4": "=B2*(1+B3)" },
+    "styles": {
+      "A1": { "bold": true, "size": 16, "color": "FFFFFF", "fill": "1F3A5F", "align": "left" },
+      "B2:B3": { "number_format": "#,##0" }
+    },
+    "widths": { "A": 26, "B": 16 },
+    "row_heights": { "1": 24 },
+    "freeze": "A2",
+    "merged": ["A1:F1"],
+    "gridlines": false,
+    "charts": [{
+      "type": "column",
+      "title": "Q4 plan (USD)",
+      "anchor": "A16",
+      "height": 7,
+      "width": 14,
+      "data": { "min_col": 2, "min_row": 1, "max_col": 2, "max_row": 4 },
+      "categories": { "min_col": 1, "min_row": 2, "max_row": 4 }
+    }],
+    "images": [{ "path": "<absolute png path>", "anchor": "H2", "width": 240 }]
+  }]
+}
+```
+
+- `styles` values: `bold`, `italic`, `size`, `color`, `fill`, `number_format`, `align` (`left`/`center`/`right`, vertically centered). A range key styles every cell in it.
+- `formulas` is address → formula string; the leading `=` is required.
+- `charts[].data` and `.categories` use 1-based column/row indices on the same sheet, so build the label column before the value column and keep both over the same rows.
+- `merged` takes A1 strings. Merge only for presentation (one title across empty header cells); merged cells cannot be resized, sorted, or filled per cell, so keep data out of them.
+
+## Order of work
+
+1. Sketch the sheets as roles, not tabs: inputs, calculations, outputs, checks. A five-line model belongs on one sheet with labelled blocks.
+2. Put the number formats on the cells, not on a copy of the values. `#,##0` for currency-ish amounts, `0.0%` for percentages, `yyyy-mm-dd` for real dates.
+3. Write the calculation as visible steps (quantity × rate, opening + movements = closing) and link the output to the build rather than repeating the arithmetic.
+4. Add a chart only when it answers a comparison question the numbers alone answer slowly; see `references/charts.md`.
+5. Render and read the PNG, then recalc if formulas exist.
+
+## What needs more than the spec
+
+| Need | Route |
+| --- | --- |
+| Excel Table (filter buttons, banded style, structured references) | `recipes/data-tables.md` |
+| Conditional formatting, data bars, colour scales | `recipes/conditional-formats.md` |
+| Defined names used by formulas or validation | `recipes/named-ranges.md` |
+| Sparkline-style in-cell bars | `recipes/sparklines.md` |
+| Chart types or settings beyond bar/column/line/pie | `recipes/charts.md` |
+| Page setup, print area, tab colours, sheet protection | openpyxl snippet (`ws.page_setup`, `ws.print_area`, `ws.sheet_properties.tabColor`); see `references/style-guidelines.md` |
+
+## Pitfalls
+
+- Values written through the CLI keep their type: `1840000` is a number, `"1,840,000"` is text and will not sum. Format numbers, never pre-format them as strings.
+- A chart whose `max_row` is larger than the data plots empty points as zero, which reads as a collapse to the floor. Match the range to the data.
+- `anchor` is where the chart's top-left corner sits; a chart outside the print area gets cut off by `xlsx render`. Put it below or beside the data inside the printed range.
+- Dates must be real dates (`date(2026, 1, 31)` via a snippet, or Excel serial numbers), never `"Jan-26"` strings, or period filters fail silently.
+- Set the font family explicitly if the file will be opened on another machine; a missing Calibri falls back to a serif in some renderers and every column width shifts.

package/assets/skills/office-spreadsheets/tasks/diff-workbooks.md

@@ -0,0 +1,38 @@
+# Diff two workbooks
+
+```bash
+"<python>" "<skill>/container_tools/diff_workbooks.py" --before "<original.xlsx>" --after "<edited.xlsx>"
+```
+
+Exit code `0` means the files match at the requested level, `1` means differences (not a failure), `2` is a usage or read error. The report is JSON on stdout.
+
+## Options
+
+| Flag | Effect |
+| --- | --- |
+| `--no-formats` | Compare values and formulas only; ignore styling, number formats, widths |
+| `--sheet NAME` | Restrict to one sheet (repeatable) |
+| `--limit N` | Cap the cell-level changes listed per sheet (default 200); counts stay exact |
+
+## What it compares
+
+- **Structure** — sheet list and order, added/removed sheets, merged ranges, column widths, hidden state.
+- **Cells** — value and formula changes, reported as `{cell, before, after}` per sheet, with a count even when the list is truncated.
+- **Formatting** — number format, fill, font weight and colour, alignment; dropped by `--no-formats`.
+- **Objects** — Excel Table names and refs, defined names, chart counts and series, conditional-formatting rule sets.
+
+## Using it as an edit gate
+
+Run it as `--before original --after original-edited` immediately after any edit, and read the "changed" sections as the diff you are about to describe to the user:
+
+1. Anything under cells that you did not intend to touch is collateral damage — revert and redo with a narrower edit.
+2. A sheet, table, name, or chart in "removed" is a lost object; rebuild it from `recipes/charts.md` / `recipes/named-ranges.md` before presenting.
+3. Formatting-only differences across many rows usually mean a style object was reapplied to a range instead of a cell.
+
+Diffing a file against itself is a useful sanity check that the tool and the file load cleanly: it should return `identical: true`.
+
+## Limits
+
+- Cached formula results are not compared; use `recalc_gate.py` for that.
+- Pivot caches and VBA are compared by part presence, not content.
+- Chart internals are compared by count and series references; a restyled chart of the same data reads as unchanged.

package/assets/skills/office-spreadsheets/tasks/edit-workbook.md

@@ -0,0 +1,69 @@
+# Edit an existing workbook
+
+The file is the specification. Read its conventions before writing a cell, then make the smallest change that satisfies the request.
+
+## Procedure
+
+1. `"<python>" "<cli>" xlsx read --input "<book.xlsx>" --json-out "<dump>.json"` — every sheet, its used range, and its formulas.
+2. `"<python>" "<skill>/container_tools/inspect_workbook.py" --input "<book.xlsx>"` — what the read verb does not show: merged ranges, conditional formatting, defined names, Excel Tables, charts and their series, freeze panes, protections. It prints JSON; `--no-values` skips the second load that looks for cached results.
+3. Render the sheets you are about to touch and look at them: `xlsx render`, then `read_image`. Match the surrounding format, not your personal default.
+4. Apply the edit with the narrowest tool that fits (below), or with an openpyxl snippet when the change is not one of those shapes.
+5. Read back and re-check structure, recalculate if formulas changed, render again, compare.
+
+## Mutation tools
+
+There is no `xlsx edit` verb. Each tool loads the workbook, changes only what you name, and saves a copy.
+
+| Change | Command |
+| --- | --- |
+| Write values and formulas | `set_cells.py --input "<book.xlsx>" --out "<step1.xlsx>" --sheet Model --set B3=0.07 --set D9="=SUM(D2:D8)"` |
+| Reuse a file of assignments | `set_cells.py --input "<book.xlsx>" --spec "<cells.json>"` |
+| Format cells | `style_cells.py --input "<step1.xlsx>" --out "<step2.xlsx>" --sheet Model --range B11:B14 --style '{"number_format":"#,##0"}'` |
+| Append records | `append_rows.py --input "<book.xlsx>" --sheet Pipeline --rows '[["Delta Supply","R. Osei","Proposal",98000,0.4]]'` |
+| Add, rename, delete, reorder sheets | `sheet_ops.py --input "<book.xlsx>" --add Checks` / `--rename Sheet1=Assumptions` / `--delete Scratch` / `--order "Outputs,Assumptions,Build"` |
+| Add a native chart | `add_chart.py --input "<book.xlsx>" --sheet Trend --type line --title "Monthly revenue (USD)" --anchor A6 --data-min-col 2 --data-min-row 3 --data-max-col 13 --data-max-row 3 --cat-min-row 2 --cat-max-row 2` |
+| Embed an image | `add_image.py --input "<book.xlsx>" --sheet Cover --path logo.png --anchor B2 --width 320` |
+
+Each tool writes `<input>-edited.xlsx` unless you pass `--out`, so chain by naming outputs, never by editing the file you just read and forgetting the step in between.
+
+`cells.json` is `{"sheet": "Model", "cells": {"B3": 0.07, "D9": "=SUM(D2:D8)"}}` or a list of those. `styles.json` is `{"sheet": "Model", "styles": {"A11:B11": {"bold": true}, "C11:C14": {"number_format": "0.0%"}}}`.
+
+Two tool limits are deliberate: `append_rows.py` does not extend an Excel Table, copy the formula from the row above, or grow a chart — do those with a snippet from `recipes/data-tables.md` and `recipes/charts.md`, or the new rows will sit outside the table and the chart will stop at the old last row. `add_chart.py` treats a one-row data range as one series of many points (which is what a monthly row means) but cannot set axis number formats or series colours; fix those in the same snippet.
+
+## What must survive an edit
+
+| Thing | Why it breaks | Guard |
+| --- | --- | --- |
+| Formula cells outside the edit | openpyxl keeps the formula text, so they survive — unless something flattens them | Never write computed results over formulas |
+| Pivot tables | openpyxl does not model pivots; a save-backed rewrite can drop the cache | Inspect before/after, or edit with a snippet that touches only cells |
+| Excel Tables (`ListObject`) | Rows appended below a table are outside it | Extend `table.ref` when you add rows |
+| Shared formulas and array formulas | Re-saving can materialise or drop them | If the area uses them, edit only the cells asked and diff after |
+| Named ranges, conditional formats, validation | Not always round-tripped by third-party writers | Confirm with `inspect_workbook.py` after the save |
+| Charts, images, sparklines | Anchored objects; some are dropped on re-save | Count them before and after; rebuild from `recipes/charts.md` if lost |
+| Freeze panes, hidden/grouped rows, tab colours, protection | Structural metadata | Diff structure before and after |
+| Sheet names used in formulas | Renaming breaks every reference | Prefer adding a sheet over renaming one |
+
+New conditional formatting that covers a whole table must extend to the rows you add, or the new rows look unfinished. A dynamic chart range whose source grows needs the same extension, or the chart stops at the old last row.
+
+## Cells: the smallest change
+
+- Write to the sheet and address you resolved; never "the first empty row" of an unnamed sheet.
+- A text edit changes run-level text only in a cell; the format stays unless the request names it.
+- A number-format change is a format change, not a value change: do not replace `0.0649` with `6.5%` text.
+- Do not autofit every column or restyle a table to fix one clipped cell. Widen the column, or shrink the font only for that block.
+- Do not add spacer rows, helper sheets, or "Notes" tabs unless the request needs them.
+
+## Errors you did not cause
+
+If `xlsx read` shows `#REF!`, `#DIV/0!`, or a formula pointing at a sheet that no longer exists, it is pre-existing. Summarise where it is and ask before touching it — repairing it silently changes numbers the user may already have reported.
+
+## Verify
+
+```bash
+"<python>" "<cli>" xlsx recalc --input "<book-edited.xlsx>" --out "<book-edited.xlsx>"
+"<python>" "<skill>/container_tools/recalc_gate.py" --input "<book-edited.xlsx>"
+"<python>" "<skill>/container_tools/diff_workbooks.py" --before "<book.xlsx>" --after "<book-edited.xlsx>"
+"<python>" "<cli>" xlsx render --input "<book-edited.xlsx>" --out-dir "<render-dir>"
+```
+
+The diff is the closest thing to a guarantee that nothing else moved: it reports changed cells and formulas, changed formatting unless you pass `--no-formats`, and structure changes (sheets, merges, widths, tables, charts, defined names). Exit code `1` means differences — not failure. Use `--sheet` to narrow and `--limit` to cap the per-sheet cell list.

package/assets/skills/office-spreadsheets/tasks/inspect-workbook.md

@@ -0,0 +1,38 @@
+# Inspect a workbook
+
+Two readers, different jobs:
+
+- `"<python>" "<cli>" xlsx read --input "<book.xlsx>" [--data-only]` — the cell values, per sheet, as arrays without coordinates. `--data-only` returns cached results instead of formula text.
+- `"<python>" "<skill>/container_tools/inspect_workbook.py" --input "<book.xlsx>"` — the structure around the cells: formats that govern how they read, objects that live beside them, and whether the formulas were ever computed.
+
+Run both before editing, and after editing to prove nothing was lost.
+
+## What the inspector reports
+
+| Field | Reading it |
+| --- | --- |
+| `workbook.sheets`, `active_sheet` | Tab order and what opens first; order carries meaning (outputs lead) |
+| `workbook.defined_names` | `name`, `refers_to`, `scope` (`workbook` or a sheet), `hidden`. A broken `refers_to` (`#REF!`) breaks every formula using the name |
+| `workbook.calc_mode`, `full_calc_on_load`, `date_system` | `manual` calc mode means saved values can be stale; `1904` date system shifts every date by four years |
+| `container.*` | Counts of tables, pivot tables/caches, charts, drawings, images, comment parts, external links, VBA, shared strings — the objects a rewrite can silently drop |
+| `sheets[].dimensions`, `max_row`, `max_column` | The used range: what the file *thinks* has content, including formatting far from the data |
+| `sheets[].print_area`, `freeze_panes`, `gridlines` | Layout choices a render will honour |
+| `sheets[].merged` | Merged ranges; a value lives in the top-left cell only |
+| `sheets[].tables` | Excel Table names and refs; rows appended below a `ref` land outside the table |
+| `sheets[].charts[].anchor`, `.kind`, `.series` | Where a chart sits and what it plots; `anchor` outside `print_area` means the chart is cut off when printed |
+| `sheets[].conditional_formats[].rules` | `type` (`cellIs`, `colorScale`, `dataBar`, `expression`), `operator`, `formula`, `priority`. A rule whose range stops short of new rows silently stops applying |
+| `sheets[].data_validations` | Dropdowns and constraints an edit must preserve |
+| `sheets[].hidden_rows`, `hidden_columns` | Content the user deliberately folded away |
+| `sheets[].formulas.shared`, `.array`, `.data_tables` | Non-trivial formula storage; re-saving can materialise or drop these |
+| `sheets[].values.cached`, `.missing`, `.errors` | How many formula cells carry a cached result, carry none, or carry an error value |
+
+`--no-values` skips the second load that reads cached results (faster on big files, blind to whether formulas were ever computed). `--sample N` sets how many formula samples per sheet are printed (default 5).
+
+## How to read it
+
+- `values.missing` equal to `formulas.count` means nothing has ever calculated this file. Do not quote any formula result; recalculate first (`tasks/recalc-and-check.md`).
+- `values.errors` non-empty is pre-existing damage (or a deliberately `#N/A` sentinel). Report it, do not fix it unasked.
+- `container.pivot_tables > 0` or `has_vba_project: true` means a plain openpyxl rewrite is risky: back up, change the fewest cells possible, and re-inspect after saving.
+- `formulas.shared > 0` means a spreadsheet app wrote the file; copy an existing formula down rather than inventing a new pattern.
+- A sheet with a huge `dimensions` and few real cells is a formatting artefact (fill applied to whole columns). Do not "clean" it; note it if the user asks why the file is slow.
+- `print_area` and chart `anchor` are the two fields that explain most render surprises: charts clipped at the page edge, or entire data blocks missing from a PDF because they fall outside the print range.

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

@@ -0,0 +1,57 @@
+# 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.
+
+```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 a calculation engine on this host — Microsoft Excel or WPS
+  Spreadsheets, driven over COM. Without one 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".
+
+## What the gate flags
+
+| Flag | Meaning | Action |
+| --- | --- | --- |
+| `errors` | Cached value is `#REF!`, `#DIV/0!`, `#NAME?`, `#VALUE!`, `#N/A`, … | Fix the formula or the input; do not paint the cell red and move on |
+| `missing` | Formula cell with no cached value | Either recalc did not reach it or it was written after the recalc |
+| `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.
+
+## 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.
+- 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.
+
+## 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.

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

@@ -0,0 +1,252 @@
+# Annotation recipes
+
+The user may reply to a rendered preview with an `office-annotations` block: 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.
+
+| Format | Item keys | `page` means |
+| --- | --- | --- |
+| pdf | `target`, `fileName`, `page`, `text`, `requirement`, `region`, `imageName` | 1-based page of the PDF itself |
+| docx | `target`, `fileName`, `page`, `text`, `requirement`, `region` | page of the rendered PDF preview, not a Word page |
+| pptx | `target`, `fileName`, `page`, `text`, `requirement`, `region` | rendered PDF page; one slide per page, so page N is slide N |
+| xlsx | `target`, `fileName`, `text: ""`, `requirement`, `region`, `imageName`, `unmapped: true` | no `page`, no `sheet`, no `range` |
+
+- `target` and `fileName` name the file.
+- `region` is normalised 0–1 against the rendered preview page the user drew on.
+- `requirement` is natural language. Read it as a change request.
+- `text` is the words under the mark. For docx and pdf it is stronger evidence
+  than `region`; for xlsx it is always empty.
+- `imageName` marks a location screenshot that arrived as a normal image
+  attachment.
+
+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.
+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.
+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.
+
+## 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:
+
+- `"<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:
+
+```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,
+                    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)))
+```
+
+Apply the edit and write `<original>-edited.docx`:
+
+```json
+{
+  "replace": [{
+    "find": "Revenue grew 18.4% year over year.",
+    "replace": "Revenue grew 19% year over year."
+  }]
+}
+```
+
+```bash
+"<python>" "<cli>" docx edit --input "report.docx" --spec "edit.json" --out "report-edited.docx"
+```
+
+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.
+
+## 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)))
+```
+
+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.
+
+Choose the edit that the helper actually supports:
+
+- Metadata, rotation, page order, merge, page removal → `pdf edit`:
+
+  ```json
+  { "metadata": { "title": "Field report (revised)" } }
+  ```
+
+  ```bash
+  "<python>" "<cli>" pdf edit --input "report.pdf" --spec "edit.json" --out "report-edited.pdf"
+  ```
+
+- 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.
+
+Verify with `<cli> pdf render --input "report-edited.pdf" --out-dir "render"` and
+`read_image render/page-1.png`. `pdf render` uses PyMuPDF and works without
+LibreOffice or Office, 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.
+
+```python
+import sys
+from pptx import Presentation
+prs = Presentation(sys.argv[1])
+slide_no, l, t, w, h = int(sys.argv[2]), *map(float, sys.argv[3:7])
+sw, sh = prs.slide_width, prs.slide_height
+for shape in prs.slides[slide_no - 1].shapes:
+    x0, y0 = (shape.left or 0) / sw, (shape.top or 0) / sh
+    x1, y1 = x0 + (shape.width or 0) / sw, y0 + (shape.height or 0) / sh
+    if x1 > l and x0 < l + w and y1 > t and y0 < t + h and shape.has_text_frame:
+        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.
+
+Apply with the run-level replacement:
+
+```json
+{ "replace": [{ "find": "Renewal 92%", "replace": "Renewal 94%" }] }
+```
+
+```bash
+"<python>" "<cli>" pptx edit --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.
+
+## 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:
+
+   ```python
+   import json, sys
+   from openpyxl.utils import get_column_letter
+   data = json.load(open(sys.argv[1], encoding="utf-8"))
+   needle = sys.argv[2]
+   for sheet in data["sheets"]:
+       for r, row in enumerate(sheet["rows"], start=1):
+           for c, value in enumerate(row, start=1):
+               if isinstance(value, str) and needle in value:
+                   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" } } }
+     ]
+   }
+   ```
+
+   ```bash
+   "<python>" "<cli>" xlsx edit --input "book.xlsx" --spec "edit.json" --out "book-edited.xlsx"
+   ```
+
+   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.
+
+Forbidden, because both produce plausible-looking edits in the wrong place:
+
+- converting `region` pixels into a cell address — the spreadsheet preview has
+  its own zoom and scroll;
+- naming a sheet the screenshot does not show or `xlsx read` cannot match.
+
+Visual confirmation needs `xlsx render`, which requires LibreOffice or Office;
+without one, say the change is verified structurally but not visually. Formula
+results stay uncalculated unless `xlsx recalc` runs on Windows with Microsoft
+Excel; do not present openpyxl's empty cache as a computed value.
+
+## When to stop and ask
+
+Ask one short question, listing what you did find, when:
+
+- the region covers text that exists 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.