dsh-office-kit 0.2.0 → 0.3.1

package/CAPABILITY.md

@@ -1,75 +1,154 @@
 # Capability report
 
-This file records what the plugin actually does, how each capability maps from the original skills, what was verified, and what remains unsupported. It is intentionally conservative: a feature is listed as supported only after a working command path and a check exist.
-
-## Capability trace
-
-| User capability | Original mechanism | DSH execution chain | Acceptance | State |
-| --- | --- | --- | --- | --- |
-| Create a DOCX report | `documents` skill; Python OOXML scripts; `mark_artifact_operation_started.mjs` | `/documents` chip → `office-documents` skill → `office_status` → `office_cli.py docx create/edit` (python-docx, OMML) → Word/LibreOffice render → PNG inspection | Create with headings, lists, table, image, equation, header/footer; read back counts; edit text and append section; equation survives; rendered page inspected | Supported |
-| Read a DOCX | Same skill | `docx read` → JSON counts/text/tables/images | Counts and text match the created document | Supported |
-| Create a PDF | `pdf` skill; reportlab/pdfplumber/pypdf | `/pdf` chip → `office-pdf` skill → `office_cli.py pdf create/read/edit/render` | Chinese text embeds with registered CJK font; read extracts text; metadata edit; PyMuPDF render inspected | Supported |
-| Inspect a PDF | Same | `pdf read` → page count, text, metadata, form fields | Page count and Chinese/English text extracted | Supported |
-| Edit a PDF | Same | `pdf edit` → metadata, rotate, merge, remove pages | Metadata edit and read-back verified | Supported |
-| Create/edit a PPTX | `presentations` skill; `@oai/artifact-tool` | `/presentations` chip → `office-presentations` skill → `office_cli.py pptx create/edit` (python-pptx) → PowerPoint/LibreOffice render | Three slides with bullets, table, chart, image; edit text and append a slide; four rendered pages inspected; layout overlap fixed with explicit coordinates | Supported, with a different authoring engine than the original |
-| Create/edit an XLSX | `spreadsheets` skill; `@oai/artifact-tool` | `/spreadsheets` chip → `office-spreadsheets` skill → `office_cli.py xlsx create/edit/recalc` (openpyxl + Excel COM) | Formulas, styles, widths, frozen panes, chart; edit cells/append rows; Excel recalculation persists cached values (`40`, `58`, `228`); data-only read confirms | Supported, with a different authoring engine than the original |
-| Render for visual QA | Original render helpers / artifact tool | `render` → Microsoft Office COM (Word/PowerPoint/Excel) or LibreOffice headless; PyMuPDF for PDF | DOCX page, PPTX pages, PDF page rendered and inspected | Supported when a renderer exists; explicit error otherwise |
-| `/` menu with names and icons | Original skill menu (not `InputTrigger`) | Public `ctx.inputTriggers` source named `office`; four candidates with Gravity UI Icons SVGs and locale labels | Typecheck/build; not yet exercised in a running DSH window | Implemented, GUI interaction unverified |
-| Enter → reference chip | Original artifact reference | `onPick` returns `ReferenceInsert`; host `codec` persists `/documents` and serializes a skill instruction | Build/typecheck; chip persistence is the documented public contract, not live-tested | Implemented, GUI interaction unverified |
-| Chip preview | Original skill preview | `openReference` maps feature id → skill name → `SKILL.md` path → `sidebarRight.openResource` | Code path implemented; GUI unverified | Implemented, GUI unverified |
-| Python setup | Original bundled runtime | `postinstall.mjs` detect/download/verify/install/venv/pip/import check/config/PATH | Auto-install path not run (a working Python already existed); venv creation, dependency install, import verification, config write, idempotent rerun all verified | Supported; installer download path unverified in this environment |
-
-## Dependency mapping
-
-| Original dependency | DSH replacement | Notes |
-| --- | --- | --- |
-| `load_workspace_dependencies` | `office_status` + absolute paths embedded in each skill body | No hidden workspace loader; the host verifies the interpreter and packages. |
-| `mark_artifact_operation_started.mjs` | None | It only marked artifact sessions in the original runtime; DSH has no equivalent and the CLI does not pretend to. |
-| `@oai/artifact-tool` (PPTX/XLSX) | `python-pptx`, `openpyxl` | Different API and some different capabilities; see limits. |
-| Google Drive/Slides/Sheets plugins | None | Remote editing is explicitly unsupported, not silently replaced by local files. |
-| Original render helpers | Microsoft Office COM or LibreOffice headless; PyMuPDF | Renderer availability is reported by `office_status`. |
-| Original `agents/openai.yaml` manifests | DSH skill frontmatter + `ctx.skills.registerProvider` | The four DSH skills live in `assets/skills`. |
-
-## Python and renderer environment
-
-- Python: 3.12.12 in `%LOCALAPPDATA%\dsh-office-kit\venv`, created by `postinstall.mjs` from an existing CPython 3.12.12.
-- Installed and import-verified: python-docx 1.2.0, openpyxl 3.1.5, python-pptx 1.0.2, pypdf 6.21.1, reportlab 4.5.1, pdfplumber 0.11.9, PyMuPDF 1.28.2, Pillow 11.3.0, latex2mathml 3.81.1, mathml2omml 0.0.2.
-- Renderers: Microsoft Word/PowerPoint/Excel 16 installed. LibreOffice is not installed on this machine. OCR (`tesseract`) and Poppler `pdftoppm` are not installed; PDF rendering uses PyMuPDF instead.
+What this plugin can do, verified 2026-10-21 on Windows by reading the code and
+running the helper CLI. Unverified items are marked as such.
 
