dsh-office-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Write values or formulas into specific cells of an existing workbook.
+
+Only the named cells change. Values are parsed with `json.loads` when they look
+like JSON, so `42`, `3.5`, `true`, `null`, and `["a","b"]` become numbers and
+structured values, while anything else (`hello`, `=SUM(B2:B9)`, `2026-01-31`) is
+written as text. A leading `=` is a formula string and is stored as a formula.
+
+Examples:
+    set_cells.py --input book.xlsx --sheet Model --set B3=0.07 --set B4="=B2*(1+B3)"
+    set_cells.py --input book.xlsx --spec cells.json
+
+    cells.json: {"sheet": "Model", "cells": {"B3": 0.07, "D9": "=SUM(D2:D8)"}}
+        or:    [{"sheet": "Model", "cells": {...}}, {"sheet": "Data", "cells": {...}}]
+
+Exit codes:
+  0  cells written (the JSON on stdout lists them)
+  1  refused: unknown sheet or an unparseable assignment
+  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")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Write values or formulas into specific cells of an .xlsx workbook.",
+    )
+    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 sheet for --set assignments")
+    parser.add_argument("--set", action="append", default=[], metavar="A1=VALUE", help="assign one cell")
+    parser.add_argument("--spec", help="JSON file with sheet/cells assignments")
+    return parser.parse_args()
+
+
+def _error(message: str, code: int) -> int:
+    print(json.dumps({"ok": False, "error": message}), file=sys.stderr)
+    return code
+
+
+def parse_value(raw: str):
+    try:
+        return json.loads(raw)
+    except (TypeError, ValueError):
+        return raw
+
+
+def assignments(args: argparse.Namespace) -> list[tuple[str, dict[str, object]]]:
+    """Return [(sheet, {cell: value})] from --spec and --set, in that order."""
+    batches: list[tuple[str, dict[str, object]]] = []
+    if args.spec:
+        payload = json.loads(Path(args.spec).expanduser().read_text(encoding="utf-8-sig"))
+        items = payload if isinstance(payload, list) else [payload]
+        for item in items:
+            if not isinstance(item, dict):
+                raise ValueError("--spec items must be objects with sheet and cells")
+            sheet = item.get("sheet")
+            cells = item.get("cells")
+            if not isinstance(sheet, str) or not isinstance(cells, dict):
+                raise ValueError("--spec needs {sheet, cells: {A1: value}}")
+            batches.append((sheet, dict(cells)))
+    if args.set:
+        if not args.sheet:
+            raise ValueError("--set needs --sheet")
+        cells: dict[str, object] = {}
+        for pair in args.set:
+            if "=" not in pair:
+                raise ValueError(f"--set expects A1=VALUE, got: {pair}")
+            address, raw = pair.split("=", 1)
+            cells[address.strip().upper()] = parse_value(raw)
+        batches.append((args.sheet, cells))
+    if not batches:
+        raise ValueError("nothing to do: pass --set A1=VALUE with --sheet, or --spec")
+    return batches
+
+
+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:
+        from openpyxl import load_workbook
+    except ImportError as error:  # pragma: no cover - environment guard
+        return _error(f"openpyxl missing: {error}", 2)
+
+    try:
+        batches = assignments(args)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        return _error(str(error), 1)
+
+    try:
+        workbook = load_workbook(str(source))
+    except Exception as error:  # noqa: BLE001
+        return _error(f"cannot read workbook: {error}", 2)
+
+    written: list[dict[str, object]] = []
+    for sheet, cells in batches:
+        if sheet not in workbook.sheetnames:
+            return _error(f"sheet not found: {sheet}", 1)
+        worksheet = workbook[sheet]
+        for address, value in cells.items():
+            worksheet[str(address)] = value
+            written.append({"sheet": sheet, "cell": str(address), "value": value})
+
+    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), "written": written},
+            ensure_ascii=False,
+            indent=2,
+            default=str,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Add, delete, rename, or reorder worksheets in a workbook.
+
+Sheet names are referenced by formulas, charts, and defined names, so renaming
+a sheet rewrites nothing: every reference to the old name breaks. Prefer adding
+a sheet over renaming one that formulas point at.
+
+Examples:
+    sheet_ops.py --input book.xlsx --add Checks
+    sheet_ops.py --input book.xlsx --rename Sheet1=Assumptions
+    sheet_ops.py --input book.xlsx --delete Scratch --delete Notes
+    sheet_ops.py --input book.xlsx --order "Outputs,Assumptions,Build,Inputs"
+
+Exit codes:
+  0  done (the JSON on stdout lists the resulting sheet order)
+  1  refused: unknown sheet, duplicate name, or an attempt to delete the last sheet
+  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")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Add, delete, rename, or reorder worksheets in an .xlsx workbook.",
+    )
+    parser.add_argument("--input", required=True, help="source workbook")
+    parser.add_argument("--out", help="destination workbook (default: <input>-edited.xlsx)")
+    parser.add_argument("--add", action="append", default=[], metavar="NAME", help="create sheet NAME")
+    parser.add_argument("--delete", action="append", default=[], metavar="NAME", help="remove sheet NAME")
+    parser.add_argument("--rename", action="append", default=[], metavar="OLD=NEW", help="rename a sheet")
+    parser.add_argument(
+        "--order",
+        metavar="A,B,C",
+        help="move these sheets to the front in this order; unlisted sheets keep their order",
+    )
+    return parser.parse_args()
+
+
+def _error(message: str, code: int) -> int:
+    print(json.dumps({"ok": False, "error": message}), file=sys.stderr)
+    return code
+
+
+def default_out(source: Path) -> Path:
+    return source.with_name(f"{source.stem}-edited{source.suffix}")
+
+
+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:
+        from openpyxl import load_workbook
+    except ImportError as error:  # pragma: no cover - environment guard
+        return _error(f"openpyxl missing: {error}", 2)
+
+    try:
+        workbook = load_workbook(str(source))
+    except Exception as error:  # noqa: BLE001 - any unreadable file is reported the same way
+        return _error(f"cannot read workbook: {error}", 2)
+
+    actions: list[str] = []
+    try:
+        for name in args.add:
+            if name in workbook.sheetnames:
+                raise ValueError(f"sheet already exists: {name}")
+            workbook.create_sheet(str(name)[:31])
+            actions.append(f"added {name}")
+
+        for pair in args.rename:
+            if "=" not in pair:
+                raise ValueError(f"--rename expects OLD=NEW, got: {pair}")
+            old, new = pair.split("=", 1)
+            if old not in workbook.sheetnames:
+                raise ValueError(f"sheet not found: {old}")
+            if new in workbook.sheetnames:
+                raise ValueError(f"sheet already exists: {new}")
+            workbook[old].title = str(new)[:31]
+            actions.append(f"renamed {old} -> {new}")
+
+        for name in args.delete:
+            if name not in workbook.sheetnames:
+                raise ValueError(f"sheet not found: {name}")
+            if len(workbook.sheetnames) == 1:
+                raise ValueError("refusing to delete the last sheet; a workbook needs at least one")
+            workbook.remove(workbook[name])
+            actions.append(f"deleted {name}")
+
+        if args.order:
+            wanted = [part.strip() for part in args.order.split(",") if part.strip()]
+            missing = [name for name in wanted if name not in workbook.sheetnames]
+            if missing:
+                raise ValueError(f"unknown sheet in --order: {', '.join(missing)}")
+            rest = [name for name in workbook.sheetnames if name not in wanted]
+            workbook._sheets = [workbook[name] for name in wanted + rest]
+            actions.append("reordered " + ", ".join(wanted + rest))
+    except ValueError as error:
+        return _error(str(error), 1)
+
+    out = Path(args.out).expanduser() if args.out else default_out(source)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    names = list(workbook.sheetnames)
+    workbook.save(str(out))
+    workbook.close()
+
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "input": str(source),
+                "output": str(out),
+                "sheetnames": names,
+                "actions": actions,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Apply number formats, fonts, fills, and alignment to existing cells.
+
+The style vocabulary is the helper CLI's, so a style written here behaves exactly
+like one written at create time: `bold`, `italic`, `size`, `color` (hex), `fill`
+(hex), `number_format`, `align` (left/center/right).
+
+Examples:
+    style_cells.py --input book.xlsx --sheet Model --range B11:B14 \
+        --style '{"number_format": "#,##0"}'
+    style_cells.py --input book.xlsx --sheet Pipeline --range A1:G1 \
+        --style '{"bold": true, "fill": "FF1F3864", "color": "FFFFFFFF", "align": "center"}'
+    style_cells.py --input book.xlsx --spec styles.json
+
+    styles.json: {"sheet": "Model", "styles": {"A11:B11": {"bold": true}, "C11:C14": {"number_format": "0.0%"}}}
+
+Only cells covered by the given ranges change; neighbouring cells keep their
+existing formatting.
+
+Exit codes:
+  0  styles applied (the JSON on stdout lists the ranges and styles)
+  1  refused: unknown sheet, bad range, or no style given
+  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]
+
+
+def load_office_cli():
+    """Import the helper CLI's style helpers so both paths format identically."""
+    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="Apply number formats, fonts, fills, and alignment to cells in an .xlsx workbook.",
+    )
+    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 sheet for --range/--style")
+    parser.add_argument("--range", action="append", default=[], metavar="A1:B2", help="cell or range to style")
+    parser.add_argument("--style", help="JSON style object applied to every --range")
+    parser.add_argument("--spec", help="JSON file with sheet/styles assignments")
+    return parser.parse_args()
+
+
+def _error(message: str, code: int) -> int:
+    print(json.dumps({"ok": False, "error": message}), file=sys.stderr)
+    return code
+
+
+def assignments(args: argparse.Namespace) -> list[tuple[str, dict[str, dict[str, object]]]]:
+    batches: list[tuple[str, dict[str, dict[str, object]]]] = []
+    if args.spec:
+        payload = json.loads(Path(args.spec).expanduser().read_text(encoding="utf-8-sig"))
+        items = payload if isinstance(payload, list) else [payload]
+        for item in items:
+            if not isinstance(item, dict) or not isinstance(item.get("styles"), dict):
+                raise ValueError("--spec items need {sheet, styles: {range: style}}")
+            batches.append((str(item.get("sheet", "")), dict(item["styles"])))
+    if args.range:
+        if not args.sheet or not args.style:
+            raise ValueError("--range needs both --sheet and --style")
+        style = json.loads(args.style)
+        if not isinstance(style, dict):
+            raise ValueError("--style must be a JSON object")
+        batches.append((args.sheet, {address: style for address in args.range}))
+    if not batches:
+        raise ValueError("nothing to do: pass --range with --style, or --spec")
+    return batches
+
+
+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:
+        batches = assignments(args)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        return _error(str(error), 1)
+
+    workbook = load_workbook(str(source))
+    applied: list[dict[str, object]] = []
+    for sheet, styles in batches:
+        if sheet not in workbook.sheetnames:
+            return _error(f"sheet not found: {sheet}", 1)
+        worksheet = workbook[sheet]
+        for address, style in styles.items():
+            if not isinstance(style, dict):
+                return _error(f"style for {address} must be an object", 1)
+            cells = list(office_cli._xlsx_cells(worksheet, str(address).upper()))
+            for cell in cells:
+                office_cli._xlsx_apply_style(cell, style)
+            applied.append({"sheet": sheet, "range": str(address).upper(), "cells": len(cells), "style": style})
+
+    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), "applied": applied}, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

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

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

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

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

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

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

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