dsh-office-kit 0.4.2 → 0.4.3

package/assets/skills/office-spreadsheets/references/formula-patterns.md

@@ -1,7 +1,6 @@
 # Formula patterns
 
-Spreadsheet formulas are read by people who did not write them and recalculated
-by engines that disagree at the edges. Prefer the direct, boring form.
+People who did not write a formula have to read it, and engines that disagree at the edges recalculate it. Prefer the direct, boring form.
 
 ## Anchoring
 
@@ -12,67 +11,38 @@ by engines that disagree at the edges. Prefer the direct, boring form.
 | `$A8` | right only | A column of item labels |
 | `$B$3` | never | One rate, a case selector, a fixed constant |
 
-`=SUMIFS(Amount,Month,C$4,Item,$A8)` reads the period from the header and the item
-from the label. `=C8*$B$3` multiplies by one fixed rate; `=C8*C$3` multiplies by
-the rate in that column. Getting this backwards is the most common silent error in
-a copied model — check one filled row and one filled column by hand.
+`=SUMIFS(Amount,Month,C$4,Item,$A8)` reads the period from the header and the item from the label. `=C8*$B$3` multiplies by one fixed rate; `=C8*C$3` multiplies by the rate in that column. Getting this backwards is the most common silent error in a copied model — check one filled row and one filled column by hand.
 
 ## Aggregation
 
-- `SUM` for a column, `SUMIFS` for filtered totals, `COUNTIFS` for counts,
-  `AVERAGEIFS` for averages.
-- Use `SUMIFS`/`COUNTIFS` even with one criterion; they read the same and extend
-  cleanly.
-- `SUMPRODUCT(qty_range, rate_range)` for paired multiplication; it does not
-  collapse to a single cell the way array arithmetic would.
-- `PRODUCT` for multiplied factors, but it skips blanks: a missing input silently
-  removes a factor. Check the inputs before trusting the result.
-- `INDEX`/`MATCH`, `VLOOKUP(...,FALSE)`, or `XLOOKUP` — all fine. Keep the exact
-  match flag explicit. A matched key is not a filled value: check the returned
-  cell for blank as well as for the key existing.
-- Long category lists belong in a mapping table with a lookup, not in a nested
-  `IF` chain.
+- `SUM` for a column, `SUMIFS` for filtered totals, `COUNTIFS` for counts, `AVERAGEIFS` for averages.
+- Use `SUMIFS`/`COUNTIFS` even with one criterion; they read the same and extend cleanly.
+- `SUMPRODUCT(qty_range, rate_range)` for paired multiplication; it does not collapse to a single cell the way array arithmetic would.
+- `PRODUCT` for multiplied factors, but it skips blanks: a missing input silently removes a factor. Check the inputs before trusting the result.
+- `INDEX`/`MATCH`, `VLOOKUP(...,FALSE)`, or `XLOOKUP` — all fine. Keep the exact-match flag explicit. A matched key is not a filled value: check the returned cell for blank as well as for the key existing.
+- Long category lists belong in a mapping table with a lookup, not in a nested `IF` chain.
 
 ## Dates and periods
 
-- Use the date the source gives; `TODAY()` only when the workbook should track
-  today, and label it when it does.
+- Use the date the source gives; `TODAY()` only when the workbook should track today, and label it when it does.
 - Store real dates with a date number format. Text dates do not calculate.
-- Derive period filters from one header row so a new month is a copy, not an edit:
-  `=SUMIFS(Amount,Date,">="&C$4,Date,"<"&EDATE(C$4,1),Item,$A8)`.
-- Week starting on the first business day (Monday unless the business says
-  otherwise); say which in the header.
-- Time scales run left to right coarse to fine: Annual, Quarterly, Monthly,
-  Weekly — with narrow unfilled spacer columns, not merged headers over hidden
-  helpers.
+- Derive period filters from one header row so a new month is a copy, not an edit: `=SUMIFS(Amount,Date,">="&C$4,Date,"<"&EDATE(C$4,1),Item,$A8)`.
+- Week starting on the first business day (Monday unless the business says otherwise); say which in the header.
+- Time scales run left to right coarse to fine: Annual, Quarterly, Monthly, Weekly — with narrow unfilled spacer columns, not merged headers over hidden helpers.
 
 ## Missing data
 
-- A real zero is zero. A missing value is blank, or honestly `n.a.`/`N/A` where
-  the reader expects text. Never substitute one for the other to make a chart look
-  complete.
-- `IFERROR` only around a failure you understand, never wrapped around a whole
-  block to hide it. `IFERROR(x,0)` turns a broken reference into a plausible zero.
-- Guards must not swallow the failure they guard against: `=IF(C8=0,"n.a.",B8/C8)`
-  is a clear answer, `=IFERROR(B8/C8,0)` is a lie.
-- Missing keys in a lookup should show as missing (`=IFNA(...,"not found")`), not
-  as zero.
+- A real zero is zero. A missing value is blank, or honestly `n.a.`/`N/A` where the reader expects text. Never substitute one for the other to make a chart look complete.
+- `IFERROR` only around a failure you understand, never around a whole block to hide it. `IFERROR(x,0)` turns a broken reference into a plausible zero.
+- Guards must not swallow the failure they guard against: `=IF(C8=0,"n.a.",B8/C8)` is a clear answer, `=IFERROR(B8/C8,0)` is a lie.
+- Missing keys in a lookup should show as missing (`=IFNA(...,"not found")`), not as zero.
 
 ## Things not to write
 
