dsh-office-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,72 @@
+# Number formats
+
+A number format changes how a stored value is displayed, never the value. The
+cell keeps full precision; `0.0%` shows `6.4%` for `0.06398`. Never store a
+rounded number to make a column look tidy, and never store `"6.4%"` as text —
+it stops summing.
+
+```python
+import sys
+from openpyxl import load_workbook
+
+wb = load_workbook(sys.argv[1])
+ws = wb["Model"]
+
+formats = {
+    "B11:B14": "#,##0",        # whole dollars
+    "B6:B7":   "0.0%",         # rates, one decimal
+    "B8":      '"$"#,##0',     # currency with a literal sign
+    "C2:C13":  "yyyy-mm-dd",   # real dates, ISO order
+    "D2:D13":  '"$"#,##0;[Red]-"$"#,##0',   # negatives in red
+}
+for rng, code in formats.items():
+    block = ws[rng]
+    rows = block if isinstance(block, tuple) else ((block,),)   # a single cell is not a tuple
+    for row in rows:
+        for cell in row:
+            cell.number_format = code
+wb.save(sys.argv[2])
+```
+
+## The codes worth knowing
+
+| Purpose | Code | Notes |
+| --- | --- | --- |
+| Thousands, no decimals | `#,##0` | The default for money in a model |
+| Thousands, two decimals | `#,##0.00` | Prices, unit costs |
+| Percent, one decimal | `0.0%` | Analytical percentages — rates, margins, growth |
+| Percent, no decimal | `0%` | Dashboard and KPI tiles only |
+| Percent, two decimals | `0.00%` | When differences of a tenth of a point matter |
+| Currency | `"$"#,##0` | A literal sign keeps the unit visible in every cell |
+| Negative in red | `#,##0;[Red]-#,##0` | Check that the reader wants colour, not a `( )` convention |
+| Date | `yyyy-mm-dd` | Sortable, unambiguous; store a real date, not text |
+| Text passthrough | `@` | For codes and account numbers with leading zeros |
+
+Do not use `0,0%` or `#.##0`. They are not locale-independent and render
+differently on an engine that reads `,` as a decimal separator.
+
+## Signs, units, and scale
+
+- State the unit once, in the header or title (`Revenue (USD)`), and keep the
+  stored value in that unit. A column that stores thousands but is headed
+  "USD" is a defect waiting to be discovered.
+- If the presentation needs thousands (`$K`) while the data is in units,
+  format does not divide — either store thousands and say so, or divide with a
+  formula in a helper column. Never scale twice.
+- Percentages: store `0.064`, never `6.4`. A stored `6.4` formatted `0.0%`
+  reads `640.0%`.
+
+## Widths and `###`
+
+`###` means the column is narrower than the formatted number. Widen that
+column (`ws.column_dimensions["B"].width = 14`) or shrink the font for the block.
+Never shorten the number, switch to text, or reduce decimals just to fit — and do
+not autofit every column in the sheet to fix one.
+
+## Dates
+
+Write a real date (`datetime.date(2026, 1, 31)`) and set `yyyy-mm-dd`. Storing
+an ISO string sorts alphabetically and calculates as text: `EDATE`, `SUMIFS` on
+dates, and `YEAR()` all fail silently or with `#VALUE!`. A date typed as a number
+of days since 1899-12-30 is a serial — fine for formulas, unreadable for people,
+so format it.

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