-## Verification evidence
+## Runtime model
+
+Every operation goes through one spec-driven helper CLI, addressed by the
+absolute `python` and `cli` paths the host appends to each skill body as the
+`## Office runtime` block. It prints one JSON object; failures print JSON on
+stderr and exit non-zero.
+
+```
+<python> <cli> {docx|pptx|xlsx|pdf} {create|read|render}
+<python> <cli> xlsx recalc | status
+```
+
+`create` takes `--spec --out`, `read` takes `--input`, `render` takes
+`--input --out-dir`; all accept `--json-out`, `xlsx read` also `--data-only`.
+The CLI has no `edit` verb on purpose: changing a file is a set of narrow pack
+scripts (one operation each), so a new capability is a new script rather than a
+new verb in a shared dispatcher that every format has to keep in step.
+Every verb prints one JSON object; failures print JSON on stderr, exit non-zero.
+These verbs are the common path, not the ceiling: specialised work uses the pack
+scripts (`scripts/`, `container_tools/`), and the rest uses short snippets
+against the installed libraries, run with the same `python` and verified the same
+way. A missing verb is a missing shortcut, not a missing capability.
+
+## Packs and shared layer
+
+| Format | Router | Pack helpers | CLI verbs |
+| --- | --- | --- | --- |
+| DOCX | `assets/skills/office-documents/SKILL.md` | `scripts/` — OOXML kit, comments, fields, tracked changes, template styles, accessibility audit, text/blocks/properties edits | create, read, render |
+| PDF | `assets/skills/office-pdf/SKILL.md` | `scripts/` — text/table extraction, page rendering, form inspect/fill, page ops, region redaction | create, read, render |
+| PPTX | `assets/skills/office-presentations/SKILL.md` | `container_tools/` — OOXML helpers, preview rendering, text/slide/properties edits | create, read, render |
+| XLSX | `assets/skills/office-spreadsheets/SKILL.md` | `container_tools/` — workbook inspection, diff, recalculation gate, sheet/cell/row/style/chart edits | create, read, render, recalc |
+| live XLSX | `assets/skills/excel-live-control/SKILL.md` | `container_tools/live_excel.py` — attach to a running Excel/WPS window: read, write, formulas, styles, tables, charts, recalc, save | — |
+| shared | `assets/skills/shared/` | `common-workflow.md`, `annotation-recipes.md`, `check_runtime.py`, `scripts/ensure_raster_image.py` | — |
+
+The four routers register through `ctx.skills.registerProvider` in
+`src/index.ts`; `/` commands, labels and skill names come from
+`src/features.ts`. Helper scripts are argparse-based with `--help`.
+
+## What each format does
+
+- **DOCX** — create from a block spec: headings, paragraphs, bullets, numbered
+  lists, tables, images, LaTeX equations (OMML, fallbacks counted in
+  `equation_fallbacks`), quotes, page breaks, spacers, header/footer, page size,
+  margins. Read returns styled text, tables, images, equations, counts. Edits run
+  as pack scripts (text replacement, block append, core properties).
+- **PDF** — create with reportlab; the CJK font is auto-detected (named in the
+  report, e.g. `OfficeCJK`). Read returns page text, metadata, word counts and
+  form fields; OCR is not bundled (`ocr.available: false`). Edits run as pack
+  scripts: metadata, rotation, page order, merge, page removal, region
+  redaction. Render uses PyMuPDF.
+- **PPTX** — create 16:9 decks: layouts `title`, `bullets`, `section`,
+  `title_only`, `blank`; bullet levels, tables, bar/column/line/pie charts,
+  images. Read returns slides, text, tables and charts but **no shape geometry**,
+  so annotation work computes overlap with python-pptx. Edits run as pack
+  scripts: run-level text replacement, added slides, core properties.
+- **XLSX** — create sheets with rows, formulas, styles (cell or `A1:B2` range),
+  widths, row heights, frozen panes, merges, charts, anchored images. Read
+  returns rows, formulas with cached values, merges, charts, images, dimensions.
+  Edits run as pack scripts: sheets, cells, appended rows, range styles, charts,
+  images, rows.
+- **Live XLSX** — `excel-live-control` drives a workbook that is already open in
+  Excel or WPS Spreadsheets through COM (`GetActiveObject`, Windows PowerShell
+  5.1), never by writing the file behind the user's back: `info`, `read_range`,
+  `write_range`, `set_formula`, `style_range`, `add_chart`, `add_table`,
+  `recalc`, `save`, `close`, plus `--diagnose`. It refuses to start a hidden
+  instance for normal work and reports exactly which sheet and range it touched;
+  sheet create/rename/delete/reorder are deliberately absent (use a tab the user
+  has, or the file route).
+
+## Delivery rule
 