-- `LET`, dynamic arrays/spills, `MAP`, `REDUCE`, `LAMBDA`: the engines that read
-  these files implement them unevenly, and openpyxl stores text without
-  validating it.
-- `INDIRECT` for everything. It breaks traceability and does not update when a
-  sheet is renamed. Keep it only where the existing file already relies on it.
-- Volatile functions (`TODAY`, `NOW`, `RAND`, `OFFSET`) in a calculation grid:
-  every keystroke recalculates them, and the value changes when the file is
-  reopened.
+- `LET`, dynamic arrays/spills, `MAP`, `REDUCE`, `LAMBDA`: the engines that read these files implement them unevenly, and openpyxl stores text without validating it.
+- `INDIRECT` for everything. It breaks traceability and does not update when a sheet is renamed. Keep it only where the existing file already relies on it.
+- Volatile functions (`TODAY`, `NOW`, `RAND`, `OFFSET`) in a calculation grid: every keystroke recalculates them, and the value changes when the file is reopened.
 
 ## Circular references
 
-Avoid unintended cycles; Excel flags them for a reason. If a cycle is deliberate
-(interest on average balance, iterative allocation), document it in the sheet,
-confirm iteration is enabled, and verify the result converges to the expected
-number. A model that only "works" because the last recalc happened to stop at
-iteration 100 is not verified.
+Avoid unintended cycles; Excel flags them for a reason. If a cycle is deliberate (interest on average balance, iterative allocation), document it in the sheet, confirm iteration is enabled, and verify the result converges to the expected number. A model that only "works" because the last recalc happened to stop at iteration 100 is not verified.

package/assets/skills/office-spreadsheets/references/style-guidelines.md

@@ -1,69 +1,44 @@
 # Style guidelines
 
-Precedence: the user's request, then the workbook or template being edited, then a
-domain convention, then these defaults. Defaults apply to new sheets, or to
-restyling the user asked for — never to a sheet you were not asked to touch.
+Precedence: the user's request, then the workbook or template being edited, then a domain convention, then these defaults. Defaults apply to new sheets, or to restyling the user asked for — never to a sheet you were not asked to touch.
 
 ## Page furniture
 
-- One blank row at the top, then a short unfilled title, left aligned, in a size
-  clearly larger than the body. No full-width filled banner.
+- One blank row at the top, then a short unfilled title, left aligned, in a size clearly larger than the body. No full-width filled banner.
 - A thin rule under the title separates it from the table; nothing else.
-- Notes sit in ordinary cells to the right of the data, at least one blank column
-  away from the last header fill, with wrap off.
+- Notes sit in ordinary cells to the right of the data, at least one blank column away from the last header fill, with wrap off.
 - No footer blocks, no "Prepared by" furniture, no date stamps nobody asked for.
-- Gridlines off on new sheets. Do not change gridlines on a sheet you are editing
-  for another reason.
+- Gridlines off on new sheets. Do not change gridlines on a sheet you are editing for another reason.
 
 ## Structure
 
-- Freeze the header row of any table that scrolls, plus the identifying column(s)
-  when horizontal scrolling hides them. Freeze the smallest useful area and never
-  move content to make freezing convenient.
-- Header row: bold, centred horizontally and vertically, dark fill with white text
-  or a light grey band, thin white separators between header cells.
-- Section bands: one continuous fill with a single outline around the block; no
-  internal borders inside the band, no full-cell grid.
-- Spacer columns are genuinely empty (no values, no borders), not narrow columns
-  of spaces.
-- Keep working titles, headers, and input areas unmerged. Center Across Selection
-  gives the look of a merge without breaking sorting, filtering, and references.
+- Freeze the header row of any table that scrolls, plus the identifying column(s) when horizontal scrolling hides them. Freeze the smallest useful area and never move content to make freezing convenient.
+- Header row: bold, centred horizontally and vertically, dark fill with white text or a light grey band, thin white separators between header cells.
+- Section bands: one continuous fill with a single outline around the block; no internal borders inside the band, no full-cell grid.
+- Spacer columns are genuinely empty (no values, no borders), not narrow columns of spaces.
+- Keep working titles, headers, and input areas unmerged. Center Across Selection gives the look of a merge without breaking sorting, filtering, and references.
 
 ## Numbers, inputs, calcs
 
 - Typed values with explicit number formats — see `recipes/number-formats.md`.