@@ -0,0 +1,43 @@
+# Sparklines and in-cell bars
+
+openpyxl writes no sparkline object (and neither does the helper CLI), so a
+"sparkline" here is one of two things: a formula that draws a bar inside the
+cell, or a tiny native chart. Pick by what the user needs to read.
+
+```python
+import sys
+from openpyxl import load_workbook
+from openpyxl.styles import Alignment, Font
+
+wb = load_workbook(sys.argv[1])
+ws = wb["Trend"]
+
+for col in range(2, 14):                       # B..M
+    letter = ws.cell(1, col).column_letter
+    cell = ws.cell(4, col, f'=IF({letter}3="","",REPT("█",MAX(1,ROUND({letter}3/MAX($B$3:$M$3)*7,0))))')
+    cell.font = Font(size=9, color="FF2E7D32")
+    cell.alignment = Alignment(horizontal="left", shrink_to_fit=True)
+ws.row_dimensions[4].height = 14
+wb.save(sys.argv[2])
+```
+
+- `REPT` needs a repeat count that fits the column. A 9-character column shows
+  about 7 blocks at 9pt; anything longer spills into the neighbouring cell and
+  the bars look like one continuous smear. Scale to the column width, not to 22.
+- Keep the count formula-driven (`value / MAX(values) * width`), so a changed
+  number moves the bar.
+- The block character is text. Sorting the column sorts blocks, and a reader who
+  copies the cell gets `████`, not a number — never put these in the column the
+  numbers should be read from.
+- Guard blanks with `IF(cell="","",…)`, otherwise a blank reads as zero and every
+  missing month draws a minimum bar.
+- A native in-cell chart is not the same as a chart object: if the user needs a
+  hover tooltip, axis, or legend, build a real chart with `recipes/charts.md`
+  instead of stretching a formula.
+
+## When a real chart is the right answer
+
+A sparkline is context for one number, in a dense table. If the sheet has space
+and the point is the trend itself, a small `LineChart` (height 4, width 9, no
+legend, no gridlines) reads better and stays editable. Two or three word-sized
+charts beat a wall of block characters.

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

@@ -0,0 +1,63 @@
+# Chart choice and audit
+
+A chart earns its place when it makes a comparison, a trend, a distribution, or a
+relationship easier to see than a table would. If the reader only needs the
+figures, a compact table or a KPI tile is better — and cheaper to check.
+
+| Question | Default | Notes |
+| --- | --- | --- |
+| Compare and rank categories | Column or bar, sorted by value | Horizontal bar for long labels |
+| Change over time | Line, chronological left to right | Area only when the volume under the line means something |
+| Distribution of values | Histogram (formula bins + bar) | Box-and-whisker when median and spread matter and the engine supports it |
+| Relationship between two numbers | Scatter | Never a line chart over unordered pairs |
+| Share of a whole | Sorted bar, or a table | Pie/doughnut only for two or three slices, rough share |
+| Exact values | Table | A chart cannot carry precision |
+| One metric with context | KPI tile plus a small line | Sparkline-style bars only if the sheet is dense |
+
+## Honesty
+
+- Series must read from cells, not from typed arrays, and derived values must be
+  formulas. A chart of pasted numbers drifts the moment the table updates.
+- Include zero on bar, column, and area axes. Narrowing a line or scatter axis is
+  acceptable when the limits are stated; a truncated bar axis turns a 5% change
+  into a dramatic cliff.
+- No 3-D, no shadows, no gradients. They occlude data and date the workbook.
+- One period, one baseline, one unit across comparable charts. Disclose omitted
+  periods and missing values; do not let a blank read as zero.
+- Sort categories deliberately (by value, or by the natural order of time), and
+  keep the same order across charts that will be compared.
+
+## Formatting rules that catch reviewers' eyes
+
+- Title states subject and unit: `Profit by category ($m)`, `Monthly revenue
+  (USD)`. No placeholder titles, no legend standing in for a title.
+- Units in the title or on the axis: `($K)`, `($M)`, `(USD thousands)`. Never
+  `($000)`.
+- Axis number formats are set on the chart. Source cell formats do not carry over,
+  and a `0.0%` column can still produce `0.06, 0.08` ticks.
+- Few series: direct labels. More series: legend above the plot area, consistent
+  colours per series across the workbook.
+- Single series: no legend, one colour. A reference or target line is neutral or
+  dashed so it does not read as another data series.
+- Selective data labels only — the last point, the maximum, the one the user asked
+  about. Ten labels on a twelve-point line is a table with extra steps.
+- Line strokes are set explicitly; a fill alone may not colour an exported line.
+
+## Placement
+
+Charts sit next to the data they describe, aligned to a column edge, over empty
+cells, and never over the data, the controls, or a note. Size them to their
+content; a chart stretched across the page with two bars in it looks unfinished.
+
+## Verifying a chart
+
+1. Read the object back: type, anchor, series count, category source.
+2. Render and look at the image: are there categories, is anything clipped, is the
+   legend empty, do the bars reach the values in the table?
+3. Compare the visual against the sheet's numbers at one or two points.
+4. Re-open in the app the user will use if the colours matter — an authoring
+   preview is not proof that a filled series exports as a visible line.
+
+If the chart cannot be delivered as asked (the engine has no box plot, the data
+cannot be rearranged), say so and use the closest clear alternative. Never claim a
+requirement was met by a chart that does not show it.

