dsh-office-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,86 @@
+# Financial models
+
+Financial modelling has a short list of distinctions that decide whether a sheet is
+right, and a live edit makes each of them visible to a user who is watching.
+
+## The distinctions that matter
+
+| Looks similar | Actually different |
+| --- | --- |
+| Revenue (earned) | Collections (cash received) — timing, bad debt, deferred revenue |
+| Payroll expense | Cash paid to employees — accruals, timing, employer costs |
+| Capex | Depreciation / amortisation — cash out once, expense over life |
+| Earnings | Cash flow — working capital, non-cash items, financing |
+| Budget | Forecast — one is a target, the other an expectation; never mix them silently |
+
+Also, before typing a number: which fiscal calendar, which horizon (monthly / quarterly /
+annual), and which grain (total company, segment, product)? A number without those three
+is not a model input.
+
+Actuals and forecast must be visibly different (a divide, a label, a different fill). The
+reader has to know where history stops.
+
+## Schedules
+
+Build a driver schedule per line, then a statement, then the output. Each step is a range
+the user can audit:
+
+- **Revenue**: volume × price, with mix if there are segments; recognition timing if
+  contracts span periods. Do not model revenue as a straight growth percentage unless the
+  user asked for that — it hides the drivers.
+- **Payroll**: headcount, FTE and paid FTE are three different numbers. Prorate hires and
+  exits by month; do not divide an annual salary by 12 twice (an annual figure already
+  contains the monthly rate); make the commission and employer-cost basis explicit.
+- **Opex**: units × rate, fixed amounts, or one-time costs — say which. A growing opex line
+  needs a driver, not a percent of revenue, unless that is the stated policy.
+- **D&A**: cost, residual value, in-service date, useful life, convention. Reconcile gross
+  asset and accumulated depreciation roll-forwards to the prior period.
+- **Statements**: retained earnings rolls from opening + net income − dividends; the
+  cash-flow statement's ending cash equals the balance sheet's cash. If it does not, there
+  is a plug, and a plug is a finding, not a fix.
+
+A worked unit check, done in the cells: actual salary cost $60,000 across 10 paid FTE is
+$6,000 per FTE; a forecast of $6,300 per FTE on 11 FTE gives $69,300 against $66,000 for
+the prior per-FTE rate — the difference is rate *and* headcount, and both drivers belong
+on separate rows. If either missing pay or zero FTE is in the source, the implied rate
+cannot be established; mark it unavailable, do not divide by zero and call it 0.
+
+## Refreshes and merges
+
+A refresh merges complete periods on the business key (a date that exists in the calendar,
+a product code that exists in the master). Never append a partial period as if it were
+complete, and never let a merge drop a dimension silently — report rows that did not match.
+
+## Variances and audit
+
+- Variances need an amount **and** a percent. When the base is zero or missing, the percent
+  is unavailable — write `n.a.`, not `0%`.
+- Check totals: parts sum to the whole, schedules tie to statements, the bridge closes to
+  zero. Compare to two decimals, including `0.00`; a check that passes at 0.01 is not
+  passing.
+- Failed checks: light red fill (`#FFC7CE`) with bold red text (`#9C0006`), neutral for
+  passes. Missing or untested data is "unavailable", never "PASS".
+
+## Valuation, if it comes up
+
+- Build the method the user asked for. A DCF needs drivers, tax, D&A, capex, working
+  capital, unlevered free cash flow, the discounting convention, a terminal value method
+  and the enterprise-to-equity bridge — skipping two of these is not a shortcut, it is a
+  wrong answer.
+- IRR/XIRR need cash flows with valid signs and dates; a series with no sign change has no
+  IRR, and the function returning `#NUM!` is the correct answer to report.
+- Sensitivities the user asks for belong in a native what-if data table, not in a grid of
+  hand-typed scenarios that will drift.
+
+## Doing it live
+
+- Read the workbook before you model: `info` for tabs and objects, then
+  `read_range --formulas` across the rows you are extending. Match the existing anchoring
+  (`$C$4` for a rate, `C$9` for a period header) and the existing aggregation style
+  (`SUMIFS` over hand-rolled sums).
+- Add one driver row at a time, each with a formula you can point at, and verify after each
+  block; a 200-cell scenario grid written blind is the expensive way to fail.
+- If the model has a check tab, extend the checks to cover your new rows. If it has none
+  and the model is small, add one labelled verification row next to the output.
+- Never write a hard-coded total when a formula can tie it. And never "fix" an existing
+  `#REF!` — report it.

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

