dsh-office-kit 0.2.0 → 0.3.0

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

@@ -1,110 +1,114 @@
 ---
-description: Create, inspect, edit, recalculate, and render Excel .xlsx workbooks with the bundled Office helper CLI.
+description: Create, inspect, edit, recalculate, and verify Excel workbooks (.xlsx/.csv) using openpyxl recipes and the bundled Office helper CLI.
 ---
 
 # Spreadsheets (.xlsx)
 
-Build local Excel workbooks with values, formulas, styles, charts, and images; inspect existing workbooks; recalculate with Excel when cached values are required. This skill does not use `@oai/artifact-tool` and does not edit Google Sheets.
+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 — Microsoft Excel or WPS Spreadsheets via `xlsx recalc`, 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.
+
+| User job | What is really 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` |
+| 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) |
+| 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.
 
 ## Before any file work
 
 1. Call the `office_status` tool.
-2. Use the `python` and `cli` values from the `## Office runtime` JSON block at the end of this file.
-3. If no compatible Python is reported, stop and tell the user.
-
-## Create
-
-```bash
-"<python>" "<cli>" xlsx create --spec "<spec.json>" --out "<output.xlsx>"
-```
-
-```json
-{
-  "sheets": [{
-    "name": "Summary",
-    "rows": [
-      ["Quarter", "Revenue", "Cost", "Gross profit"],
-      ["Q1", 100, 60, "=B2-C2"],
-      ["Q2", 128, 70, "=B3-C3"],
-      [null, "=SUM(B2:B3)"]
-    ],
-    "styles": {
-      "A1:D1": { "bold": true, "fill": "#E8EEF7", "align": "center" },
-      "B2:D4": { "number_format": "#,##0" }
-    },
-    "widths": { "A": 12, "B": 14, "C": 12, "D": 14 },
-    "freeze": "A2",
-    "charts": [{
-      "type": "column",
-      "title": "Quarterly revenue",
-      "anchor": "F2",
-      "data": { "min_col": 2, "min_row": 1, "max_col": 2, "max_row": 3, "titles_from_data": true },
-      "categories": { "min_col": 1, "min_row": 2, "max_row": 3 }
-    }]
-  }]
-}
-```
-
-Rows are written from A1. A string starting with `=` is a formula, not text. Styles support `bold`, `italic`, `size`, `color` (hex), `fill` (hex), `number_format`, and `align` (`left`/`center`/`right`). Chart types: `bar`, `column`, `line`, `pie`; data/category references are 1-based.
-
-## Read
-
-```bash
-"<python>" "<cli>" xlsx read --input "<file.xlsx>"
-"<python>" "<cli>" xlsx read --input "<file.xlsx>" --data-only
-```
-
-Default read returns formulas. `--data-only` returns cached values, which are only present if Excel (or another producer) stored them. A formula created by openpyxl has no cached value until recalculated.
-
-## Edit
-
-```bash
-"<python>" "<cli>" xlsx edit --input "<file.xlsx>" --spec "<edit.json>" --out "<file-edited.xlsx>"
-```
-
-```json
-{
-  "operations": [
-    { "action": "set_cells", "sheet": "Summary", "cells": { "E2": "Reviewed", "E3": "Pending" } },
-    { "action": "append_rows", "sheet": "Summary", "rows": [["Q3", 150, 80, "=B4-C4"]] },
-    { "action": "style", "sheet": "Summary", "cells": { "E2:E3": { "bold": true } } },
-    { "action": "add_sheet", "name": "Notes" },
-    { "action": "rename_sheet", "from": "Notes", "to": "Appendix" },
-    { "action": "delete_sheet", "name": "Appendix" }
-  ]
-}
-```
-
-Actions: `set_cells`, `append_rows` (or `rows`), `style`, `chart`, `image`, `add_sheet`, `delete_sheet`, `rename_sheet`. The input is never modified. Existing formulas/styles outside the edited cells are preserved by openpyxl, but charts created by other tools may be dropped when the workbook is re-saved; verify before replacing a production file.
-
-## Recalculate formulas
-
-```bash
-"<python>" "<cli>" xlsx recalc --input "<file.xlsx>" --out "<file-recalculated.xlsx>"
-```
-
-This requires Microsoft Excel on Windows. It opens the workbook, forces a full calculation, saves with cached values, and closes Excel. On other systems the CLI fails explicitly; there is no bundled formula engine. Without recalculation, Excel normally computes formulas when the file is opened, but `--data-only` reads will stay empty.
-
-## Render and verify
-
-```bash
-"<python>" "<cli>" xlsx render --input "<file.xlsx>" --out-dir "<render-dir>"
-```
-
-The renderer prefers Microsoft Excel COM on Windows (exports each sheet to PDF) and LibreOffice otherwise, then rasterizes pages to PNG. Check values, number formats, column widths, frozen panes, merged cells, chart legends/categories, and clipping. `read` complements the visual check for exact cell values.
-
-## Quality rules
-
-- Put raw inputs and calculated cells on the same sheet, or clearly document the calculation chain.
-- Use formulas instead of hard-coded results when the workbook should stay live.
-- Use number formats for currency/percent/dates instead of embedding symbols in text.
-- Keep one header row, avoid merged cells in data ranges, and leave a frozen header.
-- Verify every formula you authored with `read` (formula) and, where possible, `recalc` + `--data-only` (value).
-
-## Not supported
-
-- Google Sheets / Google Drive editing.
-- Pivot tables, Power Query, macros/VBA, data validation, conditional formatting, slicers, external workbook links.
-- Formula evaluation without Microsoft Excel; `recalc` is Windows + Excel only.
-- Exact Excel rendering fidelity on LibreOffice; charts from foreign producers may not survive editing.
-- `@oai/artifact-tool` helpers or artifact-tool workbook gates.
+2. Read the `## Office runtime` JSON block at the end of this file and use its `python`, `cli`, `skill`, and `shared` values verbatim, quoted: `"<python>"`, `"<cli>"`, `"<skill>/container_tools/<name>.py"`.
+3. If that block reports no working runtime, stop. Give the user the `node "..."` remedy command it names, then call `office_status` again. Never claim a workbook you could not create, read, or recalculate.
+4. Run `<python> <script> --help` before using a container tool you have not called in this session.
+
+## 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.
+
+- 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.
+
+## 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.
+
+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"`.
+
+## 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>"`. On a host without Microsoft Excel or WPS Spreadsheets the recalc fails and `recalc_gate.py` 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 Excel, WPS Spreadsheets, or LibreOffice; with none installed it fails explicitly: report the file as structurally verified but visually unchecked, and offer to rebuild from a spec. WPS in particular needs its print area and page setup right before exporting, so a layout complaint may be the export settings rather than the sheet.
+
+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.
+
+| 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 |
+
+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 the same as a blank cell — leave a cell out of the assignment to keep it blank.
+
+## Formulas you will write
+
+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).
+- Lookups: `INDEX`/`MATCH`, `VLOOKUP` with `FALSE`, or `XLOOKUP` if the file already uses it. A matched key is not a populated value — check the looked-up cell too.
+- Guards: `IFERROR` only around an understood failure, never `IFERROR(x,0)` across a block. A blank input and a real zero are different answers: `=IF(C8="","",B8/C8)` and `=IF(C8=0,"n.a.",B8/C8)`.
+- 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`.
+
+## Tasks
+
+| Task | Read |
+| --- | --- |
+| Build a workbook from scratch | `tasks/create-workbook.md` |
+| Edit an existing workbook without collateral damage | `tasks/edit-workbook.md` |
+| Inspect sheets, ranges, formulas, names, conditions | `tasks/inspect-workbook.md` |
+| Diff two workbook versions | `tasks/diff-workbooks.md` |
+| Recalculate and gate consistency | `tasks/recalc-and-check.md` |
+| Answer questions about an existing file | `tasks/analyze-workbook.md` |
+| Resolve an `office-annotations` region to cells | `tasks/annotations.md` |
+
+## Recipe index
+
+`recipes/number-formats.md`, `recipes/conditional-formats.md`, `recipes/data-tables.md`, `recipes/charts.md`, `recipes/sparklines.md`, `recipes/named-ranges.md` — each is a short runnable openpyxl snippet plus the pitfall it avoids. Use them when the CLI spec has no key for what you need; the CLI is a shortcut, not a ceiling.
+
+Background: `references/workbook-structure.md` (tab roles and layout), `references/formula-patterns.md` (anchoring, aggregation, dates), `references/style-guidelines.md` (visual defaults), `references/charts.md` (chart choice and audit), `references/domain/*.md` (finance, healthcare, marketing, research conventions).
+
+## 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`.
+
+## 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.

package/assets/skills/office-spreadsheets/container_tools/add_chart.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""Add a native, editable chart to an existing worksheet.
+
+The chart is bound to cells, not to copied values: read the numbers you want to
+plot straight from the sheet so the chart tracks later edits. Chart types are
+the helper CLI's: `bar`, `column`, `line`, `pie`.
+
+Reference rows/columns are 1-based sheet coordinates. `--data`-style flags
+describe the plotted values; category flags describe the labels.
+
+Examples:
+    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-col 2 --cat-min-row 2 --cat-max-row 2
+    add_chart.py --input book.xlsx --sheet Model --spec chart.json
+
+    chart.json: {"title": "Q4 plan (USD)", "type": "column", "anchor": "A16",
+                 "data": {"min_col": 2, "min_row": 11, "max_col": 2, "max_row": 14,
+                          "titles_from_data": true,
+                          "categories": {"min_col": 1, "min_row": 11, "max_row": 14}}}
+
+A chart added this way has no explicit axis number format and keeps the default
+series name, so check the rendered page and fix the title, units, and legend.
+
+Exit codes:
+  0  chart added (the JSON on stdout reports the sheet's chart count)
+  1  refused: unknown sheet, incomplete reference, or unsupported chart type
+  2  usage error, missing file, or unreadable workbook
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(errors="replace")
+
+ROOT = Path(__file__).resolve().parents[4]
+CHART_TYPES = {"bar", "column", "line", "pie"}
+
+
+def load_office_cli():
+    """Reuse the helper CLI's chart builder so create-time and edit-time charts match."""
+    scripts = ROOT / "python"
+    if not (scripts / "office_cli.py").is_file():
+        raise RuntimeError(f"helper CLI not found next to the skill: {scripts / 'office_cli.py'}")
+    if str(scripts) not in sys.path:
+        sys.path.insert(0, str(scripts))
+    import office_cli
+
+    return office_cli
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Add a native chart to an .xlsx worksheet.")
+    parser.add_argument("--input", required=True, help="source workbook")
+    parser.add_argument("--out", help="destination workbook (default: <input>-edited.xlsx)")
+    parser.add_argument("--sheet", help="target worksheet (required unless --spec names one)")
+    parser.add_argument("--spec", help="JSON file with a chart object or a list of chart objects")
+    parser.add_argument("--type", default="column", choices=sorted(CHART_TYPES), help="chart type")
+    parser.add_argument("--title", default="", help="chart title")
+    parser.add_argument("--anchor", default="E2", help="top-left cell the chart floats over")
+    parser.add_argument("--height", type=float, default=8.0, help="chart height in cm")
+    parser.add_argument("--width", type=float, default=14.0, help="chart width in cm")
+    parser.add_argument("--data-min-col", type=int, help="first data column (1-based)")
+    parser.add_argument("--data-min-row", type=int, help="first data row (1-based)")
+    parser.add_argument("--data-max-col", type=int, help="last data column (1-based)")
+    parser.add_argument("--data-max-row", type=int, help="last data row (1-based)")
+    parser.add_argument("--titles-from-data", action="store_true", help="first data row holds series names")
+    parser.add_argument("--cat-min-col", type=int, help="first category column (1-based)")
+    parser.add_argument("--cat-min-row", type=int, help="first category row (1-based)")
+    parser.add_argument("--cat-max-row", type=int, help="last category row (1-based)")
+    return parser.parse_args()
+
+
+def _error(message: str, code: int) -> int:
+    print(json.dumps({"ok": False, "error": message}), file=sys.stderr)
+    return code
+
+
+def charts_from_flags(args: argparse.Namespace) -> list[dict[str, object]]:
+    if args.data_min_col is None or args.data_min_row is None:
+        raise ValueError("--data-min-col and --data-min-row are required without --spec")
+    data: dict[str, object] = {
+        "min_col": args.data_min_col,
+        "min_row": args.data_min_row,
+        "max_col": args.data_max_col if args.data_max_col is not None else args.data_min_col,
+        "max_row": args.data_max_row if args.data_max_row is not None else args.data_min_row,
+        "titles_from_data": bool(args.titles_from_data),
+    }
+    if args.cat_min_col is not None:
+        categories: dict[str, object] = {"min_col": args.cat_min_col}
+        if args.cat_min_row is not None:
+            categories["min_row"] = args.cat_min_row
+        if args.cat_max_row is not None:
+            categories["max_row"] = args.cat_max_row
+        data["categories"] = categories
+    return [
+        {
+            "type": args.type,
+            "title": args.title,
+            "anchor": args.anchor,
+            "height": args.height,
+            "width": args.width,
+            "data": data,
+        }
+    ]
+
+
+def charts_from_spec(path: Path) -> list[dict[str, object]]:
+    payload = json.loads(path.read_text(encoding="utf-8-sig"))
+    items = payload if isinstance(payload, list) else payload.get("charts", [payload])
+    charts = [item for item in items if isinstance(item, dict)]
+    if not charts:
+        raise ValueError("--spec holds no chart objects")
+    return charts
+
+
+def is_row_oriented(spec: dict[str, object]) -> bool:
+    """A one-row data range holds one series of many points, not many series of one."""
+    data = spec.get("data")
+    if not isinstance(data, dict):
+        return False
+    if data.get("from_rows"):
+        return True
+    min_row = int(data.get("min_row", 0))
+    max_row = int(data.get("max_row", min_row))
+    min_col = int(data.get("min_col", 0))
+    max_col = int(data.get("max_col", min_col))
+    return min_row == max_row and max_col > min_col
+
+
+def add_row_oriented_chart(worksheet, spec: dict[str, object]) -> None:
+    """Build the chart directly: the helper CLI's reference builder reads columns only."""
+    from openpyxl.chart import BarChart, LineChart, PieChart, Reference
+
+    chart_type = str(spec.get("type", "column")).lower()
+    chart = {"bar": BarChart, "column": BarChart, "line": LineChart, "pie": PieChart}[chart_type]()
+    chart.title = str(spec.get("title", ""))
+    chart.height = float(spec.get("height", 8))
+    chart.width = float(spec.get("width", 14))
+
+    data = spec["data"]
+    values = Reference(
+        worksheet,
+        min_col=int(data["min_col"]),
+        min_row=int(data["min_row"]),
+        max_col=int(data.get("max_col", data["min_col"])),
+        max_row=int(data.get("max_row", data["min_row"])),
+    )
+    chart.add_data(values, titles_from_data=bool(data.get("titles_from_data", False)), from_rows=True)
+    categories = data.get("categories")
+    if isinstance(categories, dict):
+        chart.set_categories(Reference(
+            worksheet,
+            min_col=int(categories.get("min_col", 1)),
+            min_row=int(categories.get("min_row", 1)),
+            max_row=int(categories.get("max_row", data.get("max_row", 1))),
+        ))
+    worksheet.add_chart(chart, str(spec.get("anchor", "E2")))
+
+
+def main() -> int:
+    args = parse_args()
+    source = Path(args.input).expanduser()
+    if not source.is_file():
+        return _error(f"input file not found: {source}", 2)
+
+    try:
+        office_cli = load_office_cli()
+        from openpyxl import load_workbook
+    except (ImportError, RuntimeError) as error:  # pragma: no cover - environment guard
+        return _error(str(error), 2)
+
+    try:
+        charts = charts_from_spec(Path(args.spec).expanduser()) if args.spec else charts_from_flags(args)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        return _error(str(error), 1)
+
+    if not args.sheet:
+        return _error("--sheet is required", 2)
+
+    workbook = load_workbook(str(source))
+    if args.sheet not in workbook.sheetnames:
+        return _error(f"sheet not found: {args.sheet}", 1)
+
+    worksheet = workbook[args.sheet]
+    added = []
+    for chart in charts:
+        chart_type = str(chart.get("type", "column")).lower()
+        if chart_type not in CHART_TYPES:
+            return _error(f"unsupported chart type: {chart_type}", 1)
+        if is_row_oriented(chart):
+            add_row_oriented_chart(worksheet, chart)
+        else:
+            office_cli._xlsx_add_chart(worksheet, chart)
+        added.append(
+            {
+                "type": chart_type,
+                "title": chart.get("title", ""),
+                "anchor": chart.get("anchor", "E2"),
+                "data": chart.get("data"),
+            }
+        )
+
+    out = Path(args.out).expanduser() if args.out else source.with_name(
+        f"{source.stem}-edited{source.suffix}"
+    )
+    out.parent.mkdir(parents=True, exist_ok=True)
+    workbook.save(str(out))
+    charts_on_sheet = len(worksheet._charts)
+    workbook.close()
+
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "input": str(source),
+                "output": str(out),
+                "sheet": args.sheet,
+                "charts_added": len(added),
+                "charts_on_sheet": charts_on_sheet,
+                "charts": added,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/assets/skills/office-spreadsheets/container_tools/add_image.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Place an image file on a worksheet at a cell anchor.
+
+Images are embedded copies: the workbook keeps the pixels it was given, so an
+image that later changes on disk does not update. Prefer a native chart or a
+table when the content is data; use an image only for logos, screenshots, and
+diagrams that have no cell representation.
+
+Examples:
+    add_image.py --input book.xlsx --sheet Cover --path logo.png --anchor B2
+    add_image.py --input book.xlsx --sheet Cover --path shot.png --anchor B10 --width 640
+
+Exit codes:
+  0  image embedded (the JSON on stdout reports the anchor and size)
+  1  refused: unknown sheet or unsupported image file
+  2  usage error or missing file
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(errors="replace")
+
+IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".tif", ".tiff", ".emf", ".wmf"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Embed an image on an .xlsx worksheet.")
+    parser.add_argument("--input", required=True, help="source workbook")
+    parser.add_argument("--out", help="destination workbook (default: <input>-edited.xlsx)")
+    parser.add_argument("--sheet", required=True, help="target worksheet")
+    parser.add_argument("--path", required=True, help="image file to embed")
+    parser.add_argument("--anchor", default="A1", help="top-left cell the image floats over")
+    parser.add_argument("--width", type=int, help="display width in pixels")
+    parser.add_argument("--height", type=int, help="display height in pixels")
+    return parser.parse_args()
+
+
+def _error(message: str, code: int) -> int:
+    print(json.dumps({"ok": False, "error": message}), file=sys.stderr)
+    return code
+
+
+def main() -> int:
+    args = parse_args()
+    source = Path(args.input).expanduser()
+    image_path = Path(args.path).expanduser()
+    if not source.is_file():
+        return _error(f"input file not found: {source}", 2)
+    if not image_path.is_file():
+        return _error(f"image file not found: {image_path}", 2)
+    if image_path.suffix.lower() not in IMAGE_SUFFIXES:
+        return _error(f"unsupported image type: {image_path.suffix}", 1)
+
+    try:
+        from openpyxl import load_workbook
+        from openpyxl.drawing.image import Image as XLImage
+    except ImportError as error:  # pragma: no cover - environment guard
+        return _error(f"openpyxl or Pillow missing: {error}", 2)
+
+    workbook = load_workbook(str(source))
+    if args.sheet not in workbook.sheetnames:
+        return _error(f"sheet not found: {args.sheet}", 1)
+
+    try:
+        image = XLImage(str(image_path))
+    except Exception as error:  # noqa: BLE001 - Pillow rejects unreadable files
+        return _error(f"cannot read image: {error}", 1)
+
+    if args.width:
+        image.width = args.width
+    if args.height:
+        image.height = args.height
+    workbook[args.sheet].add_image(image, args.anchor)
+
+    out = Path(args.out).expanduser() if args.out else source.with_name(
+        f"{source.stem}-edited{source.suffix}"
+    )
+    out.parent.mkdir(parents=True, exist_ok=True)
+    workbook.save(str(out))
+    workbook.close()
+
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "input": str(source),
+                "output": str(out),
+                "sheet": args.sheet,
+                "anchor": args.anchor,
+                "image": str(image_path),
+                "width": image.width,
+                "height": image.height,
+            },
+            indent=2,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())