-- Left-align text, right-align numbers, centre headers, middle-align vertically;
-  top-align long wrapped descriptions.
-- Distinguish inputs from calculations consistently: inputs get a light fill or a
-  colour cue the sheet already uses, calculations stay white. Yellow/amber marks an
-  input that still needs updating; keep that cue separate from calculated warnings.
-- When cases exist, show `Case Selected:` plus the linked value near the top of
-  each output and build tab, in a restrained dashed outline, and highlight the
-  active row in the driver table.
+- Left-align text, right-align numbers, centre headers, middle-align vertically; top-align long wrapped descriptions.
+- Distinguish inputs from calculations consistently: inputs get a light fill or a colour cue the sheet already uses, calculations stay white. Yellow/amber marks an input that still needs updating; keep that cue separate from calculated warnings.
+- When cases exist, show `Case Selected:` plus the linked value near the top of each output and build tab, in a restrained dashed outline, and highlight the active row in the driver table.
 - Technical helper rows above a model are italic and grouped/collapsed.
 
 ## Conditional formatting as a cue
 
-- Bound the rule to the data, and use it for status, risk, variance, and
-  exceptions — not decoration.
-- Critical errors: light red fill, bold dark red text. Valid checks stay neutral;
-  no static green "PASS" paint over a range.
-- Reuse the sheet's existing rule style before inventing a new colour. Two similar
-  reds in one workbook look like two different severities.
+- Bound the rule to the data, and use it for status, risk, variance, and exceptions — not decoration.
+- Critical errors: light red fill, bold dark red text. Valid checks stay neutral; no static green "PASS" paint over a range.
+- Reuse the sheet's existing rule style before inventing a new colour. Two similar reds in one workbook look like two different severities.
 
 ## Typography
 
 - One family across the workbook: Helvetica Neue, Helvetica, Arial, then Aptos.
-- Two sizes at most (three counting the title). Largest size no more than six
-  points above body. A 10pt body with an 11pt header and a 14pt title is enough.
-- Bold for headers and totals, italic for short context notes — never both on
-  the same line, never on every row.
-- Tighten row heights after content fits; do not shrink the font to win an
-  argument with a column width.
+- Two sizes at most (three counting the title). Largest size no more than six points above body. A 10pt body with an 11pt header and a 14pt title is enough.
+- Bold for headers and totals, italic for short context notes — never both on the same line, never on every row.
+- Tighten row heights after content fits; do not shrink the font to win an argument with a column width.
 
 ## Tab colours
 
-Use colours only to help navigation: a darker brand tone on output tabs, one
-level lighter on assumptions, a distinct muted tone on a ReadMe, a divider tab
-coloured while its children stay plain. Financial Actuals tabs are traditionally
-light tan. Never recolour tabs during an unrelated edit.
+Use colour only to help navigation: a darker brand tone on output tabs, one level lighter on assumptions, a distinct muted tone on a ReadMe, a divider tab coloured while its children stay plain. Financial Actuals tabs are traditionally light tan. Never recolour tabs during an unrelated edit.

package/assets/skills/office-spreadsheets/references/workbook-structure.md

@@ -1,9 +1,6 @@
 # Workbook structure
 
-Tab roles describe what a sheet *does*, not what tabs a workbook must have. A
-simple workbook can carry several roles as labelled blocks on one sheet; a large
-one separates them because the readers, the refresh cadence, or the audit trail
-differ.
+Tab roles describe what a sheet *does*, not what tabs a workbook must have. A simple workbook can carry several roles as labelled blocks on one sheet; a large one separates them because the readers, the refresh cadence, or the audit trail differ.
 
 | Role | Holds | Feeds |
 | --- | --- | --- |
@@ -16,45 +13,25 @@ differ.
 
 Rules that keep a workbook readable a year later:
 
-- Inputs flow forward: source → build → output. A source tab never reads a
-  downstream result back in; when it seems to, the value belongs on a build tab.
-- Builds show the steps: quantity × rate, capacity used ÷ capacity available,
-  opening + movements = closing. One dense formula that jumps from input to final
-  number cannot be reviewed and will be wrong the first time an input changes.
-- Outputs consolidate and roll up. They do not repeat a calculation that already
-  exists on a build tab; they reference it.
-- Checks are terminal. Nothing depends on a check tab, and a passing check stays
-  neutral — a wall of green PASS fills trains the reader to ignore the one red
-  cell that matters.
-- Combine roles when the workbook is small. Three assumption cells do not need a
-  Settings tab; a short labelled block beside the calculation is easier to audit.
-- Add a tab when the reader differs, the data grain differs, the refresh
-  boundary differs, or the user asks. Not because a template had one.
+- Inputs flow forward: source → build → output. A source tab never reads a downstream result back in; when it seems to, the value belongs on a build tab.
+- Builds show the steps: quantity × rate, capacity used ÷ capacity available, opening + movements = closing. One dense formula that jumps from input to final number cannot be reviewed and will be wrong the first time an input changes.
+- Outputs consolidate and roll up. They reference the calculation on the build tab; they do not repeat it.
+- Checks are terminal. Nothing depends on a check tab, and a passing check stays neutral — a wall of green PASS fills trains the reader to ignore the one red cell that matters.
+- Combine roles when the workbook is small. Three assumption cells do not need a Settings tab; a short labelled block beside the calculation is easier to audit.
+- Add a tab when the reader differs, the data grain differs, the refresh boundary differs, or the user asks. Not because a template had one.
 
 ## Physical order
 