@@ -0,0 +1,58 @@
+# Healthcare
+
+Two kinds of workbook live in a health organisation, and they carry different rules:
+
+- **Clinical and patient records**: appointments, encounters, observations, results.
+  The source of truth is a clinical system; a workbook holds an extract.
+- **Administrative and financial work**: budgets, staffing, throughput, cost per case.
+  Money follows `financial_models.md` even when the organisation is a hospital.
+
+Most healthcare spreadsheet tasks are the second kind built on top of the first. Keep the
+extract and the analysis visibly separate.
+
+## Handling the raw extract
+
+- Put raw data on its own sheet or block, untouched, one table. Everything you compute
+  lives *beside* it or in a separate prepared block — never by overwriting a measurement.
+- Descriptive names help the next reader: `Appointments_RawData` beats `Sheet2`;
+  `Clinic KPI Dashboard` beats `Sheet5`.
+- Keep the source's definitions with the data: the period it covers, the extract date, the
+  source system, the denominator used. Length of stay, readmission rate and utilisation
+  are meaningless without them, and definitions differ between systems.
+- Preserve identifiers exactly as supplied (MRN formats vary), and keep dates as dates with
+  one format down the column.
+- Units belong in the header (`Weight (kg)`, `Temperature (°C)`, `HbA1c (%)`, `Heart rate
+  (bpm)`), not in the cells as text. A column of `"72 bpm"` strings cannot be averaged.
+
+## Building on it
+
+- Highlight the fields staff must complete (amber fill) and keep unused placeholders out.
+- If a threshold drives a flag, use one named cell for it (`BMI_threshold`) and reference
+  it, so the cut-off is visible and changeable. A number buried in a formula is an
+  invisible policy.
+- Flags come only from a stated source or protocol threshold, and keep the severity the
+  source gives (normal / elevated / high), with a legend on the sheet. Do not invent
+  clinical ranges, do not round a borderline value into a category.
+- A codebook (code → meaning, units, abbreviations) next to the data when the extract uses
+  codes, or a legend when it uses abbreviations.
+- Keep a `Corrected value` column or an audit log for corrections. Never edit the original
+  measurement in place; the original and the correction are both evidence.
+
+## Consequences of getting it wrong
+
+Clinical arithmetic and clinical judgement are different things. Compute what the source
+supports; verify a critical calculation (dosing, risk score, threshold classification)
+against the authoritative definition when one is available, and if it is not available say
+so instead of asserting the number is right. Do not give clinical advice, and do not
+present a screening flag as a diagnosis.
+
+## Doing it live
+
+- The user may have the extract open with their own formatting. Read before writing:
+  `info` for the sheets and used ranges, `read_range --formulas --display` for the block
+  you are extending.
+- Add derived columns to the right of the raw block with a clear header, or to a separate
+  prepared area; never insert a column into the middle of an extract that other formulas
+  or a pivot already reference.
+- After writing, verify with `read_range --formulas` and check the `errors` array — a
+  healthcare sheet with a `#DIV/0!` in a rate column is a report that will be misread.

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