-Run on Windows, 2026-10-20, in paths containing Chinese characters and spaces.
+Hand the file over with `present` and summarise the change in one sentence. A
+bare path is not delivery: `.docx`/`.pptx`/`.xlsx`/`.pdf` links in the transcript
+render as "二进制文件，无法显示改动". Edits go to `<original>-edited.<ext>` (or
+the name the user asked for); never overwrite the original, report both paths.
+
+## Annotations
+
+A preview arrives as `<office-annotations>` wrapping a JSON array of items keyed
+`target`, `fileName`, `requirement`, `text` and a 0–1 `region`. `docx`/`pptx`
+add `page` (rendered PDF page; pptx one slide per page) and `pdf` adds a 1-based
+PDF `page` plus `imageName`. `xlsx` items are always `unmapped: true` with
+`text: ""` and no page/sheet/range: resolve cells from the `imageName` screenshot
+and `xlsx read`, and state the resolved sheet/A1 range before editing. Treat it
+as a change request — locate, smallest edit, re-render, confirm. Recipes:
+`assets/skills/shared/annotation-recipes.md`; unmappable payloads are reported,
+never guessed.
+
+## Renderer dependency
+
+- `docx`, `pptx` and `xlsx` rendering needs an office suite: Microsoft Office
+  (Word/PowerPoint/Excel over COM), WPS Office (`KWps`/`KWpp`/`Ket` over COM) or
+  LibreOffice (headless conversion). `render` names the one it used in its
+  `renderer` field (`microsoft-office`, `kingsoft-wps`, `libreoffice`). With none
+  installed it exits non-zero: `no document renderer found: install LibreOffice,
+  Microsoft Office, or WPS Office`.
+- `xlsx recalc` needs a real calculation engine: Excel or WPS Spreadsheets over
+  COM. It reports `renderer` and the count of cached values it filled in.
+- `pdf render` needs no external renderer; PyMuPDF rasterises it directly.
+- The PPTX pack's `container_tools/preview_render.py` is a geometry-only draft:
+  it redraws shapes, text boxes and images from the package with PyMuPDF and
+  labels itself `draft-preview` / `geometry-only`. It proves placement, not
+  typography (bullet glyphs are not drawn), and `render_slides.py` prefers the
+  real renderer whenever one exists.
+- **This machine renders through WPS Office.** `office_status` reports
+  `kingsoft_wps: {writer, presentation, spreadsheet}` from `wps.exe`/`wpp.exe`/
+  `et.exe` under `%LOCALAPPDATA%\Kingsoft\WPS Office\<version>\office6`;
+  `docx`/`pptx`/`xlsx render` return `"renderer": "kingsoft-wps"`, and `xlsx
+  recalc` fills cached values through `Ket.Application`.
+- `assets/skills/shared/scripts/ensure_raster_image.py` turns SVG, a chosen PDF
+  page, or a raster file into a PNG (PyMuPDF for vectors, Pillow for rasters), so
+  artwork can be embedded and then looked at. It never overwrites its input.
+- `assets/skills/shared/check_runtime.py` imports every package from
+  `python/requirements.txt` and runs `<cli> status`; it exits non-zero on a
+  missing package or broken CLI, and 4 with `--require-renderer` when no renderer
+  is installed (a missing renderer is otherwise only a warning).
+
+## Verification evidence
 
 | Check | Result |
 | --- | --- |