-For multi-tab workbooks, left to right: outputs, the assumption control panel
-(usually just after the primary output so a reader sees the switch), builds,
-then inputs and sources, with a divider tab such as `Internal >>` guarding the
-tail. The reader gets the answer first; the machinery lives to the right.
+For multi-tab workbooks, left to right: outputs, the assumption control panel (usually just after the primary output so a reader sees the switch), builds, then inputs and sources, with a divider tab such as `Internal >>` guarding the tail. The reader gets the answer first; the machinery lives to the right.
 
-Separate schedules when inputs, grain, or owners differ (revenue vs cost bases,
-monthly vs weekly). A single mega-sheet that mixes both grains is where
-double-counting starts.
+Separate schedules when inputs, grain, or owners differ (revenue vs cost bases, monthly vs weekly). A single mega-sheet that mixes both grains is where double-counting starts.
 
 ## Names
 
-Short, descriptive, and about the content: `Pipeline`, `Revenue build`,
-`Monthly forecast`. Not `Sheet3`, not `Data2`, not a sentence. A forecast review
-tab is `Forecast review`, `Forecast variance`, or `Sensitivity`; never `Movement`,
-which says nothing about what moved.
+Short, descriptive, and about the content: `Pipeline`, `Revenue build`, `Monthly forecast`. Not `Sheet3`, not `Data2`, not a sentence. A forecast review tab is `Forecast review`, `Forecast variance`, or `Sensitivity`; never `Movement`, which says nothing about what moved.
 
-Divider tabs are labels, not data: `Inputs >>` with its children uncoloured reads
-as a section marker; a coloured tab on every sheet reads as noise.
+Divider tabs are labels, not data: `Inputs >>` with its children uncoloured reads as a section marker; a coloured tab on every sheet reads as noise.
 
 ## The case selector
 
-When a workbook has cases, there is exactly one editable selector, on the cover
-or assumptions tab, with its current value shown as `Case Selected:` near the top
-of every output and build tab. Two selectors, or a selector plus hard-coded
-per-tab values, is how a model ends up reporting two different cases.
+When a workbook has cases, there is exactly one editable selector, on the cover or assumptions tab, with its current value shown as `Case Selected:` near the top of every output and build tab. Two selectors, or a selector plus hard-coded per-tab values, is how a model ends up reporting two different cases.

package/assets/skills/office-spreadsheets/routing/google-sheets.md

@@ -1,36 +1,21 @@
 # Google Sheets
 
-This runtime works on local files with openpyxl. There are no Google credentials,
-no Drive API, and no live link to a browser sheet, so "update my Google Sheet"
-cannot be done directly.
+This runtime works on local files with openpyxl. There are no Google credentials, no Drive API, and no live link to a browser sheet, so "update my Google Sheet" cannot be done directly.
 
 ## What to do instead
 
-1. Say plainly what is possible: the work is done on a local `.xlsx` file the user
-   opens in Sheets, or the user exports the sheet and shares the file.
-2. Ask for an export when the source lives in Sheets: `File > Download >
-   Microsoft Excel (.xlsx)`. A single-sheet CSV loses formulas and formats, so ask
-   for `.xlsx` unless the sheet is truly one flat table.
-3. Do the work on the exported file with this skill, then hand back the `.xlsx`.
-   The user re-uploads or imports it. State that formulas recalculate when Sheets
-   opens the file.
-4. Do not promise a round trip that keeps Sheets-specific features. Named
-   functions, Apps Script, and connected sheets do not survive export.
+1. Say plainly what is possible: the work is done on a local `.xlsx` file the user opens in Sheets, or the user exports the sheet and shares the file.
+2. Ask for an export when the source lives in Sheets: `File > Download > Microsoft Excel (.xlsx)`. A single-sheet CSV loses formulas and formats, so ask for `.xlsx` unless the sheet is truly one flat table.
+3. Do the work on the exported file with this skill, then hand back the `.xlsx`. The user re-uploads or imports it. State that formulas recalculate when Sheets opens the file.
+4. Do not promise a round trip that keeps Sheets-specific features. Named functions, Apps Script, and connected sheets do not survive export.
 
-## When writing formulas for a file that will go back to Sheets
+## Formulas for a file that goes back to Sheets
 
-- Keep to functions both engines share: `SUMIFS`, `INDEX/MATCH`, `XLOOKUP`,
-  `IFERROR`, `EDATE`, `TEXT`.
-- Newer functions that Excel stores with an `_xlfn.` prefix are a common source of
-  `#NAME?` after a round trip. If a function is genuinely new, say so.
-- Array formulas and dynamic spills behave differently in the two engines. Avoid
-  them in shared files.
-- Number formats, conditional-formatting rules, and charts mostly survive an
-  export; images and pivot tables often do not. Check them after the round trip
-  with `container_tools/inspect_workbook.py`.
+- Keep to functions both engines share: `SUMIFS`, `INDEX/MATCH`, `XLOOKUP`, `IFERROR`, `EDATE`, `TEXT`.
+- Newer functions that Excel stores with an `_xlfn.` prefix are a common source of `#NAME?` after a round trip. If a function is genuinely new, say so.
+- Array formulas and dynamic spills behave differently in the two engines. Avoid them in shared files.
+- Number formats, conditional-formatting rules, and charts mostly survive an export; images and pivot tables often do not. Check them after the round trip with `container_tools/inspect_workbook.py`.
 
 ## Links
 
