dsh-office-kit 0.4.2 → 0.4.4

package/assets/skills/excel-live-control/domain_guidance/marketing_advertising.md

@@ -1,53 +1,52 @@
 # Marketing and advertising
 
-Campaign, funnel, lead, CRM and ad-performance data. The failures here are almost always
-grain, denominator or freshness — not arithmetic.
+Campaign, funnel, lead, CRM and ad-performance data. Failures here are grain, denominator or
+freshness — rarely arithmetic.
 
 ## Know what the export is
 
-- **Extract freshness vs analysis time.** An export pulled Tuesday and analysed Friday is
-  Tuesday's data. Record the extract date and the as-of date once, in the input area, and
-  do not compare a Friday figure with a Tuesday one as if the difference were performance.
-- **Channel setup.** A campaign may be split across an ad platform, a CRM and a billing
-  system. Name which one each figure comes from before combining them.
-- **Grain.** Daily rows are not campaign rows. Impressions are not sessions; clicks are not
+- **Freshness**: an export pulled Tuesday and analysed Friday is Tuesday's data. Record the
+  extract date and as-of date in the input area; do not read a Friday-vs-Tuesday difference as
+  performance.
+- **Channel setup**: a campaign may span an ad platform, a CRM and a billing system. Name the
+  source of each figure before combining them.
+- **Grain**: daily rows are not campaign rows. Impressions are not sessions; clicks are not
   leads; leads are not qualified leads; a pipeline total is not revenue.
-- **Denominators.** CTR uses impressions, CVR uses sessions or clicks depending on the
-  platform's definition, CPA uses conversions attributed that period. Carry the platform's
-  definition into the label; two vendors' "conversion rate" differ.
+- **Denominators**: CTR uses impressions; CVR uses sessions or clicks per the platform's
+  definition; CPA uses conversions attributed that period. Put the platform's definition in
+  the label — vendors' "conversion rate" differ.
 
 ## Layout
 
 - Name tabs by content and period: `Leads_Q1_2025`, `Pipeline Analysis`, `ROI Dashboard`.
-- Keep the raw import intact on its own sheet; clean in derived columns or a prepared
-  area, and record what you excluded or mapped (non-target region, test account,
-  renamed source) so the exclusion is visible.
+- Keep the raw import intact on its own sheet; clean in derived columns or a prepared area,
+  and record exclusions and mappings (non-target region, test account, renamed source).
 - One typed time-series date column with one format. Add an ISO helper column only when a
-  downstream import needs it, and label it as such.
+  downstream import needs it, labelled as such.
 - Targets and traffic lights only when the source supplies a target and a direction. No
-  invented targets, no green/amber/red on numbers nobody set a goal for.
-- Every dashboard figure traces back to a cell in the prepared data. If a number cannot be
-  traced, it does not go on the dashboard.
+  invented targets, no green/amber/red on goals nobody set.
+- Every dashboard figure traces back to a cell in the prepared data; otherwise it does not go
+  on the dashboard.
 
 ## Metrics
 
-- Define abbreviations where they are used (CPC, CPM, CPA, ROAS, MQL) — a legend on the
-  analysis sheet, not a glossary tab nobody opens.
-- Keep the comparison basis visible: week over week, month over month, or the same period
-  last year. Mixing bases across one chart is the most common misleading dashboard.
-- Attribution: say which model (last click, first click, linear, platform-reported) and
-  keep it consistent within a table. Platform-reported and analytics-reported conversions
-  never reconcile exactly; report both rather than forcing a match.
-- Charts only when they make a trend, a comparison or a funnel clearer than a table. A
-  chart of six categories is a table with extra steps.
+- Define abbreviations where used (CPC, CPM, CPA, ROAS, MQL) — a legend on the analysis sheet,
+  not a glossary tab nobody opens.
+- Keep the comparison basis visible: week over week, month over month, or same period last
+  year. Mixing bases in one chart is the most common misleading dashboard.
+- Attribution: state the model (last click, first click, linear, platform-reported) and keep
+  it consistent within a table. Platform- and analytics-reported conversions never reconcile
+  exactly; report both.
+- Charts only when they make a trend, comparison or funnel clearer than a table. Six
+  categories is a table with extra steps.
 
 ## Doing it live
 