-| `pnpm run typecheck` | Passed |
-| `pnpm run build` | Passed; `dist/index.js`, `dist/index.d.ts`, `dist/client.js` generated |
-| `pnpm run test -- --run` | 14 passed across 2 files (10 in `test/office-cli.test.ts`) |
-| DOCX create/read/edit/render | Passed; rendered page inspected: Chinese header/title/body/table/equation/image/footer |
-| PDF create/read/edit/render | Passed; Chinese text extracted, metadata edit, page rendered |
-| PPTX create/read/edit/render | Passed; four slides rendered; table/chart/image layout fixed and inspected |
-| XLSX create/read/edit/recalc | Passed; formulas preserved; Excel recalculation produced cached values; data-only read confirmed |
-| `postinstall.mjs` first run | Passed; venv created, 10 packages installed, imports verified, config written |
-| `postinstall.mjs` second run | Passed in 2.7 s; idempotent |
-| `PATH` update | Registry write blocked by this Windows sandbox; plugin now warns instead of claiming success; absolute-path resolution works |
-| Chinese + spaces path | Used for every integration test |
-| Missing/incompatible Python | `resolvePython` reports `found: false` or `compatible: false`; skill bodies tell the agent to stop and ask for repair instead of running |
-| Interrupted installer | Download uses a unique temp filename per process; stale locked installers no longer block a retry |
-| `pnpm run lint --fix` | Passed |
-
-## Unsupported (explicit)
-
-- Google Docs, Google Slides, Google Sheets, Google Drive import/export, or any online document editing.
-- `@oai/artifact-tool`-only behavior and its artifact-session lifecycle.
-- DOCX comments, tracked changes, TOC fields, watermarks, redaction, content controls, template-style transfer, and accessibility audit.
-- PDF OCR, AcroForm filling, signing, redaction, and page-level text editing.
-- PPTX animations, speaker notes, template slide masters, and morph transitions.
-- XLSX pivot tables, macros, data validation, conditional formatting, and shared-workbook features.
-- Installing LibreOffice or Python on macOS/Linux; the plugin detects and reports, but only Windows auto-installs Python.
-- Live GUI interaction (menu open, chip insertion, chip persistence, right-sidebar preview) was not exercised in a running DSH window. It compiles against the public `0.2.1-rc.2` types, but installation into the user's profile was intentionally not performed.
-
-## UI API constraints recorded during implementation
-
-- The public composer `ReferenceChip` shows a custom icon only for `session`, `file`, and `folder`. This plugin uses `appearance: 'file'` in the composer, so the chip shows the built-in file glyph plus the friendly format label. The `/` menu candidates and transcript chips use four Gravity UI Icons SVGs (`file-text`, `file-letter-p`, `display`, `layout-cells`), vendored in `assets/icons` under MIT.
-- `matchEnter` cannot create a reference chip; Enter on a highlighted `/` candidate goes through the source's `onPick`, which is the implemented path.
-- The chip's stable internal ref is the feature id; clipboard/persistence text is `/documents` etc.; model serialization names the skill explicitly so the agent loads it before file work.
+| Packages on the runtime venv (3.13.12, `~/.dsh/office/runtime/venv`) | 10/10 import — python-docx 1.2.0, openpyxl 3.1.5, python-pptx 1.0.2, pypdf 6.21.1, reportlab 4.5.1, pdfplumber 0.11.9, PyMuPDF 1.28.2, Pillow 11.3.0, latex2mathml 3.81.1, mathml2omml 0.0.2 |
+| `check_runtime.py` (venv / `--require-renderer` / bare `py -3.14`) | exit 0 + renderer warning / exit 4 / exit 1 listing the 8 missing packages and the pip remedy |
+| DOCX create / read / `replace_text.py` / `append_blocks.py` | ok — counts returned, styles preserved, `replacements: 1`, `appended: 1`, equation intact |
+| DOCX / PPTX render | ok through WPS — `renderer: kingsoft-wps`, DOCX 2 pages, PPTX 3 pages, PNGs opened and checked |
+| PPTX create / read / `add_slides.py` | ok — 3 slides, texts and charts read back |
+| XLSX create / read / `set_cells.py` | ok — formula read back uncached, one cell written |
+| XLSX recalc | ok through WPS — `renderer: kingsoft-wps`, 34 cached values filled, `A3 = 7` after `CalculateFull` |
+| `ensure_raster_image.py` | ok — 120×60 SVG at `--dpi 300` → 500×250, `--page` on a 2-page PDF, `--width 400` upscale, JSON errors on missing/unwritable input |
+| `excel-live-control/container_tools/live_excel.py` | ok against WPS — attach refusal with remediation when nothing runs; `write_range` A1:B3 (6 cells), `set_formula` C1, `read_range` values `[[10,20,30],[30,40,null],[50,60,null]]`, `save` 9,268 bytes, `--diagnose` lists the workbook/sheet, `close --quit-app` refuses a dirty book, `--discard` leaves zero `et.exe` |
+| PDF create / read / render / `metadata.py` / `page_ops.py` / `redact_region.py` | ok — CJK font applied, metadata written, merge→remove→rotate, region redaction removed 170 chars and 11 drawings, `page-1.png` produced |
+| Annotation geometry helpers | pymupdf rect conversion, python-pptx overlap scan, A1 text matching run against those files |
+| Forbidden-vocabulary grep over the delivered docs | empty |
+
+Not claimed (no evidence here): installer or self-heal timings, live GUI
+interaction (`/` menu, chip, sidebar preview, annotation overlay), and macOS/Linux
+renderer support.
+
+## Explicitly out of scope
+
+- Google Docs/Slides/Sheets or Drive-backed editing; visual verification of
+  docx/pptx/xlsx without a renderer (skills say so instead of claiming a page was
+  inspected).
+- In-place PDF page-content editing (rebuild from a `pdf create` spec and say
+  so); OCR and scanned-PDF text extraction.
+- PPTX animations, speaker notes, slide masters; XLSX pivots, macros, data
+  validation, conditional formatting — no spec keys or verbs in the helper.
+- Formula evaluation without Microsoft Excel or WPS Spreadsheets; macOS/Linux
+  installation and renderer behaviour (only Windows was exercised).