@@ -0,0 +1,53 @@
+# Marketing and advertising
+
+Campaign, funnel, lead, CRM and ad-performance data. The failures here are almost always
+grain, denominator or freshness — not 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
+  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.
+
+## 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.
+- 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.
+- 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.
+
+## 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.
+
+## Doing it live
+
+- Read first: `info` (which sheets, which 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.

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

@@ -0,0 +1,53 @@
+# 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.
+
+## 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.
+
+## Presentation tables are a different object
+
+When the sheet is a report of the data rather than the data itself:
+
+- One type of data per column, units in the header (`Concentration (mg/L)`), never inside
+  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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,207 @@
+# 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.
+
+`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.
+
+## Reaching the running instance
+
+```powershell
+$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()`.
+
+## 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
+  rectangular `Value2` assignment cannot fill them.
+
+## Cells: what you write and what comes back
+
+| 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.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
+  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.
+
+## 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`.
+
+## Colour is BGR
+
+`Interior.Color` and `Font.Color` are OLE colour longs written `0xBBGGRR`, while every
+spec in this repo is `#RRGGBB`. Convert explicitly:
+
+```
+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.
+
+## 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.
+
+## 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.
+- **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.
+
+## 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.
+
+## 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.
+
+## 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.

package/assets/skills/excel-live-control/references/read_only_qna.md

@@ -0,0 +1,59 @@
+# Answering questions about a workbook the user has open
+
+Read-only work: no writes, no saves, no restyling. The deliverable is an answer with cell
+references the user can check, not a changed document.
+
+## Reading
+
+- `info` first: which workbook, which sheets, which used ranges, tables, charts, pivots.
+  That tells you where to look and whether the thing the user is asking about even exists.
+- `read_range --formulas` for the cells that matter. You almost always need both: the
+  value tells you *what*, the formula tells you *why*. A number with no formula behind it
+  is an input the user typed; a formula with no precedent is a number you cannot trust.
+- `read_range --display` when the question is about how something *reads* (`###`, a
+  truncated label, a date that shows as a serial). Displayed text follows the number
+  format; the value does not.
+- Read the workbook's own labels — row and column headers, period names, "Actual" vs
+  "Forecast" markers, units — before interpreting a cell. `D14` is only meaningful when
+  you know it is "Q3 advertising spend, USD".
+- The window may be ahead of the disk file. If `info` shows `saved: false`, the numbers
+  you read are the user's unsaved state; say so if the answer would differ from the file.
+
+## Answering
+
+1. **Locate the output by its labels**, not by guesswork: find the row/column that names
+   the metric and the period the user asked about, then read the intersection.
+2. **Trace the precedent chain** back from the output to labelled assumptions or raw
+   inputs. `read_range --formulas` on each step; stop at cells whose value is typed rather
+   than computed. Reporting an intermediate total as the cause is the classic error.
+3. **Reconcile before asserting.** If a total does not equal the sum of its parts, that is
+   the finding — report the gap and the cells, do not average it away.
+4. **Compute from the underlying values.** A cell showing `1.2` may hold `1.2345`; the
+   answer to "what is the margin" uses the stored value, and if the requested precision
+   needs the rounded number, say that you are using the displayed value.
+5. **Rank drivers** by absolute contribution when the question is "why did it move".
+   Report the top two or three with their cells and amounts, not a list of everything.
+6. **Cite cells** in the reply: `` `Summary!D14` shows 1,234 units because `Build!F7:F12`
+   sums to that ``. A claim without an address is not verifiable.
+7. If two sheets disagree, say which one you believe and why (more recent period, source
+   data rather than a copy, a formula chain rather than a paste), and do not "fix" either
+   without being asked.
+
+## Sensitive reviews
+
+Clinical records, payroll and individual compensation, customer-level data: answer at the
+level the user asked for and no lower. Inspect structure, formats, dependency chains and
+formulas as evidence, and do not echo restricted values into the chat unless the user
+needs that exact figure to act. If the question cannot be answered without exposing
+personal data, say what you can answer instead.
+
+## Limits
+
+- Do not equate the live window with the saved file, and do not present a read-only
+  question as if you had verified the disk copy.
+- If a formula depends on external links, volatile functions (`NOW()`, `RAND()`) or a
+  pivot cache that has not been refreshed, say the number is provisional.
+- If the workbook is protect-structured or the sheet is protected, reads still work;
+  report the protection rather than working around it.
+- `#REF!`, `#DIV/0!` and friends in the cells are part of the answer, not noise: name the
+  cell, the formula and what it broke.

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