-A sheet shared by URL is not a workbook on this machine. Do not fetch a Google
-Sheets URL and pretend it is a file: without a published CSV or an export, there
-is nothing to read.
+A sheet shared by URL is not a workbook on this machine. Do not fetch a Google Sheets URL and pretend it is a file: without a published CSV or an export, there is nothing to read.

package/assets/skills/office-spreadsheets/tasks/analyze-workbook.md

@@ -1,37 +1,22 @@
 # Answer questions about an existing workbook
 
-This is a read-only job. Do not "improve" the file, do not recalculate it in
-place, and do not save a copy unless the user asked for one.
+This is a read-only job. Do not "improve" the file, do not recalculate it in place, and do not save a copy unless the user asked for one.
 
 ## Procedure
 
-1. `"<python>" "<cli>" xlsx read --input "<book.xlsx>" --json-out "<dump>.json"` —
-   sheet names, used ranges, and cell contents.
-2. Read **values**, not formulas, when the question is about numbers:
-   `xlsx read --data-only` returns cached results. If the cache is empty (the
-   file was last written by a script), say so and quote the formula instead of a
-   number, or recalculate into a copy first (`tasks/recalc-and-check.md`).
-3. `container_tools/inspect_workbook.py --input "<book.xlsx>" --sample 8` when the
-   question touches structure: which cells are formulas, merged ranges, totals
-   rows, conditional formats, defined names, hidden rows, extra sheets.
-4. Answer with the cells you used: "`Pipeline!B4:B13`, the Amount column, sums to
-   `812,000`" beats "the pipeline is about 800k". Name the sheet, the range, and
-   the figure.
+1. `"<python>" "<cli>" xlsx read --input "<book.xlsx>" --json-out "<dump>.json"` — sheet names, used ranges, and cell contents.
+2. Read **values**, not formulas, when the question is about numbers: `xlsx read --data-only` returns cached results. If the cache is empty (the file was last written by a script), say so and quote the formula instead of a number, or recalculate into a copy first (`tasks/recalc-and-check.md`).
+3. `container_tools/inspect_workbook.py --input "<book.xlsx>" --sample 8` when the question touches structure: which cells are formulas, merged ranges, totals rows, conditional formats, defined names, hidden rows, extra sheets.
+4. Answer with the cells you used: "`Pipeline!B4:B13`, the Amount column, sums to `812,000`" beats "the pipeline is about 800k". Name the sheet, the range, and the figure.
 
 ## Judgement calls
 
-- A number that disagrees with the user's expectation is usually a real answer,
-  not an error to fix. Explain the calculation and stop.
-- Pre-existing `#REF!`/`#DIV/0!` cells are part of the answer. Point at them, say
-  what breaks, and wait for instructions.
-- Two tabs with the same title and different numbers: report both and ask which
-  one the user means before averaging or picking.
-- Empty cells are not zeros. "Not reported" and "zero" are different answers, and
-  a missing month in a total usually means a filter, not a zero.
+- A number that disagrees with the user's expectation is usually a real answer, not an error to fix. Explain the calculation and stop.
+- Pre-existing `#REF!`/`#DIV/0!` cells are part of the answer. Point at them, say what breaks, and wait for instructions.
+- Two tabs with the same title and different numbers: report both and ask which one the user means before averaging or picking.
+- Empty cells are not zeros. "Not reported" and "zero" are different answers, and a missing month in a total usually means a filter, not a zero.
 - If the workbook has a case selector, check it. The answer depends on it.
 
 ## Output shape
 
-Short answer first (one line with the figure), then the cells behind it, then any
-caveat about missing data or stale cache. No file changes, no new workbook, no
-chart unless asked.
+Short answer first (one line with the figure), then the cells behind it, then any caveat about missing data or stale cache. No file changes, no new workbook, no chart unless asked.

package/assets/skills/office-spreadsheets/tasks/annotations.md

@@ -1,7 +1,6 @@
 # Resolve an `office-annotations` region to cells
 
-The user drags a box on the rendered workbook and types a requirement. The
-payload for spreadsheets is:
+The user drags a box on the rendered workbook and types a requirement. The payload for spreadsheets is:
 
 ```json
 {
@@ -15,37 +14,20 @@ payload for spreadsheets is:
 }
 ```
 
-There is no `page`, no `sheet`, and no `range`: the preview client cannot turn a
-pixel rectangle into a cell address and will not fake one. Read it as "look at
-this area of this sheet and do this", not as a cell reference.
+There is no `page`, no `sheet`, and no `range`: the preview client cannot turn a pixel rectangle into a cell address and will not fake one. Read it as "look at this area of this sheet and do this", not as a cell reference.
 
 ## Procedure
 