package/README.md

@@ -35,8 +35,10 @@ dsh plugin add dsh-office-kit
 - 📄 **PDF**：`/pdf` 创建、读取和编辑 PDF，支持合并、旋转、删页与元数据。
 - 📽️ **演示文稿**：`/presentations` 创建、读取和编辑 PPTX，支持项目符号、表格、图表与图片。
 - 📊 **电子表格**：`/spreadsheets` 创建、读取和编辑 XLSX，支持公式、样式、图表、冻结窗格与重算。
-- 🖍️ **侧边栏标注**：在 PDF、DOC/DOCX 预览中吸附段落或框选区域，批量提交修改要求。
+- 🖍️ **侧边栏标注**：在 PDF、DOC/DOCX、PPTX、XLSX 预览中吸附段落或框选区域，批量提交修改要求。
 - 🔗 **会话引用**：通过 Chip 调用文档技能；注释链接可悬停查看文件名与要求，PDF 标注附选区截图。
+- 🖼️ **渲染校验**：DOCX/PPTX/XLSX 经 Microsoft Office、WPS Office 或 LibreOffice 导出 PDF 再栅格化，PDF 直接用 PyMuPDF；SVG/PDF 素材可用 `ensure_raster_image.py` 转成 PNG 后嵌入。
+- 🧮 **活体表格**：`excel-live-control` 技能通过 COM 驱动已经打开的 Excel / WPS 表格（读区、写值、样式、图表、重算、保存）。
 
 ## 🚀 快速开始
 

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