@@ -0,0 +1,87 @@
+# Style guidelines for a live sheet
+
+Style is subordinate to content and to the user's own file. Precedence, strongest first:
+
+1. What the user asked for, in this conversation.
+2. The workbook's existing conventions — fonts, colours, borders, tab colours, number
+   formats. Match them; do not impose a house style on someone else's document.
+3. The domain guidance for the kind of model (`domain_guidance/`).
+4. The defaults below.
+
+Look before you paint: `info` for tab colours and structure, `read_range` for the formats
+a neighbouring block already uses. Restyling a user's sheet because your defaults are
+tidier is a defect, not a service.
+
+## Defaults that are safe anywhere
+
+- **Font family**: one per workbook. If it has none, Helvetica Neue → Helvetica → Arial →
+  Aptos. **Two sizes**: 10 pt body, 14 pt title, 16 pt ceiling. Never introduce a third
+  family or a decorative size.
+- **Alignment**: text left, numbers right, headers centred horizontally and middle
+  vertically. Do not centre numbers to look neat; they lose their decimal alignment.
+- **Headers**: bold, one rule under the last header row (`border: "outline"` on the header
+  block, or a bottom border on the row). No merged cells in working headers — merge only a
+  single spanning title, and prefer Center Across Selection for that.
+- **Inputs vs calculations**: an input cell the user is expected to type into gets a light
+  fill (`#FFF2CC` amber) and a thin border; calculated cells keep a plain fill. If the
+  whole block is inputs, one header note beats painting every cell.
+- **Gridlines**: a clean output or dashboard sheet hides them (`ActiveWindow.DisplayGridlines
+  = $false`, a view setting, not a cell format) and uses thin structural borders instead.
+  A working sheet keeps them.
+- **Borders**: outline a block, hairline between header and body. No box around every cell,
+  no double lines, no thick decorative frames.
+- **Column widths**: set them once per block (`column_width` in `style_range`), not per
+  cell. Widen for the formatted value, then check with `read_range --display` for `###`.
+- **Conditional formatting**: bounded to the data range, one or two rules. Never a whole
+  column, never a rule that paints a user input cell.
+- **Freeze panes** are not a styling nicety; the tool cannot set them on a hidden window.
+  If scrolling is the complaint, say so and let the user freeze the row.
+
+## Model layouts
+
+- Summary above detail, outputs before workings, assumptions grouped in one block rather
+  than scattered. A reader should be able to look at the top-left and understand the sheet.
+- One blank row at the top of a new output sheet, the title in an unfilled cell on the
+  left, a thin rule under it. No logo, no merged banner, no slogan.
+- Rows of commentary go to the right of the numbers, separated by one blank column; they
+  never sit between a label and its value.
+- Helper rows: italic, grouped under the block they serve, collapsed if the workbook
+  already uses grouping. Helper columns live outside the printed range or on a separate
+  helper sheet.
+- A case or scenario selector is a visible label plus a validated cell: `Case Selected:`
+  and the value on display. Do not hide the control in a defined name.
+- Section bands (a filled row spanning the table) get one outline around the whole
+  section, not per row.
+- Dark header fill with white text, or plain text with a rule. Pick one per workbook.
+
+## Finance conventions
+
+These are long-standing reader expectations in financial models; a reviewer notices when
+they are violated.
+
+- **Colour encodes provenance.** Blue font for editable hard-coded inputs, black for
+  formulas on the same sheet, green for links to another sheet, red for links to an
+  external workbook. Results on an output view stay black or the brand dark colour.
+- **Number formats**: `#,##0` for amounts, `#,##0.00` for per-share and price data,
+  `0.0%` for rates, `( )` for negatives and `-` for zero in accounting views
+  (`#,##0;(#,##0);"-"`). Currency symbol on the first monetary row and on totals, not on
+  every row.
+- **Indent formats** (`  @` for text labels, `_(`-style spacing) map a hierarchy without
+  empty columns.
+- **Totals** sit flush left in the label column, bold, with the rule above them. A total
+  that is a hard number rather than a formula is a finding, not a style choice.
+- **Period labels** follow `mmm-yy`, `d-mmm`, `yyyy`, `Q#:YY`, `FY:YY` as the workbook
+  already does. A date column has one format down its whole length.
+- **Actuals vs forecast**: the change of basis is visible — a divide, a different fill, or
+  a label — and never inferred from a colour alone.
+- A model that needs a gutter between the row labels and the numbers gets columns A:B
+  reserved for it. Do not retrofit a gutter onto a sheet that does not have one.
+
+## Warning colour, used sparingly
+
+- Input that must be refreshed: amber fill (`#FFF2CC`), normal font.
+- Critical error or failed check: light red fill (`#FFC7CE`) plus bold red text
+  (`#9C0006`).
+- Passing checks: neutral. A green wash over every PASS makes the one red row invisible.
+- Never encode a value only in colour — a reader with a monochrome printout, or a colour
+  vision deficiency, must still see the meaning. Put the flag in a cell.