dsh-office-kit 0.4.1 → 0.4.3

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

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

package/assets/skills/excel-live-control/container_tools/live_excel.py

@@ -605,6 +605,15 @@ def main() -> int:
     except ToolError as error:
         return emit(failure_payload(op, error), 2)
 
+    # macOS and Linux ship pwsh but no COM, and `shutil.which('powershell')` can find
+    # that binary; fail on the platform instead of surfacing a cryptic attach error.
+    if sys.platform != "win32":
+        return emit(failure_payload(op, ToolError(
+            "Excel/WPS live control drives the application through Windows PowerShell 5.1 "
+            "COM, which only exists on Windows",
+            "powershell",
+        )), 3)
+
     request = {
         "op": op,
         "launch_hidden": bool(getattr(args, "launch_hidden", False)),

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

@@ -1,7 +1,6 @@
 # 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.
+A live edit makes every modelling distinction visible to a watching user.
 
 ## The distinctions that matter
 
@@ -11,76 +10,61 @@ right, and a live edit makes each of them visible to a user who is watching.
 | 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 |
+| Budget | Forecast — a target vs 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.
+Establish fiscal calendar, horizon (monthly / quarterly / annual) and grain (company,
+segment, product) before typing a number; without all three it is not a model input. Show
+actuals and forecast apart (divide, label or fill) so the reader sees 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.
+Build a driver schedule per line, then a statement, then the output.
+
+- **Revenue**: volume × price; mix for segments; recognition timing for multi-period
+  contracts. No straight growth percentage unless the user asked.
+- **Payroll**: headcount, FTE and paid FTE are three numbers. Prorate hires and exits by
+  month; never divide an annual salary by 12 twice; state commission and employer-cost basis.
+- **Opex**: units × rate, fixed, or one-time — say which. A growing line needs a driver, not
+  a percent of revenue, unless that is 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 = opening + net income − dividends; cash-flow ending
+  cash = balance-sheet cash. A mismatch is a plug: report it, do not fix it.
+
+Worked unit check, in the cells: $60,000 of salary over 10 paid FTE is $6,000 per FTE;
+$6,300 per FTE × 11 is $69,300 against $66,000 at the prior rate — rate and headcount both
+moved, so both need a row. Missing pay or zero FTE: implied rate unavailable; never divide
+by zero into 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.
+Merge complete periods on the business key (calendar date, master product code). Never append
+a partial period as complete; never drop a dimension silently — report unmatched rows.
 
 ## 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%`.
+- A variance needs an amount **and** a percent. Zero or missing base: 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".
+  zero; compare to two decimals including `0.00`; a check that passes at 0.01 is failing.
+- Failed checks: `#FFC7CE` fill with bold `#9C0006` text; passes stay neutral. 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.
+- 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 is a wrong answer, not a shortcut.
+- IRR/XIRR need valid signs and dates; with no sign change there is no IRR, and `#NUM!` is
+  the answer to report.
+- Sensitivities belong in a native what-if data table, not a grid of hand-typed scenarios.
 
 ## 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.
+- Read first: `info` for tabs and objects; `read_range --formulas` over the rows you will
+  extend; match existing anchoring (`$C$4` rate, `C$9` period header) and `SUMIFS`
+  aggregation.
+- One driver row at a time, each with a formula you can point at; verify after each block. A
+  200-cell scenario grid written blind is the expensive way to fail.
+- Extend the check tab to cover new rows; on a small model with none, add one labelled
+  verification row beside the output.
+- Never hard-code a total a formula can tie; never "fix" an existing `#REF!` — report it.