@@ -0,0 +1,234 @@
+---
+description: Drive a workbook that is already open in Excel or WPS Spreadsheets over COM — read cells, write values and formulas, style ranges, add charts and tables, recalculate, save, and report the exact ranges touched.
+---
+
+# Live spreadsheets (Excel / WPS)
+
+## What "live" means here
+
+The workbook is open in a running Excel or WPS Spreadsheets window, and the user is
+looking at it. The file on disk may be behind the window, may not exist yet, and may
+carry edits the user has not saved. A live call changes the *open document*: the cells
+the user is staring at update while they watch, and saving is a separate decision.
+
+That one sentence drives everything below:
+
+- The target is `Application.ActiveWorkbook`-shaped state, not a path. Address it by
+  workbook name, sheet name and A1 range, never by "the active sheet" or "the selection".
+- Nothing is transactional. A failed call leaves whatever already landed exactly where
+  it landed. Read before retrying; never replay a half-applied batch.
+- The disk file is not the deliverable. What the user sees in the window is. Saving is
+  an explicit act you announce.
+
+## Live or file editing?
+
+| Situation | Route |
+| --- | --- |
+| The user says the file is open, or asks for "the sheet I'm looking at" | this skill |
+| They want to watch cells change, iterate on a model with them, or add a chart to the visible sheet | this skill |
+| No spreadsheet application is running | `../office-spreadsheets/SKILL.md` — edit the file, then tell them to reopen it |
+| Bulk generation, batch jobs, CI, or work that outlives the session | `../office-spreadsheets/SKILL.md` |
+| Reading a file to answer a question, with no app open | `../office-spreadsheets/SKILL.md` |
+
+Never force the live path. If nothing is running, do not launch an application to avoid
+talking to the user: say plainly that the workbook must be open, or switch to the file
+route and say so.
+
+## Before you touch anything
+
+1. Call the `office_status` tool, then take the `## Office runtime` JSON block that the
+   host appends to `../office-spreadsheets/SKILL.md` (this sub-skill is routed from
+   there, so that block is where the paths live). Use its `python` value verbatim and
+   quote every path; this pack's directory is `<skill>/../excel-live-control`, which is
+   what `<skill>` below means.
+2. Run `"<python>" "<skill>/container_tools/live_excel.py" --help` once per session.
+3. Attach and look before writing:
+
+   ```
+   "<python>" "<skill>/container_tools/live_excel.py" info
+   ```
+
+   `info` lists every open workbook, the target workbook, its sheets, and per sheet the
+   used range, charts, tables, pivot tables and protection state.
+
+4. If attach fails, the JSON carries a `remediation` string. Relay it as written: open
+   the workbook in Excel or WPS and keep it open, then ask for the change again. Do not
+   start an application on the user's behalf.
+5. If more than one workbook is open, the tool refuses to guess. Pass `--workbook` with
+   the file name (`Budget FY26.xlsx`) or enough of the path to be unambiguous.
+6. Something looks wrong with the environment — attach works but calls fail, or the
+   application name and vendor disagree — run `--diagnose`. It reports the attach
+   mechanism, the running application, every workbook and every sheet without mutating
+   anything.
+
+Attachment uses `[Runtime.InteropServices.Marshal]::GetActiveObject` from Windows
+PowerShell 5.1, trying `Excel.Application` then `Ket.Application` (WPS Spreadsheets).
+WPS registers `Excel.Application` as an alias, so the reported application name is not
+proof of which product is running; the JSON's `engine.vendor` is derived from
+`Application.Path`. Mechanics and the COM object model: `references/office-automation.md`.
+
+## The edit contract
+
+These are not preferences. Every mutating call has to satisfy them.
+
+- **Touch only what was asked for.** The named sheet and the named ranges. Not the
+  neighbouring column, not the whole sheet, not "while I'm here".
+- **Read before you write.** Call `read_range` on the target first. You need to know
+  whether a cell holds a value, a formula, or a merged-region fragment, and whether the
+  user's edits are unsaved before you replace them.
+- **Never destroy structure you did not create**: formulas (never flatten to values),
+  named ranges, conditional formats, shared formulas, data validation, pivots and their
+  sources, chart series definitions, filters, hidden rows, freeze panes, protection.
+- **Never clear more than you can name.** `write_range --clear` clears contents of an
+  explicit range; it does not remove charts, tables or formats. Clearing a used range to
+  "start clean" is off-limits.
+- **Small writes, batched.** One call per logical block (a column of assumptions, a
+  sheet of outputs). Rectangular data only: if the range is 6 rows × 2 columns, the JSON
+  array must be 6 rows of 2 values.
+- **Report exactly what you touched.** Every mutating op answers with workbook name and
+  path, sheet, exact address, row/column/cell counts, and a `warnings` list. Quote that
+  in your reply — "wrote `Assumptions!C4:D8` (10 cells)" — not "updated the assumptions".
+- **Saving is a separate, announced act.** See Delivery.
+- **No decorative edits without a request.** Do not restyle a sheet to your taste, do not
+  autofit whole columns, do not add a header row the user did not ask for.
+
+If a call fails partway, `read_range` the block you were writing and continue from what
+actually landed. Retrying the identical call is how duplicate rows and reversed edits
+happen.
+
+## The tool
+
+`"<skill>/container_tools/live_excel.py"` — one command per operation, one JSON object on
+stdout, non-zero exit on failure. It shells out to `powershell.exe`; pywin32, comtypes and
+Excel interop assemblies are neither used nor needed.
+
+| Op | Does | Key options |
+| --- | --- | --- |
+| `info` | workbooks, target workbook, sheet inventory | `--workbook` |
+| `read_range` | typed values, optionally formulas and displayed text | `--sheet --range`, `--formulas`, `--display`, `--max-cells` |
+| `write_range` | one rectangular block of values | `--sheet --range --data`/`--data-file`, `--clear` |
+| `set_formula` | a formula filled across a range, or a cell→formula map | `--range --formula`, or `--cells '{"C1":"=A1+B1"}'`/`--cells-file`, `--r1c1` |
+| `style_range` | font, fill, number format, alignment, borders, width, merge | `--style` JSON or `--style-file`, `--merge` |
+| `add_table` | native table (ListObject) over a range | `--name`, `--style TableStyleMedium2`, `--no-headers` |
+| `add_chart` | embedded chart pointed at a range | `--type`, `--data`, `--anchor`, `--title`, `--width`, `--height` |
+| `recalc` | `CalculateFull` on every open workbook | — |
+| `save` | save in place, or `SaveAs` a copy | `--path` |
+| `close` | close the workbook, optionally quit the application | `--save`, `--discard`, `--quit-app` |
+
+Global options on every op: `--workbook NAME|PATH`, `--timeout SECONDS` (default 180;
+a live call is allowed to take seconds), and `--launch-hidden` (**self-tests only** — it
+starts a hidden application, which is wrong for any user-facing edit).
+
+Style keys: `font_name`, `font_size`, `bold`, `italic`, `color`, `fill` (hex RGB, e.g.
+`#FFF2CC`), `number_format`, `h_align` (`left|center|right|general|justify`), `v_align`
+(`top|center|bottom`), `indent`, `wrap`, `column_width`, `border` (`outline|all|none`).
+Unknown keys are rejected with the allowed list rather than silently dropped.
+
+Chart types: `column`, `column-stacked`, `bar`, `bar-stacked`, `line`, `line-markers`,
+`area`, `area-stacked`, `pie`, `doughnut`, `scatter`, `scatter-lines`.
+
+Typical first calls:
+
+```
+"<python>" "<skill>/container_tools/live_excel.py" info
+"<python>" "<skill>/container_tools/live_excel.py" read_range --sheet Build --range D5:D9 --formulas
+"<python>" "<skill>/container_tools/live_excel.py" write_range --sheet Assumptions --range C4:D8 --data-file assumptions.json
+"<python>" "<skill>/container_tools/live_excel.py" set_formula --sheet Build --range E5:E9 --formula "=D5*Assumptions!$C$4"
+"<python>" "<skill>/container_tools/live_excel.py" style_range --sheet Assumptions --range C4:D8 --style '{"number_format":"#,##0","fill":"#FFF2CC"}'
+```
+
+Failures print `{"ok": false, "stage": "...", "error": "...", "remediation": "..."}` and
+exit 1 (2 for usage errors, 3 when PowerShell itself is unavailable). `stage: "attach"`
+means nothing was running; `stage: "com"` means the application refused or failed the
+call; read the message before changing the approach.
+
+The CLI is the fast path, not the ceiling. When a job needs a COM call it does not wrap —
+a sheet tab, freeze panes, a pivot, data validation, shape geometry — extend the script or
+drive the application from a short PowerShell snippet, and keep the same reporting and
+verification rules. The object model is in `references/office-automation.md`.
+
+What this tool deliberately does not do: create, rename, delete or reorder sheets; delete
+ranges or objects; run macros; open a file from disk. A job that needs one of those asks
+the user for it, or belongs to the file route in `../office-spreadsheets/SKILL.md`.
+
+## Verification
+
+Do these in order after every batch of edits, before you report anything as done.
+
+1. **Read it back.** `read_range` the exact ranges you wrote, with `--formulas` when you
+   wrote formulas. Compare against what you intended cell by cell.
+2. **No error cells.** The `errors` array in `read_range` lists every cell whose *live*
+   value is an error (`#DIV/0!`, `#VALUE!`, `#REF!`, `#NAME?`, `#N/A`, …) with its
+   formula and address. An edit that leaves an error is not finished. A pre-existing
+   error you did not cause is reported to the user, not silently fixed.
+3. **Numbers.** Run `recalc` after adding or changing formulas, then read the cells
+   again. A formula that has not been calculated tells you nothing.
+4. **Objects.** If you added a table or chart, run `info` and confirm it in the sheet's
+   inventory, and read the chart's `source` from `add_chart`'s reply to confirm it points
+   at the range you meant.
+5. **Appearance.** You cannot screenshot the user's window from here. `--display` on
+   `read_range` shows the rendered text of each cell (up to 500), which catches `###`
+   widths, applied number formats and stray `#` — use it when formatting is part of the
+   request. Otherwise say the visual check is the user's, and ask them to confirm if it
+   matters.
+6. **Structure.** If the sheet had tables, pivots or charts before you started, `info`
+   after the edit proves they are still there.
+7. **Report.** Name the workbook, the sheet, every range, and the cell counts.
+
+## Delivery
+
+The workbook is the user's open document, not an artifact you produced. Say what you did
+and what state the document is in; do not save quietly.
+
+- **Default: leave the document modified and unsaved.** The change is visible in their
+  window. Tell them so, and tell them Ctrl+S keeps it. This is what keeps you from
+  overwriting a file they were editing by hand.
+- **They asked you to save**: `save` with no `--path` writes the workbook over its own
+  file. Say "saved `Budget FY26.xlsx`" and give the full path from the reply.
+- **Unsaved workbook, or they want an artifact to keep**: `save --path <copy>.xlsx`
+  writes a copy and leaves the original window dirty. Then `present` that copy — it is a
+  real file they can open, send, or archive.
+- **`.xlsx` in chat**: a path on its own is not delivery. Use the `present` tool on a
+  saved file, and state both paths when the original and the copy differ.
+- **Never** save over the user's file to "make sure it's persisted" without telling them,
+  and never close their workbook. `close --quit-app` is for cleaning up a self-test
+  instance, not for tidying the user's desktop.
+- If the edit failed partway and the document is dirty with a half-finished change, say
+  exactly which ranges landed, and offer either to finish them or to close without saving.
+
+## What good content looks like
+
+The mechanics above keep the document intact; these rules keep it useful. The same rules
+as the file-editing skill, because a careless live edit damages a document the user is
+looking at.
+
+- **Structure by role, not by tab count.** Inputs, assumptions, calculations, outputs.
+  Outputs on the left of the tab strip, builds in the middle, inputs on the right; a
+  terminal check/audit tab for models that need one. Do not restructure a workbook the
+  user already organised — `workflows/edit_workflows.md`.
+- **Formulas that a reviewer can audit.** Anchored references (`$B$3`, `C$4`, `$A8`),
+  `SUMIFS`/`COUNTIFS`/`AVERAGEIFS` over hand-rolled sums, short `IF`, no blanket
+  `IFERROR(...,0)` (`#VALUE!` is information), no `LET`/`LAMBDA`/spill arrays.
+  `workflows/create_workflows.md` and `references/office-automation.md` for what COM
+  stores when you write these.
+- **Typed values.** Numbers as numbers, dates as dates, one number format per column.
+  Invariant format codes (`#,##0`, `0.0%`, `"$"#,##0.00`) — never swap `.` and `,`.
+- **Reading someone else's workbook is read-only.** `references/read_only_qna.md`.
+- **Domain conventions** — finance, healthcare, marketing, scientific data — carry real
+  meaning in their cells: `domain_guidance/`. Read the matching file before modelling in
+  that area.
+- **Visual defaults** (headers, input fills, borders, tab colours, one font family):
+  `style_guidelines.md`.
+- **Citations** for external data go next to the input table they support, not in a
+  tab of their own.
+
+## Files in this skill
+
+| File | Use it when |
+| --- | --- |
+| `references/office-automation.md` | you need the COM object model: addressing, `Value2` vs `Formula`, colour encoding, locale, latency |
+| `references/read_only_qna.md` | answering a question about the open workbook without changing it |
+| `style_guidelines.md` | the request involves how the sheet looks |
+| `workflows/create_workflows.md` | building a new sheet or workbook live |
+| `workflows/edit_workflows.md` | changing cells in a workbook the user already built |
+| `domain_guidance/*.md` | the model is financial, clinical, marketing, or research data |