package/assets/skills/office-spreadsheets/references/domain/financial-models.md

@@ -0,0 +1,40 @@
+# Financial models
+
+Applies to forecasts, budgets, cash-flow plans, and valuation work in any
+industry.
+
+- Periods run left to right with the scale in the header (Actual, Forecast,
+  Budget). Do not mix a monthly column with a quarterly total in the same row
+  without a labelled total column at the edge.
+- Drivers first, results second: volume × price, headcount × cost, days × rate.
+  A revenue row that jumps straight to a number cannot be reviewed.
+- Units are stated once and kept: thousands vs millions in the same block is the
+  classic reconciliation failure. Put the unit in the title, not in a footnote.
+- Three statements or none: if the workbook includes a balance sheet and a cash
+  flow, the balance sheet must balance and closing cash must equal the cash-flow
+  ending balance. Add those as checks, not as comments.
+- Working capital moves: receivables from revenue × DSO, payables from cost × DPO,
+  inventory from COGS × days. Hard-coded changes in working capital break when the
+  drivers move.
+- Scenarios: one selector, one set of case inputs per driver, and an explicit
+  `Case Selected:` on each output. A workbook with two switch cells reports two
+  answers.
+- Never hard-code a total that already exists as a sum, and never sum a column that
+  already contains a total (double counting is silent).
+- Sensitivity: one or two variables, closed-form or a small grid with the base case
+  marked. A native What-If Data Table is a different object with its own limits —
+  only build one when the user asks for it and the engine supports it.
+
+## Checks a finance reader looks for first
+
+| Check | Expected |
+| --- | --- |
+| Balance sheet balances | Assets − Liabilities − Equity = 0 |
+| Cash ties | Closing cash on the balance sheet = cash-flow ending balance |
+| Sum of segments | Segment revenue = consolidated revenue |
+| Period total | Sum of monthly columns = annual total column |
+| Case consistency | Every tab shows the same selected case |
+| No hard-coded totals | Total cells are formulas |
+
+Put them on a check tab, terminal and read-only, and make a failing check visually
+obvious without painting passing checks green.

package/assets/skills/office-spreadsheets/references/domain/healthcare.md

@@ -0,0 +1,22 @@
+# Healthcare operations
+
+Workbooks here usually track volume, capacity, cost, and quality — not patients.
+Treat patient-level data as sensitive: do not paste identifiers into a workbook
+unless the user asks for it, do not copy rows from files you were shown into new
+sheets, and prefer aggregates.
+
+- Name the denominator in every rate: per patient day, per discharge, per 1,000
+  members, per available bed. A percentage without its base is not a metric.
+- Volume and capacity are different columns. Utilization is
+  `used ÷ available`, and both sides need the same period and unit (bed-days, not
+  beds).
+- Payer mix, service line, and site of care are separate dimensions. One table with
+  a column per dimension beats four tables that must be read together.
+- Quality and safety metrics keep their own definitions; do not average a rate
+  across sites without stating whether it is volume-weighted.
+- Claims and remittance data arrive with gaps. Show missing as blank or `n.a.`,
+  never as zero, and state the coverage period.
+- Do not invent clinical thresholds, targets, or compliance claims. Use the
+  targets the source file provides, and cite the sheet and cell.
+- Money and counts follow the finance conventions: units stated once, totals as
+  formulas, checks that detail rows reconcile to the summary.

package/assets/skills/office-spreadsheets/references/domain/marketing.md