-- Read first: `info` (which sheets, which used ranges, whether the user is mid-edit) then
+- Read first: `info` (sheets, used ranges, whether the user is mid-edit), then
   `read_range --formulas` across the block you will extend.
-- Append new periods as rows below the existing table and extend the table/conditional
-  formatting/chart source with it. Do not create a second table beside the first.
-- When a figure must be flagged for refresh (stale extract, missing platform), use the
-  amber input fill and a note in the cell beside it, not a colour nobody explained.
-- Verify with `read_range --formulas`: this is where a misaligned denominator shows up as a
-  rate that is off by a factor of ten.
+- Append new periods as rows below the table and extend the table, conditional formatting and
+  chart source with them. No second table beside the first.
+- For a refresh flag (stale extract, missing platform), use amber input fill plus a note in
+  the cell beside it, not an unexplained colour.
+- Verify with `read_range --formulas`; a misaligned denominator surfaces as a rate off by a
+  factor of ten.

package/assets/skills/excel-live-control/domain_guidance/scientific_research.md

@@ -1,53 +1,51 @@
 # Scientific research data
 
-The spreadsheet is often the only record of an experiment. Treat the observations as
-irreplaceable: a cleaned value that overwrote a raw measurement is data loss, and a live
-edit is one keystroke away from it.
+The spreadsheet is often the only record of an experiment. Treat observations as
+irreplaceable: a cleaned value that overwrote a raw measurement is data loss, and a live edit
+is one keystroke away.
 
 ## Keep the raw table raw
 