-1. `read_image` the attachment named `imageName`. It is the screenshot of the
-   area the user marked: read the visible headers, row labels, and the numbers
-   around the box.
-2. `"<python>" "<cli>" xlsx read --input "<book.xlsx>" --json-out "<dump>.json"`,
-   then match the visible values to sheets and A1 addresses. Values repeat across
-   sheets more often than you expect — match on a combination (a row label plus
-   two numbers), not on one number.
-3. When the numbers are ambiguous, `container_tools/inspect_workbook.py` adds
-   formulas, merges, tables, and names; formats often disambiguate ("the only
-   column with a `%` format").
-4. State what you resolved, in the user's terms: "`Pipeline!D2:D13`, the Amount
-   column — 12 rows of whole dollars". Ask only if two sheets or two columns
-   match equally well.
-5. Apply the smallest change that satisfies `requirement` with the mutation tools
-   (`tasks/edit-workbook.md`), re-render, and confirm the region now looks right.
+1. `read_image` the attachment named `imageName`. It is the screenshot of the area the user marked: read the visible headers, row labels, and the numbers around the box.
+2. `"<python>" "<cli>" xlsx read --input "<book.xlsx>" --json-out "<dump>.json"`, then match the visible values to sheets and A1 addresses. Values repeat across sheets more often than you expect — match on a combination (a row label plus two numbers), not on one number.
+3. When the numbers are ambiguous, `container_tools/inspect_workbook.py` adds formulas, merges, tables, and names; formats often disambiguate ("the only column with a `%` format").
+4. State what you resolved, in the user's terms: "`Pipeline!D2:D13`, the Amount column — 12 rows of whole dollars". Ask only if two sheets or two columns match equally well.
+5. Apply the smallest change that satisfies `requirement` with the mutation tools (`tasks/edit-workbook.md`), re-render, and confirm the region now looks right.
 
 ## What not to do
 
-- Do not compute a cell from the rectangle's coordinates. Header width, frozen
-  panes, hidden columns, and zoom all move cells under the same pixel.
-- Do not edit the first sheet because it was the default. The visible page may be
-  the fourth sheet.
-- Do not re-style the whole sheet to make the marked area consistent. Match the
-  surrounding convention and change the cells the requirement names.
-- If the region covers a chart or a picture, the change is to the object, not the
-  cells behind it — check `charts`/`images` in the inspect output first.
-- If nothing on the page carries the values in the screenshot, say which image
-  you looked at and what you could not locate. Do not guess a sheet.
+- Do not compute a cell from the rectangle's coordinates. Header width, frozen panes, hidden columns, and zoom all move cells under the same pixel.
+- Do not edit the first sheet because it was the default. The visible page may be the fourth sheet.
+- Do not re-style the whole sheet to make the marked area consistent. Match the surrounding convention and change the cells the requirement names.
+- If the region covers a chart or a picture, the change is to the object, not the cells behind it — check `charts`/`images` in the inspect output first.
+- If nothing on the page carries the values in the screenshot, say which image you looked at and what you could not locate. Do not guess a sheet.

package/assets/skills/office-spreadsheets/tasks/create-workbook.md

@@ -40,9 +40,9 @@
 
 ## Order of work
 
-1. Sketch the sheets as roles, not tabs: inputs, calculations, outputs, checks. A five-line model belongs on one sheet with labelled blocks.
-2. Put the number formats on the cells, not on a copy of the values. `#,##0` for currency-ish amounts, `0.0%` for percentages, `yyyy-mm-dd` for real dates.
-3. Write the calculation as visible steps (quantity × rate, opening + movements = closing) and link the output to the build rather than repeating the arithmetic.
+1. Sketch sheets as roles, not tabs: inputs, calculations, outputs, checks. A five-line model belongs on one sheet with labelled blocks.
+2. Put number formats on the cells, not on a copy of the values. `#,##0` for currency-ish amounts, `0.0%` for percentages, `yyyy-mm-dd` for real dates.
+3. Write calculations as visible steps (quantity × rate, opening + movements = closing) and link the output to the build rather than repeating the arithmetic.
 4. Add a chart only when it answers a comparison question the numbers alone answer slowly; see `references/charts.md`.
 5. Render and read the PNG, then recalc if formulas exist.
 
@@ -60,7 +60,7 @@
 ## Pitfalls
 
 - Values written through the CLI keep their type: `1840000` is a number, `"1,840,000"` is text and will not sum. Format numbers, never pre-format them as strings.
-- A chart whose `max_row` is larger than the data plots empty points as zero, which reads as a collapse to the floor. Match the range to the data.
-- `anchor` is where the chart's top-left corner sits; a chart outside the print area gets cut off by `xlsx render`. Put it below or beside the data inside the printed range.
+- A chart whose `max_row` exceeds the data plots empty points as zero, which reads as a collapse to the floor. Match the range to the data.
+- `anchor` is where the chart's top-left corner sits; a chart outside the print area gets cut off by `xlsx render`. Put it below or beside the data, inside the printed range.
 - Dates must be real dates (`date(2026, 1, 31)` via a snippet, or Excel serial numbers), never `"Jan-26"` strings, or period filters fail silently.
 - Set the font family explicitly if the file will be opened on another machine; a missing Calibri falls back to a serif in some renderers and every column width shifts.

package/assets/skills/office-spreadsheets/tasks/diff-workbooks.md

@@ -25,8 +25,8 @@ Exit code `0` means the files match at the requested level, `1` means difference
 
 Run it as `--before original --after original-edited` immediately after any edit, and read the "changed" sections as the diff you are about to describe to the user:
 
-1. Anything under cells that you did not intend to touch is collateral damage — revert and redo with a narrower edit.
-2. A sheet, table, name, or chart in "removed" is a lost object; rebuild it from `recipes/charts.md` / `recipes/named-ranges.md` before presenting.
+1. Cells you did not intend to touch are collateral damage — revert and redo with a narrower edit.
+2. A sheet, table, name, or chart under "removed" is a lost object; rebuild it from `recipes/charts.md` / `recipes/named-ranges.md` before presenting.
 3. Formatting-only differences across many rows usually mean a style object was reapplied to a range instead of a cell.
 
 Diffing a file against itself is a useful sanity check that the tool and the file load cleanly: it should return `identical: true`.

package/assets/skills/office-spreadsheets/tasks/edit-workbook.md

@@ -5,7 +5,7 @@ The file is the specification. Read its conventions before writing a cell, then
 ## Procedure
 
 1. `"<python>" "<cli>" xlsx read --input "<book.xlsx>" --json-out "<dump>.json"` — every sheet, its used range, and its formulas.
-2. `"<python>" "<skill>/container_tools/inspect_workbook.py" --input "<book.xlsx>"` — what the read verb does not show: merged ranges, conditional formatting, defined names, Excel Tables, charts and their series, freeze panes, protections. It prints JSON; `--no-values` skips the second load that looks for cached results.
+2. `"<python>" "<skill>/container_tools/inspect_workbook.py" --input "<book.xlsx>"` — what the read verb hides: merged ranges, conditional formatting, defined names, Excel Tables, charts and their series, freeze panes, protections. It prints JSON; `--no-values` skips the second load that looks for cached results.
 3. Render the sheets you are about to touch and look at them: `xlsx render`, then `read_image`. Match the surrounding format, not your personal default.
 4. Apply the edit with the narrowest tool that fits (below), or with an openpyxl snippet when the change is not one of those shapes.
 5. Read back and re-check structure, recalculate if formulas changed, render again, compare.
@@ -24,11 +24,11 @@ There is no `xlsx edit` verb. Each tool loads the workbook, changes only what yo
 | Add a native chart | `add_chart.py --input "<book.xlsx>" --sheet Trend --type line --title "Monthly revenue (USD)" --anchor A6 --data-min-col 2 --data-min-row 3 --data-max-col 13 --data-max-row 3 --cat-min-row 2 --cat-max-row 2` |
 | Embed an image | `add_image.py --input "<book.xlsx>" --sheet Cover --path logo.png --anchor B2 --width 320` |
 
-Each tool writes `<input>-edited.xlsx` unless you pass `--out`, so chain by naming outputs, never by editing the file you just read and forgetting the step in between.
+Each tool writes `<input>-edited.xlsx` unless you pass `--out`, so chain by naming outputs — never edit the file you just read and lose the step in between.
 
 `cells.json` is `{"sheet": "Model", "cells": {"B3": 0.07, "D9": "=SUM(D2:D8)"}}` or a list of those. `styles.json` is `{"sheet": "Model", "styles": {"A11:B11": {"bold": true}, "C11:C14": {"number_format": "0.0%"}}}`.
 
-Two tool limits are deliberate: `append_rows.py` does not extend an Excel Table, copy the formula from the row above, or grow a chart — do those with a snippet from `recipes/data-tables.md` and `recipes/charts.md`, or the new rows will sit outside the table and the chart will stop at the old last row. `add_chart.py` treats a one-row data range as one series of many points (which is what a monthly row means) but cannot set axis number formats or series colours; fix those in the same snippet.
+Two tool limits are deliberate: `append_rows.py` does not extend an Excel Table, copy the formula from the row above, or grow a chart — use a snippet from `recipes/data-tables.md` and `recipes/charts.md`, or the new rows sit outside the table and the chart stops at the old last row. `add_chart.py` treats a one-row data range as one series of many points (what a monthly row means) but cannot set axis number formats or series colours; fix those in the same snippet.
 
 ## What must survive an edit
 
@@ -48,7 +48,7 @@ New conditional formatting that covers a whole table must extend to the rows you
 ## Cells: the smallest change
 
 - Write to the sheet and address you resolved; never "the first empty row" of an unnamed sheet.
-- A text edit changes run-level text only in a cell; the format stays unless the request names it.
+- A text edit changes run-level text only; the cell format stays unless the request names it.
 - A number-format change is a format change, not a value change: do not replace `0.0649` with `6.5%` text.
 - Do not autofit every column or restyle a table to fix one clipped cell. Widen the column, or shrink the font only for that block.
 - Do not add spacer rows, helper sheets, or "Notes" tabs unless the request needs them.
@@ -66,4 +66,4 @@ If `xlsx read` shows `#REF!`, `#DIV/0!`, or a formula pointing at a sheet that n
 "<python>" "<cli>" xlsx render --input "<book-edited.xlsx>" --out-dir "<render-dir>"
 ```
 
-The diff is the closest thing to a guarantee that nothing else moved: it reports changed cells and formulas, changed formatting unless you pass `--no-formats`, and structure changes (sheets, merges, widths, tables, charts, defined names). Exit code `1` means differences — not failure. Use `--sheet` to narrow and `--limit` to cap the per-sheet cell list.
+The diff is the closest thing to a guarantee that nothing else moved: it reports changed cells and formulas, changed formatting unless you pass `--no-formats`, and structure changes (sheets, merges, widths, tables, charts, defined names). Exit code `1` means differences — not failure. Use `--sheet` to narrow and `--limit` to cap the per-sheet cell list. Gate flags and exit codes: `tasks/recalc-and-check.md`.

package/assets/skills/office-spreadsheets/tasks/inspect-workbook.md

@@ -2,10 +2,10 @@
 
 Two readers, different jobs:
 
-- `"<python>" "<cli>" xlsx read --input "<book.xlsx>" [--data-only]` — the cell values, per sheet, as arrays without coordinates. `--data-only` returns cached results instead of formula text.
-- `"<python>" "<skill>/container_tools/inspect_workbook.py" --input "<book.xlsx>"` — the structure around the cells: formats that govern how they read, objects that live beside them, and whether the formulas were ever computed.
+- `"<python>" "<cli>" xlsx read --input "<book.xlsx>" [--data-only]` — cell values per sheet, as arrays without coordinates. `--data-only` returns cached results instead of formula text.
+- `"<python>" "<skill>/container_tools/inspect_workbook.py" --input "<book.xlsx>"` — the structure around the cells: the formats that govern how they read, the objects beside them, and whether the formulas were ever computed.
 
-Run both before editing, and after editing to prove nothing was lost.
+Run both before editing, and again after to prove nothing was lost.
 
 ## What the inspector reports
 
@@ -19,20 +19,20 @@ Run both before editing, and after editing to prove nothing was lost.
 | `sheets[].print_area`, `freeze_panes`, `gridlines` | Layout choices a render will honour |
 | `sheets[].merged` | Merged ranges; a value lives in the top-left cell only |
 | `sheets[].tables` | Excel Table names and refs; rows appended below a `ref` land outside the table |
-| `sheets[].charts[].anchor`, `.kind`, `.series` | Where a chart sits and what it plots; `anchor` outside `print_area` means the chart is cut off when printed |
+| `sheets[].charts[].anchor`, `.kind`, `.series` | Where a chart sits and what it plots; an `anchor` outside `print_area` is cut off when printed |
 | `sheets[].conditional_formats[].rules` | `type` (`cellIs`, `colorScale`, `dataBar`, `expression`), `operator`, `formula`, `priority`. A rule whose range stops short of new rows silently stops applying |
 | `sheets[].data_validations` | Dropdowns and constraints an edit must preserve |
 | `sheets[].hidden_rows`, `hidden_columns` | Content the user deliberately folded away |
 | `sheets[].formulas.shared`, `.array`, `.data_tables` | Non-trivial formula storage; re-saving can materialise or drop these |
 | `sheets[].values.cached`, `.missing`, `.errors` | How many formula cells carry a cached result, carry none, or carry an error value |
 
-`--no-values` skips the second load that reads cached results (faster on big files, blind to whether formulas were ever computed). `--sample N` sets how many formula samples per sheet are printed (default 5).
+`--no-values` skips the second load that reads cached results (faster on big files, blind to whether formulas ever computed). `--sample N` sets how many formula samples per sheet are printed (default 5).
 
 ## How to read it
 
 - `values.missing` equal to `formulas.count` means nothing has ever calculated this file. Do not quote any formula result; recalculate first (`tasks/recalc-and-check.md`).
-- `values.errors` non-empty is pre-existing damage (or a deliberately `#N/A` sentinel). Report it, do not fix it unasked.
-- `container.pivot_tables > 0` or `has_vba_project: true` means a plain openpyxl rewrite is risky: back up, change the fewest cells possible, and re-inspect after saving.
+- `values.errors` non-empty is pre-existing damage (or a deliberate `#N/A` sentinel). Report it; do not fix it unasked.
+- `container.pivot_tables > 0` or `has_vba_project: true` means a plain openpyxl rewrite is risky: back up, change the fewest cells possible, re-inspect after saving.
 - `formulas.shared > 0` means a spreadsheet app wrote the file; copy an existing formula down rather than inventing a new pattern.
-- A sheet with a huge `dimensions` and few real cells is a formatting artefact (fill applied to whole columns). Do not "clean" it; note it if the user asks why the file is slow.
-- `print_area` and chart `anchor` are the two fields that explain most render surprises: charts clipped at the page edge, or entire data blocks missing from a PDF because they fall outside the print range.
+- A huge `dimensions` with few real cells is a formatting artefact (fill applied to whole columns). Do not "clean" it; note it if the user asks why the file is slow.
+- `print_area` and chart `anchor` explain most render surprises: charts clipped at the page edge, or whole data blocks missing from a PDF because they fall outside the print range.