@@ -0,0 +1,28 @@
+# Marketing and advertising
+
+Campaign work is a funnel plus a spend table, and both are easy to make look
+better than they are.
+
+- One row per campaign, channel, or creative — with that grain named in the header.
+  Mixing a channel total into a campaign table double counts.
+- The funnel reads spend → impressions → clicks → conversions → revenue, in that
+  order, with rates derived by formula: `CTR = clicks / impressions`,
+  `CVR = conversions / clicks`, `CPA = spend / conversions`,
+  `ROAS = revenue / spend`.
+- Never compute a ratio from cells that are not the same period and the same
+  population. A monthly CTR built from a quarterly spend and a weekly click count
+  is a number nobody can defend.
+- Attribution is a claim: say which model the numbers use (last click, platform
+  reported, blended) and keep it constant across the table. Do not add platform
+  conversions together and call it incremental revenue.
+- Missing spend or reach for a period is blank, not zero — a zero-spend month
+  shows an infinite CPA and a fake collapse in the trend.
+- Benchmarks and targets belong in a labelled row or column with their source, not
+  in a note the reader has to find.
+
+## Charts for marketing
+
+Spend and return on the same chart only when both are in the same unit; otherwise
+two aligned charts. Sort channel bars by spend or by return — not alphabetically —
+and keep the same order across charts. A conversion trend belongs on a line chart
+with the campaign launch dates marked, not on a pie.

package/assets/skills/office-spreadsheets/references/domain/research.md

@@ -0,0 +1,22 @@
+# Scientific and research data
+
+The spreadsheet is usually a working copy of measurements, not the record of
+truth. Keep it that way: never edit raw measurements in place, and never let a
+formatted view replace the values behind it.
+
+- Raw data on its own sheet, untouched, in columns whose headers carry the unit
+  (`time (s)`, `temp (C)`, `conc (mg/L)`). Derived columns live on a build sheet
+  and reference the raw cells.
+- One row per observation, one column per variable. Do not encode a variable in a
+  colour, a note, or a header font.
+- Replicates are separate rows with a replicate id and a group id; the mean and
+  standard deviation are formulas over those rows, never typed.
+- Keep the precision the instrument gives you and let the format hide extra
+  decimals. Rounding stored values destroys the ability to recompute a mean.
+- Uncertainty, detection limits, and excluded points are stated in labelled cells.
+  An excluded point stays in the data with a reason column — deleting it hides the
+  decision.
+- Smoothing, binning, and unit conversion are formulas with visible inputs, or they
+  do not exist. A trend line drawn over noisy points is not an analysis.
+- Distribution, trend, and relationship: choose the chart by the question, and
+  check that the axis ranges and bins are stated (`references/charts.md`).

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

@@ -0,0 +1,78 @@
+# 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.
+
+## Anchoring
+
+| Reference | Moves when filled | Use for |
+| --- | --- | --- |
+| `C8` | both ways | A grid where every cell looks at its own row and column |
+| `C$4` | down only | A header row of periods |
+| `$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.
+
+## 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.
+
+## Dates and periods
+
+- 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.
+
+## 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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,69 @@
+# 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.
+
+## 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.
+- 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.
+- 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.
+
+## 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.
+
+## 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.
+- 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.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,60 @@
+# 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.
+
+| Role | Holds | Feeds |
+| --- | --- | --- |
+| Input / Sources | Pasted exports, system extracts, unchanged source tables | Builds |
+| Assumptions | Rates, drivers, the case selector, global inputs | Builds |
+| Build | The visible calculation steps between inputs and outputs | Outputs |
+| Output / Summary | Consolidated results, the numbers a reader came for | Nothing downstream |
+| Check / Audit | Diagnostics that compare what should reconcile | Nothing — terminal and read-only |
+| Cover / ReadMe | A short front page, or an explanation of method and joins | Nothing |
+
+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.
+
+## 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.
+
+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.
+
+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.

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

@@ -0,0 +1,36 @@
+# 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.
+
+## 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.
+
+## When writing formulas for a file that will go 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`.
+
+## 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.

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

@@ -0,0 +1,37 @@
+# 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.
+
+## 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.
+
+## 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.
+- 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.

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

@@ -0,0 +1,51 @@
+# 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:
+
+```json
+{
+  "target": "book.xlsx",
+  "fileName": "book.xlsx",
+  "text": "",
+  "requirement": "make this column currency",
+  "region": { "left": 0.42, "top": 0.51, "width": 0.18, "height": 0.30 },
+  "imageName": "book-page-1.png",
+  "unmapped": true
+}
+```
+
+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.
+
+## 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.