-- One flat table: one row per observation, one variable per column, one unit per column.
-  No merged cells, no multi-row headers, no calculation rows mixed into the data block.
-- Do not overwrite a measurement. Transformations live in separate columns (clearly headed
-  `log10(x)`, `normalised`) or in a separate processed block/sheet.
-- Record the cleaning: which rows were excluded and why, which values were imputed, which
-  units were converted. A protocol note on the sheet or a short note beside the block.
-- Missing observations stay visibly missing (blank or `n.a.` as the table's convention
-  dictates) — never silently zero-filled. Randomised and simulated values are labelled as
-  such; they are not observations.
+- One flat table: one row per observation, one variable per column, one unit per column. No
+  merged cells, no multi-row headers, no calculation rows inside the data block.
+- Never overwrite a measurement. Transformations go in separate columns (headed `log10(x)`,
+  `normalised`) or a separate processed block or sheet.
+- Record the cleaning: rows excluded and why, values imputed, units converted — in a protocol
+  note on or beside the sheet.
+- Missing observations stay visibly missing (blank or `n.a.`, per the table's convention);
+  never zero-fill silently. Label randomised and simulated values as such — they are not
+  observations.
 
 ## Presentation tables are a different object
 
-When the sheet is a report of the data rather than the data itself:
+When the sheet reports the data rather than holding it:
 
-- One type of data per column, units in the header (`Concentration (mg/L)`), never inside
-  the cell.
+- One type of data per column; units in the header (`Concentration (mg/L)`), never in the cell.
 - Never encode meaning only in colour or bold — add a labelled value column (`Flag:
-  excluded`, `Status: control`). A reader with a monochrome printout must still get the
-  full information.
-- Notes belong in a notes column, not in cell comments that a co-author will never see.
-- No merged cells in a table you expect anyone to sort or filter.
+  excluded`, `Status: control`). A monochrome printout must still carry the meaning.
+- Notes belong in a notes column, not in cell comments a co-author will never see.
+- No merged cells in a table anyone will sort or filter.
 
 ## Analysis
 
-- Prefer a transparent formula to a clever one. Someone has to defend this number in a
-  review six months from now.
-- Show the calculation steps: the intermediate columns are the evidence. Hiding them in a
-  single formula makes the result unfalsifiable.
-- A circular reference or iterative calculation is off-limits unless the user asks for it
-  and documents it. A simulation's random seed and method are part of the result.
-- Distinguish measurement, derived value, flag and assumption — by label, not by font
-  colour alone.
-- If the design of the analysis changes (an exclusion added, a normalisation changed), say
-  so in the reply. A quiet change to a denominator rewrites the conclusion.
+- A transparent formula beats a clever one; someone must defend the number in review six
+  months from now.
+- Show the steps: intermediate columns are the evidence; one formula makes the result
+  unfalsifiable.
+- Circular references and iterative calculation are off-limits unless the user asks and
+  documents it. A simulation's random seed and method are part of the result.
+- Distinguish measurement, derived value, flag and assumption by label, not by font colour
+  alone.
+- If the design changes (exclusion added, normalisation changed), say so in the reply. A
+  quiet denominator change rewrites the conclusion.
 
 ## Doing it live
 
 - Before touching anything: `info`, then `read_range --formulas --display` on the block.
-  Raw data and report blocks are usually on different sheets; confirm which is which.
-- Append observations as rows at the bottom of the table, extend any table object to cover
-  them, and keep the header row exactly as it is.
-- Verify with `read_range --formulas`; the `errors` array catches the `#DIV/0!` and
-  `#VALUE!` that appear when a text value lands in a numeric column.
-- Never delete rows from the middle of a data table; a delete shifts every downstream
-  formula and every chart range with it.
+  Raw data and report blocks usually sit on different sheets; confirm which is which.
+- Append observations as bottom rows, extend any table object to cover them, leave the header
+  row untouched.
+- Verify with `read_range --formulas`; the `errors` array catches the `#DIV/0!` and `#VALUE!`
+  that appear when text lands in a numeric column.
+- Never delete rows from the middle of a data table; a delete shifts every downstream formula
+  and chart range.

package/assets/skills/excel-live-control/references/office-automation.md

@@ -1,13 +1,10 @@
 # The COM object model behind a live edit
 
-What this skill talks to is not a file. It is an out-of-process COM server that happens
-to own a window: every property read and every write is a remote call across process
-boundaries, and every object you hold is a proxy that re-reads state when you ask it.
-That explains most of the rules below.
+The target is an out-of-process COM server that owns a window. Each property read or write
+is a remote call; each object is a proxy that re-reads state. That explains most rules here.
 
 `container_tools/live_excel.py` wraps the common cases. Read this when the CLI has no verb
-for what the task needs, when a call fails in a way the JSON does not explain, or when you
-are extending the tool.
+for the task, a failure is unexplained, or you extend the tool.
 
 ## Reaching the running instance
 
@@ -15,36 +12,33 @@ are extending the tool.
 $app = [Runtime.InteropServices.Marshal]::GetActiveObject('Excel.Application')
 ```
 
-- This is the only supported way to find a *running* instance. `New-Object -ComObject
-  Excel.Application` creates a new, invisible one — never do that for user work.
-- It exists in Windows PowerShell 5.1 (`powershell.exe`). PowerShell 7 (`pwsh`) removed
-  the method, which is why the tool shells out to `powershell.exe` and not `pwsh`.
-- With nothing running it raises `0x800401E3 (MK_E_UNAVAILABLE)`. That is the signal to
-  ask the user to open the workbook, not to launch anything.
-- WPS Spreadsheets registers both `Ket.Application` and `Excel.Application`, so a
-  successful attach to `Excel.Application` does not prove Microsoft Excel is running.
-  `Application.Name` and `Application.Version` are worse than useless here — WPS reports
-  `Microsoft Excel` / `12.0`. Infer the product from `Application.Path`.
-- The running-object table is per user session and survives the process that created the
-  instance. A hidden instance launched for a self-test stays attachable from later calls;
-  it stays invisible until something shows it, and it leaks until `Application.Quit()`.
+- The only supported way to find a running instance. `New-Object -ComObject
+  Excel.Application` creates a new invisible one; never use it for user work.
+- Only in Windows PowerShell 5.1 (`powershell.exe`); PowerShell 7 (`pwsh`) removed it,
+  which is why the tool shells out to `powershell.exe`.
+- Nothing running raises `0x800401E3 (MK_E_UNAVAILABLE)`. Ask the user to open the
+  workbook; launch nothing.
+- WPS registers `Ket.Application` and `Excel.Application`, so attaching does not prove
+  Microsoft Excel. `Application.Name`/`Version` are useless here (WPS reports `Microsoft
+  Excel` / `12.0`). Infer the product from `Application.Path`.
+- The running-object table is per user session and outlives the creating process. A hidden
+  self-test instance stays attachable, invisible until shown, and leaks until
+  `Application.Quit()`.
 
 ## Addressing
 
 `Application` → `Workbooks` → `Workbook` → `Sheets` → `Worksheet` → `Range`.
 
 - Collections are **1-based**: `$book.Sheets.Item(1)`. `Item(0)` throws.
-- `$sheet.Cells` is the whole sheet; `$sheet.UsedRange` is the rectangle that has content
-  or formatting. `UsedRange` is not trimmed by deleting a value in its last cell; treat
-  it as a hint for what to read, never as the boundary of an edit.
-- A1 strings: `A1`, `B4:D9`, `$B$14`, `Sheet1!A1:C9`, `'Build Detail'!E14` (quote sheet
-  names containing spaces). `Range.Address($row_absolute, $column_absolute)` prints one
-  back, e.g. `$r.Address(0,0)` gives `A1:C3`. Prefer reporting the absolute form the user
-  can paste into the Name Box.
-- Sheet names are case-insensitive in .NET-side matching but must match for COM:
-  `$book.Sheets.Item('Build')` throws on `build`. Use `Worksheet.Name` for the exact
-  spelling.
-- Multi-area ranges (`A1:A5,C1:C5`) exist; the tool refuses them for writes because a
+- `$sheet.Cells` is the whole sheet; `$sheet.UsedRange` is the rectangle holding content or
+  formatting. Clearing the last cell does not shrink it: a read hint, never an edit
+  boundary.
+- A1 strings: `A1`, `B4:D9`, `$B$14`, `Sheet1!A1:C9`, `'Build Detail'!E14` (quote names
+  with spaces). `$r.Address(0,0)` gives `A1:C3`; report the absolute form the user can
+  paste into the Name Box.
+- Sheet-name matching is case-insensitive in .NET but exact for COM:
+  `$book.Sheets.Item('Build')` throws on `build`. Use `Worksheet.Name` for spelling.
+- Multi-area ranges (`A1:A5,C1:C5`) exist; the tool refuses them for writes because one
   rectangular `Value2` assignment cannot fill them.
 
 ## Cells: what you write and what comes back
@@ -52,156 +46,136 @@ $app = [Runtime.InteropServices.Marshal]::GetActiveObject('Excel.Application')
 | Property | Use it for | Reads back |
 | --- | --- | --- |
 | `Range.Value2` | every value: numbers, text, dates (as serials), booleans, arrays | typed scalars / `Object[,]` |
-| `Range.Formula` | formulas in A1 notation; also the way to read them back | `String`, e.g. `=SUM(B2:B9)` |
+| `Range.Formula` | formulas in A1 notation; also how to read them back | `String`, e.g. `=SUM(B2:B9)` |
 | `Range.FormulaR1C1` | fills where you think in offsets | `String` |
-| `Range.Text` | the *displayed* string (after number format) | per-cell only |
-
-- **`Value2` is type-preserving and locale-blind.** Assign a `Double` and the cell is a
-  number; assign a `String` and it is text — except that the application may *parse* a
-  string that looks like a date, a currency amount, or `=1+1`. Writing `"2026-01-31"`
-  through `Value2` produced the serial `46053` in a date-formatted cell. If the user meant
-  the literal text, store the serial (or the number) and set a number format, or prefix
-  the apostrophe; do not rely on the parse.
-- **`$null` empties a cell.** That is the supported way to clear one value inside a block
-  you are writing.
-- A multi-cell read returns a 2-D `Object[,]` with **1-based** indices. A single cell
+| `Range.Text` | the displayed string, after number format | per-cell only |
+
+- **`Value2` preserves type and ignores locale.** A `Double` stays a number, a `String`
+  stays text — unless the app parses it as a date, currency, or `=1+1`. `"2026-01-31"`
+  written through `Value2` produced serial `46053` in a date-formatted cell. For literal
+  text, store the serial/number and set a number format, or prefix the apostrophe. Never
+  rely on the parse.
+- **`$null` empties a cell**, the supported way to clear one value inside a written block.
+- A multi-cell read returns a 2-D `Object[,]` with **1-based** indices; a single cell
   returns a scalar, so code that always indexes `[1,1]` fails on one-cell ranges.
-- **Errors come back as integers.** A live value of `#DIV/0!` is the Int32 SCODE
-  `-2146826281`; `#VALUE!` is `-2146826273`, `#REF!` `-2146826265`, `#NAME?`
-  `-2146826259`, `#NUM!` `-2146826252`, `#N/A` `-2146826246`. In WPS,
-  `WorksheetFunction.IsError` returns `False` for them and `SpecialCells(16)` throws, so
-  the practical test is "is this value an Int32?" — then read `Range.Text`,
-  `Range.Formula` and `Range.Address(0,0)` for that cell alone.
-- `Range.Text` is a per-cell property. On a multi-cell range WPS returns `DBNull`, so the
-  tool reads it cell by cell (that is why `--display` is capped).
-- **Assigning one formula to a range fills it with relative adjustment.** Setting
-  `A1:A3` to `=B1` gives `=B1`, `=B2`, `=B3`. This is the cheap way to fill a column; it
-  is also the way to accidentally create a formula you did not intend when the target is
-  more than one cell.
-- Dates are serials (`days since 1899-12-30`, the 1900 date system). `DateSerial(y,m,d)`
-  gives the number; a `NumberFormat` gives the look.
-- Formulas are text. There is no calculation on write; the value updates when the
-  application recalculates, which is why `recalc` exists.
+- **Errors are integers.** `#DIV/0!` is Int32 SCODE `-2146826281`; `#VALUE!` `-2146826273`,
+  `#REF!` `-2146826265`, `#NAME?` `-2146826259`, `#NUM!` `-2146826252`, `#N/A`
+  `-2146826246`. WPS returns `False` from `WorksheetFunction.IsError` and throws on
+  `SpecialCells(16)`, so test "is this an Int32?", then read `Range.Text`,
+  `Range.Formula`, `Range.Address(0,0)` for that cell alone.
+- `Range.Text` is per-cell; on a multi-cell range WPS returns `DBNull`, so the tool reads
+  cell by cell (hence the `--display` cap).
+- **One formula assigned to a range fills with relative adjustment**: `A1:A3` = `=B1`
+  gives `=B1`, `=B2`, `=B3`. Cheap for a column, and how unintended formulas appear on
+  multi-cell targets.
+- Dates are serials (`days since 1899-12-30`, 1900 system). `DateSerial(y,m,d)` gives the
+  number; `NumberFormat` gives the look.
+- Formulas are text. Nothing calculates on write; values update on recalc, which is why
+  `recalc` exists.
 
 ## Number formats
 
-`Range.NumberFormat` takes format *codes*, not locales: `#,##0`, `#,##0.00`, `0.0%`,
-`"$"#,##0.00`, `mmm-yy`, `d-mmm`, `@`. Use invariant ASCII codes — the dot is always the
-decimal point inside the code, whatever the machine's `Application.DecimalSeparator`
-says. WPS returns empty strings for `DecimalSeparator`/`ThousandsSeparator`, so do not
-read locale from the app and do not build codes from locale data.
-
-- Format is display only. The stored value keeps full precision; never round data to make
-  it read right.
-- One format per column. Mixing `#,##0` and `#,##0.00` down a single column is the most
-  common visual defect in a live sheet.
-- Percentages carry precision: one decimal for analytical tables, zero for dashboards,
-  two when the differences are small. The code encodes that: `0.0%`, `0%`, `0.00%`.
-- `###` in the window means the column is too narrow for the formatted value, not that
-  the value is wrong. Widen with `ColumnWidth` (points-ish, default about 8.43) or
-  `EntireColumn.AutoFit()`, and check the result with `--display`.
+`Range.NumberFormat` takes codes, not locales: `#,##0`, `#,##0.00`, `0.0%`, `"$"#,##0.00`,
+`mmm-yy`, `d-mmm`, `@`. Use invariant ASCII; the dot is always the decimal point inside a
+code, whatever `Application.DecimalSeparator` says. WPS returns empty
+`DecimalSeparator`/`ThousandsSeparator`: never read locale from the app or build codes from
+locale data.
+
+- Format is display only; values keep full precision. Never round data to make it read
+  right.
+- One format per column; mixing `#,##0` and `#,##0.00` down a column is the commonest
+  visual defect.
+- Precision belongs in the code: `0.0%` for analytical tables, `0%` for dashboards,
+  `0.00%` when differences are small.
+- `###` means too narrow, not wrong. Widen with `ColumnWidth` (default ~8.43) or
+  `EntireColumn.AutoFit()`, then check with `--display`.
 
 ## Colour is BGR
 
-`Interior.Color` and `Font.Color` are OLE colour longs written `0xBBGGRR`, while every
-spec in this repo is `#RRGGBB`. Convert explicitly:
+`Interior.Color` and `Font.Color` are OLE longs `0xBBGGRR`; specs are `#RRGGBB`:
 
 ```
 ole = red + green * 256 + blue * 65536        # #RRGGBB -> BGR long
 ```
 
-`#C00000` becomes `192`; a pure blue fill becomes `16711680`. Setting `ColorIndex = -4142`
-removes a fill (`Interior.Color` then reads back `16777215`). Theme colours and tints are
-not addressable this way: if the workbook's palette matters, use the workbook's own
-existing colours rather than inventing one.
+`#C00000` becomes `192`; pure blue fill is `16711680`. `ColorIndex = -4142` removes a fill
+(`Interior.Color` then reads `16777215`). Theme colours and tints are not addressable;
+reuse existing workbook colours.
 
 ## Font, borders, alignment, layout
 
 - `Range.Font`: `Name`, `Size`, `Bold`, `Italic`, `Color`, `Underline`, `Strikethrough`.
-  One family across the sheet; the repo default is Helvetica Neue → Helvetica → Arial →
-  Aptos, whichever the workbook already uses.
-- `Range.Borders.Item(index)`: 7 left, 8 top, 9 bottom, 10 right; `LineStyle` (1 continuous),
-  `Weight` (2 thin), `Color`. `BorderAround(1, 2)` draws a thin outline in one call.
-- `HorizontalAlignment` / `VerticalAlignment` take `xlHAlign*` constants (`-4131` left,
-  `-4108` center, `-4152` right) and `xlVAlign*` (`-4160` top, `-4108` center, `-4104`
-  bottom). The tool maps the readable names for you.
-- `Range.Merge()`, `Range.UnMerge()`, `Range.WrapText`, `Range.IndentLevel`,
-  `EntireColumn.ColumnWidth`, `Tab.Color`, `Rows.Hidden`.
-- `FreezePanes` lives on `Window`, not on the sheet, and did not stick on a hidden
-  instance in WPS. The tool deliberately has no freeze-pane verb; if the user needs panes
-  frozen, tell them to do it, or do it visibly in a shown window.
-- Whole-sheet `AutoFit` and `Select`/`Activate` are traps: they change the user's view,
-  can take seconds on a large sheet, and `ScreenUpdating` does not hide the flicker from a
-  user who is looking at the window.
+  One family per sheet: Helvetica Neue → Helvetica → Arial → Aptos, whichever the workbook
+  uses.
+- `Range.Borders.Item(index)`: 7 left, 8 top, 9 bottom, 10 right; `LineStyle` (1
+  continuous), `Weight` (2 thin), `Color`. `BorderAround(1, 2)` draws a thin outline in one
+  call.
+- `HorizontalAlignment` takes `xlHAlign*` (`-4131` left, `-4108` center, `-4152` right);
+  `VerticalAlignment` takes `xlVAlign*` (`-4160` top, `-4108` center, `-4104` bottom). The
+  tool maps readable names.
+- Also: `Merge()`, `UnMerge()`, `WrapText`, `IndentLevel`, `EntireColumn.ColumnWidth`,
+  `Tab.Color`, `Rows.Hidden`.
+- `FreezePanes` lives on `Window` and did not stick on a hidden WPS instance. No freeze
+  verb: tell the user, or do it visibly.
+- Whole-sheet `AutoFit` and `Select`/`Activate` change the user's view, can take seconds,
+  and `ScreenUpdating` does not hide the flicker.
 
 ## Objects beside the cells
 
-- **Tables**: `$sheet.ListObjects.Add(1, $range, [Type]::Missing, $has_headers)` creates
-  a `ListObject`. PowerShell cannot reproduce VBA's empty argument positions — pass
-  `[Type]::Missing` for the `Destination` slot. Created tables get localized default
-  names (`表1`), so name them. With `has_headers = 0` the application *generates a header
-  row above the data*, which shifts the values down one row and makes the table one row
-  taller than the range you named. Extend an existing table with `ListObject.Resize`
-  rather than adding a second one over the same cells.
+- **Tables**: `$sheet.ListObjects.Add(1, $range, [Type]::Missing, $has_headers)`.
+  PowerShell cannot reproduce VBA's empty argument positions, so pass `[Type]::Missing` for
+  `Destination`. Tables get localized default names (`表1`); name them. `has_headers = 0`
+  makes the app generate a header row above the data, shifting values down and making the
+  table one row taller than the range. Extend with `ListObject.Resize`, never a second
+  table.
 - **Charts**: `$sheet.ChartObjects().Add(left, top, width, height)` → `.Chart` →
-  `.SetSourceData($range)` + `.ChartType`. `HasTitle`/`ChartTitle.Text` set the title.
-  `ChartType` numbers: column 51, stacked column 52, bar 57, stacked bar 58, line 4, line
-  with markers 65, area 1, stacked area 76, pie 5, doughnut -4120, scatter -4169,
-  scatter with lines 74. A chart over an empty range renders blank — check the source
-  cells before blaming the chart.
-- **Shapes**: `$sheet.Shapes.AddShape(...)`, `AddTextbox`, `AddPicture`. They float over
-  cells and are not part of the used range; anchor them to a cell (`TopLeftCell`) so they
-  move with the data.
-- **Pivots**: `PivotTables`, `PivotFields`. Read and report them; never rebuild one
-  through COM unless the user asked for a new pivot — the field layout is not recoverable
-  from a failed attempt.
-- **Names**: `$workbook.Names`, `Range.Name`. Names break when you delete the cells they
-  point at (`#REF!` in the name), so a rename or a row delete is a contract change.
-- **Conditional formats**: `Range.FormatConditions`. Appending a condition to a range
-  that already has one edits the *existing* set; a "fix" here can silently change rules
-  the user depends on. Read first, and keep the range bounded.
-- **Validation**: `Range.Validation` — same rule. Read the existing rule before writing a
-  new one.
+  `.SetSourceData($range)` + `.ChartType`; `HasTitle`/`ChartTitle.Text` set the title.
+  Types: column 51, stacked column 52, bar 57, stacked bar 58, line 4, line with markers
+  65, area 1, stacked area 76, pie 5, doughnut -4120, scatter -4169, scatter with lines 74.
+  A chart over an empty range renders blank; check the source cells.
+- **Shapes**: `Shapes.AddShape(...)`, `AddTextbox`, `AddPicture`. They float over cells, sit
+  outside the used range, and need `TopLeftCell` anchoring to move with data.
+- **Pivots**: `PivotTables`, `PivotFields`. Read and report; never rebuild through COM
+  unless asked — a failed attempt loses the layout.
+- **Names**: `$workbook.Names`, `Range.Name`. Deleting their cells breaks names (`#REF!`),
+  so a rename or row delete is a contract change.
+- **Conditional formats**: `Range.FormatConditions`. Appending to a range with an existing
+  condition edits that set; read first, keep the range bounded.
+- **Validation**: `Range.Validation`; read the existing rule before writing.
 
 ## Calculation and freshness
 
-- `Application.Calculation`: `-4105` automatic, `-4135` manual. A workbook left in manual
-  mode shows stale numbers after your edit; `recalc` runs `CalculateFull` across every
-  open workbook and reports the mode it found.
-- `CalculateFull` recalculates dependencies, not just the active sheet. `CalculateFullRebuild`
-  rebuilds the dependency tree — use it only when a value looks impossible, because it is
-  slow on a large model.
-- Iterative calculation (`Application.Iteration`) is off by default. Circular references
-  that "worked" for the user are a sign it was on; do not turn it on to make an edit
-  succeed.
+- `Application.Calculation`: `-4105` automatic, `-4135` manual. Manual mode shows stale
+  numbers after an edit; `recalc` runs `CalculateFull` on every open workbook and reports
+  the mode.
+- `CalculateFull` recalculates dependencies, not just the active sheet.
+  `CalculateFullRebuild` rebuilds the tree; use it only when a value looks impossible — it
+  is slow on large models.
+- Iteration (`Application.Iteration`) is off by default. Circular references that "worked"
+  mean it was on; do not enable it to make an edit succeed.
 
 ## Latency, failures, retries
 
-- Every property access is an RPC. A trivial call (`info`, three reads) took about 1.2–1.5 s
-  on this host; a call that formats 100 cells one at a time can take tens of seconds.
-  **Batch**: one `write_range` for a block, one `style_range` for a range, one `set_formula`
-  for a column. Do not loop calls per cell.
-- The default timeout in the tool is 180 s. Raising it is legitimate for a big paste;
-  lowering it below a second will fail on a busy application.
-- Failures you will meet:
-  - `0x800401E3` — nothing is running. Remediate by asking the user to open the workbook.
-  - `0x8001010A` (RPC_E_SERVERCALL_RETRYLATER) — the application is busy (a modal dialog,
-    a recalculation, a user dragging a window). Read again, and if it persists tell the
-    user there is a dialog blocking the app.
-  - "Object required" / a stale proxy — usually after the user closed the workbook you
-    were holding. Re-attach by name; never reuse the old object.
-  - A method that exists in Excel raising "does not contain a method named …" in WPS — the
-    WPS object model is a subset. Fall back to a simpler route (formatting via
-    `Value2`/`NumberFormat` instead of a specialised helper).
-- **Nothing is transactional.** A call that fails halfway leaves the cells it already
-  wrote. The retry protocol is: `read_range` the block, compare with intent, write only
-  what is missing or wrong. Replaying the same batch is how a live document gets
-  duplicated rows.
+- Every property access is an RPC. `info` plus three reads took 1.2–1.5 s here; formatting
+  100 cells one at a time can take tens of seconds. **Batch**: one `write_range` per block,
+  one `style_range` per range, one `set_formula` per column. Never loop per cell.
+- Default timeout is 180 s. Raising it is fine for a big paste; below 1 s fails on a busy
+  app.
+- Failures you meet:
+  - `0x800401E3` — nothing running. Ask the user to open the workbook.
+  - `0x8001010A` (RPC_E_SERVERCALL_RETRYLATER) — app busy (dialog, recalculation, dragged
+    window). Read again; if it persists, tell the user a dialog is blocking it.
+  - "Object required" / stale proxy — usually the workbook was closed. Re-attach by name;
+    never reuse the old object.
+  - An Excel method raising "does not contain a method named …" in WPS: the WPS model is a
+    subset. Fall back to a simpler route (formatting via `Value2`/`NumberFormat`).
+- **Nothing is transactional.** A half-failing call leaves written cells. Retry:
+  `read_range` the block, compare with intent, write only what is missing or wrong.
+  Replaying a batch duplicates rows.
 
 ## The one rule that outranks the rest
 
-A live edit mutates a document the user is looking at and may have unsaved changes in.
-**Read and diff before writing.** `read_range` the target with `--formulas`; note whether
-`info` says the workbook is `saved: false`; then make the smallest write that satisfies the
-request. If the diff shows values you did not expect, stop and ask — the user's unsaved
-work is more important than finishing the task.
+A live edit mutates a document the user is looking at, possibly with unsaved changes.
+**Read and diff before writing.** `read_range` the target with `--formulas`; note
+`saved: false` from `info`; then make the smallest write that satisfies the request. If the
+diff shows unexpected values, stop and ask — unsaved user work outranks finishing the task.