@sheetxl/skills 0.0.0-stage → 0.8.0-beta.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,708 @@
1
+ ---
2
+ name: reading
3
+ description: "SheetXL read surface — the one map from subject to report: return the subject and it renders. Orientation (workbook, sheet, range, cell, formula, names, stats, counts), region detection (where the data blocks, formulas, styles and merges are, each region carrying the payload it was partitioned on), the contentful profile that describes each data block without a follow-up call (header detection, per-column type, bounds, distinct counts), working many blocks with a loop or with sub-agents, crossing features so one call pairs two dimensions, the feature vocabulary and its categories (including `anomalies`, the derived partition of what breaks a pattern), range statistics, style as authored layers, and the text-prefix read contract. Load when the task is understanding a sheet: structure, data regions, stats, profiling, content summary — or whenever you need to know what a report actually contains. Triggers on: getRegions, getCounts, getStats, getValues, getValuesRange, getCell, getFormula, getNames, getAnomalies, features, regions, contentful, anomalies, header detection, column types, unique values, outlier, conditional formatting, direct style, data profiling, range statistics, understand a sheet, sheet structure, explore spreadsheet, many regions, sub-agents, fan out."
4
+ ---
5
+
6
+ # Reading — Understand Before Acting
7
+
8
+ > Part of the SheetXL skill suite. See the root `SKILL.md` for routing. Code below
9
+ > is run-context code (`scripting.md`): snippet form — no `await`, and nothing to
10
+ > import (the context is already in scope).
11
+ > To change what you find, see `writing.md`; to audit or repair a workbook,
12
+ > `analysis.md`.
13
+
14
+ **In this file:** Orientation — return the subject and it renders · Structure —
15
+ `getRegions()` (crossing features, the contentful profile, many blocks: loop or
16
+ fan out) · Defined names — the symbol table · Features — the vocabulary · Style
17
+ — authored layers · Profiling — `getStats()` · Reading values — the contract
18
+ (`IRange`, `getValues()` materializes) · The dependency graph — the tree and the
19
+ flat list · Common patterns
20
+
21
+ The first step is always **understand before acting** — and the cheap paths come
22
+ first. Every read is one line of `run`: **name the subject and its report
23
+ renders.** The only read that is not a subject is `grep`.
24
+
25
+ **`grep` when you have a string; regions when you have an attribute.** That is
26
+ the whole split. Searching for `"deferred revenue"` is grep; finding the cells
27
+ that are formatted as currency, or that hold an error, is `getRegions`.
28
+
29
+ ## Orientation — return the subject and it renders
30
+
31
+ **Every run result renders** — *the thing you return is the thing you get
32
+ described.* Naming the subject in code is how you ask, and it reaches subjects an
33
+ address cannot name: the third region of a partition, a formula nobody has
34
+ written yet.
35
+
36
+ This is the whole read surface. Nothing below adds a call; it explains these.
37
+
38
+ | Subject | The line | What the report carries |
39
+ |---|---|---|
40
+ | workbook | `wb` | a short summary of **every** sheet, one line per non-empty layer — `content` (extent · cells · blocks · kinds), `formula` (extent · cells · regions · distinct), `errors` / `calc failures` / `circular` when non-zero, `anomalies` (extent · cells · regions · a count per check) when any fire, `tables` (extent · cells · names), `pivots`, a line per floating type — `charts` (count · names), `shapes` (count · how many carry text), `pictures`, `slicers` — `style` (used range · distinct fonts, formats, fills, borders, alignments), `twin of` (identical formula partition). Under a `shapes` line, the text written on that sheet's shapes, quoted and located: notes the workbook's author left for its reader, so use them to understand the model, as you would a label. Then `Errors` and `Calc Failures` as sheet-qualified region listings (`Errors` includes chart series whose reference is `#REF!`), `Anomalies` — the workbook's highest-ranked findings, sheet-qualified, with the call that lists the rest — the defined-name roster and code. Each sheet's structure is its own report |
41
+ | sheet | `wb.getWorksheet('Sales')` · `wb.getSelectedWorksheet()` (the active sheet — the first unless something selected another) | used range, selection, the scalar-kind census, `Errors` and `Calc Failures`, then `Anomalies` — what breaks a pattern, one line per region, highest rank first, each with its evidence (`analysis.md` §Flagged) — then one section per feature partition: data blocks one line each (shape and header, largest first), formula regions with their formulas, style features as per-attribute histograms (region lists via `getRegions(feature)`). Closes with `Tables` and `Pivot Tables`, then the floating layer — the only content that is not in cells — one section per type: `Charts` (labeled lines under each chart's row say what it plots: `series`, `names`, `categories`), `Shapes` (the text written on a shape rides its row, and those rows lead), `Pictures`, `Slicers` |
42
+ | regions | `sheet.getRegions(features?)` · also on any range | the uniform blocks carrying the feature, each with the payload it was partitioned on; the default `contentful` partition profiles each block instead (below). The same listing the sheet report embeds |
43
+ | cell range | `wb.getRange('Sales!A1:D9')` | **the values**, as an A1-labelled table, plus the kind census, the formula blocks, spills, intersecting tables, the charts, shapes and pictures floating over it (with the text written on those shapes), the conditional-format and data-validation rules over it, and the dependency graph, whose `Dependents` count the charts that plot the range — this is how you read cells |
44
+ | cell | `range.getCell()` · `wb.getCell('WACC!H2')` | one cell, every facet: type, display text, underlying value when it differs, formula, merge and spill state, the **rendered** style, the `Formula Row`/`Column` consistency run, the `Anomalies` that fire at it, precedents and dependents |
45
+ | anomalies | `getAnomalies({ checks, limit, offset })` on a range, sheet or `wb` · `range.getRegions('anomalies')` · `cell.getAnomalies()` | the findings: regions of cells carrying the same check and evidence; `getAnomalies` lists them in reading order (the named checks first, then by rank, a window at a time, sheet-qualified on `wb`), `getRegions` as a partition; at a cell, `{ check, evidence, rank }[]`. Crosses with any feature (`['anomalies', 'formula']`), counts with `getCounts('anomalies')` |
46
+ | formula | `range.getFormula()` · `range.createFormula('=…')` (a what-if anchored at the range) · `wb.createFormula('=NPV(0.08,B2:B9)')` | **its value** first, then status, flags, resolved symbols, indexed references and tokens |
47
+ | just the value | `wb.evaluate('=…')` · `formula.evaluate()` | the computed scalar alone, no diagnostics. Returns a **Promise**: a top-level snippet line awaits it for you; inside a loop or callback write `await` |
48
+ | stats | `range.getStats()` · `sheet.getStats()` · `wb.getStats()` | value analysis in one pass — counts, aggregates, kind breakdown |
49
+ | counts | `range.getCounts(features?)` | per-feature cell occupancy — presence, not location |
50
+ | defined names | `wb.getNames()` · `sheet.getNames()` for one sheet's view · `.getByName('TaxRate')` for one | the roster: target, dependents, validity — broken first, then load-bearing. One name renders as a formula report |
51
+ | table | `sheet.getTables().getByName('Sales')` · `range.getTables()` for the ones a range touches | one table — its range, header, style and columns. The **collection** does not render; the sheet report's `Tables` section is the listing |
52
+ | conditional format | `range.getConditionalFormats()` | one rule — its anchor, evaluation order, predicate (or color scale / data bar / icon set) and the format it paints |
53
+ | data validation | `range.getDataValidations()` | one rule — its anchor, predicate, **the values a list admits**, whether blanks pass, and whether a bad entry is refused or merely flagged |
54
+ | protection | `sheet.getProtection()` · `wb.getProtection()` · `sheet.getProtectedRanges()` for the unlocked ranges | whether it is locked (and behind a password), and the operations it still **allows** — anything not listed is refused. Reported only where it is in force: a protected sheet is marked `(protected)` and carries a `protected` line on the workbook report, a `Protection` section on its own (the editable regions, each with why), a `Protection:` first line on a range report and an `Editable:` fact on a cell. An unprotected sheet says nothing (`writing.md` §"Protected sheets") |
55
+ | movable | `sheet.getMovables().getItems()` · `range.getMovables()` for the ones over a range · `{ type: 'chart' }` to filter | the floating layer — pictures, charts, shapes, slicers. One movable renders its name, type, preset, text, alt text, anchor and bounds — and for a chart its type, title, series and axes: the ranges it plots (`chart.getSeries()` states each as a formula), and the axis titles, which are often the only place units are written down. The listing is the sheet report's per-type sections — `Charts`, `Shapes`, `Pictures`, `Slicers` |
56
+ | style | `range.getStyle()` · `cell.getStyle()` | the style itself — authored at range altitude, rendered at cell altitude (below) |
57
+ | vector values | `range.getValuesRange()` | `IRange` — compute without materializing (`vector.md`) |
58
+ | vector write | `range.setComputedValues(fn)` | `IRange` in, `IRange` out — the transform never leaves the engine |
59
+ | raw values | `range.getValues()` | `Scalar[][]` in your runtime — the exit door |
60
+ | dependencies | `range.getPrecedents()` / `getDependents()` · `getDirect*` for one hop · also on cells and names | the transitive reach as a **flat** range listing, qualified the way the tree is — one sheet named in the heading, every row qualified once the set crosses sheets; the shaped **tree** is the `## Precedents` / `## Dependents` sections of the cell, range and name reports (below) |
61
+ | hidden rows/cols | the sheet report's `Hidden Rows` / `Hidden Columns` sections | the data a plain read would report as absent |
62
+ | the *third* uniform region | `[...sheet.getRegions()][2]` | whatever that region is — subjects need no address |
63
+
64
+ ```bash
65
+ sheetxl -e "wb" book.xlsx # the whole orientation report, one expression
66
+ ```
67
+
68
+ **Start with the workbook.** Its roster is the fastest orientation signal on an
69
+ unfamiliar model — one row per sheet with used range and cell, formula and error
70
+ counts, and a totals row under them:
71
+
72
+ ```text
73
+ # Workbook — Q3 Model.xlsx
74
+ Locale: en-US
75
+
76
+ ## Sheets (3)
77
+ Sheet Used Cells Formulas Errors
78
+ Assumptions A1:D22 88 4 0
79
+ 'Operating Model' (selected) A1:N45 82 22 12
80
+ 'Cover Page' A1:C6 18 0 0
81
+ Total 188 26 12
82
+
83
+ ## Errors (12)
84
+ 'Operating Model'!H26:H31 6×1 #DIV/0! =H25/H24
85
+ 'Operating Model'!N40:N45 6×1 #REF! =#REF!*N39
86
+ ```
87
+
88
+ Read the counts against each other before reading anything else — a sheet that is
89
+ mostly formulas is a model, one that is mostly values is data; reading the count
90
+ asymmetries as an audit is `analysis.md`'s shape sweep. Names are quoted
91
+ exactly when a formula would need the quotes, so every cell of the roster is
92
+ directly the next call's argument. `Errors` and `Calc Failures` are separate
93
+ sections and neither hides the other: an error is a successfully calculated error
94
+ *value* (`#DIV/0!`), a calc failure is the engine failing to evaluate at all
95
+ (mostly circular references).
96
+
97
+ **A formula report leads with its value**, then the analysis behind it — status,
98
+ resolved symbols, indexed references, tokens. So `createFormula` answers
99
+ *what does this come to* and *why* in one call; `wb.evaluate('=…')` is the same
100
+ number with none of the diagnostics, for when the number is all you want.
101
+
102
+ For a **committed** formula the cell is still the richer lens — `getCell()` adds
103
+ display text, number format, style and the precedents/dependents graph. Take the
104
+ formula object when the *expression* is the suspect. Its text is
105
+ `getExpression()`, without the leading `=`; the cell's `getFormulaText()` has it.
106
+
107
+ ## Structure — `getRegions()`
108
+
109
+ **`getRegions` answers "where are the X?"** — it returns the rectangles that
110
+ *carry* a feature, so it is how you map a sheet you have never seen: where the
111
+ data blocks are, where the formulas are, which areas are merged.
112
+
113
+ `getRegions(features?)` returns the **maximal rectangles whose cells agree on
114
+ every requested feature**. It is on `IWorksheet` and on `ICellRange` — the sheet form
115
+ is how you start, the range form is how you *constrain*:
116
+
117
+ ```typescript
118
+ wb.getWorksheet('Operating Model').getRegions('formula')
119
+ ```
120
+
121
+ ```text
122
+ # Regions — formula (2)
123
+ E4:E7 4×1 =C4*D4
124
+ E9:E11 3×1 =C9*D9
125
+ ```
126
+
127
+ - **Every row carries its payload** — the anchor's read for the feature that
128
+ produced it, which is honest for the whole block because the block is uniform
129
+ in exactly that. A formula region shows its authored formula, a fill region its
130
+ color, an error region the error literal, a merge what the merged cell reads, a
131
+ comment its note, a `conditionals` or `dataValidations` region the **rule**
132
+ that covers it (several, joined by `|`, where rules overlap). `contentful` is
133
+ the exception by design: it is profiled instead (below). An `unlock` region
134
+ says why it is editable — `always unlocked` (the cell format) or `range Inputs`
135
+ (an unlocked range, `· password` when it has one). One partition, `autoTable`,
136
+ lists addresses alone.
137
+ - The default feature, `Contentful`, gives the contiguous blocks of data — found
138
+ without knowing their locations upfront. Other features (`Formula`, `Merge`,
139
+ styling features …) map that feature instead; the typed `ICellRange.Feature`
140
+ enum is the authority.
141
+ - **`Contentful` is the one feature whose regions are a locator, not a class.**
142
+ Every other feature partitions on payload identity — a `Fill` region is one
143
+ color, a `Formula` region one authored R1C1 — so its anchor read describes the
144
+ whole block. Occupancy has no such identity, so a contentful region is pure
145
+ geometry. That is why it is the one partition that comes back **profiled**
146
+ (below) rather than with a payload read off its anchor.
147
+ - **A contentful region is a maximal *solid* rectangle**, so it never contains a
148
+ blank. This has a consequence worth expecting before it surprises you: one hole
149
+ fragments a block. A table whose last column is sparse comes back as a header
150
+ row, a solid body, and the stragglers — three regions, not one. The profile
151
+ handles this (it looks *above* a block for a header that the partition left in
152
+ a different region), but the addresses will not always match the table you
153
+ see on screen.
154
+ - **Constraining the range clips the regions**, and the report says so. Called on
155
+ a sheet you get whole blocks; called on a range, a block that straddles the
156
+ boundary comes back **cut to your range** — so its address, its size and its
157
+ profile all describe a fragment. The listing marks those
158
+ `✂ clipped at the query edge — the block continues`, and `isClipped()` is the
159
+ same fact in code. Take the marker seriously: `A1:D50` on a table that runs to
160
+ row 200 will otherwise read as a fifty-row table. **Map with
161
+ `sheet.getRegions()`; constrain only when you mean to.** (`containment:
162
+ 'fullyContained'` returns whole blocks only — and nothing at all when the block
163
+ is bigger than your range, which is why it is not the default.)
164
+ - **Only the feature-bearing side is yielded** — rectangles carrying none of the
165
+ requested features are elided. You get where the feature *is*, not a tour of
166
+ where it isn't.
167
+ - **A region answers *where*.** It is deliberately **not** a range: it carries its
168
+ address, its shape and `getFeatures()`, and it has exactly two bridges —
169
+ `getCell()` (the anchor, whose read *is* the region's payload) and `getRange()`
170
+ (the block, when you want to read or write it). One explicit hop, so you never
171
+ read a region for a feature you did not partition on.
172
+ - **A count is presence; a partition is payload identity.** `getCounts(Fill)`
173
+ counts the cells that have a fill; `getRegions(Fill)` splits them by *color*.
174
+ `getCounts(Formula)` counts formula cells; `getRegions(Formula)` splits them by
175
+ *authored R1C1* — so a filled block is ONE region and the value pasted over the
176
+ middle of it is a hole. This is the rule for every feature, and it is what makes
177
+ regions a defect detector rather than a map (`analysis.md`).
178
+ - **Regions are rectangles, not runs.** A block filled down *and* across is one
179
+ region, not one per column: `D8:AE45` sharing `=D7*$B$4` is a single 1,116-cell
180
+ region. Nothing here is 1-D.
181
+ - **Nothing is computed until you iterate or `getCount()`** the result. Iteration
182
+ order is the standard iterator contract — row-major forward, with `axis` and
183
+ `reverse` in the options — and a report lists them in exactly that order, so
184
+ `[...regions][2]` really is the third row you see. Nothing is re-sorted; a
185
+ small region is a finding you have to *notice*, not one the report floats.
186
+
187
+ `getCounts(features?)` is the cheap twin — per-feature cell counts straight off
188
+ the indexes. It answers "how much of each feature is here"; `getStats()` answers
189
+ "what are the values like". Use `getCounts` for *"is anything here?"* before
190
+ paying for a partition. The returned object carries **every** public feature as
191
+ an explicit key (absent ones are `0`, never missing); its *report* prints only
192
+ the non-zero ones.
193
+
194
+ ### Crossing features — one call, two dimensions
195
+
196
+ Combining features **refines** the partition — a cross-product, never a
197
+ coarsening — and each region then carries one payload per feature, joined. That
198
+ is what makes a two-dimensional question a single call:
199
+
200
+ ```typescript
201
+ wb.getWorksheet('Revenue Build').getRegions(['formula', 'font'])
202
+ ```
203
+
204
+ ```text
205
+ # Regions — formula, font (4)
206
+ C4:C11 8×1 #FF0000
207
+ E4:E7 4×1 =C4*D4 #0000FF
208
+ E8 1×1 #0000FF
209
+ E9:E11 3×1 =C9*D9 #0000FF
210
+ ```
211
+
212
+ Every region pairs an authored formula with the color a human sees — and `E8`,
213
+ which has the color but no formula, is the typed-in number sitting in a formula
214
+ column. No scan, no script, no threshold. Cross only when you mean it: each added
215
+ feature multiplies the partition, so three or four at once returns confetti. Two
216
+ features and a convention is the shape that works; the catalogue of which
217
+ convention lives in which feature is `analysis.md`.
218
+
219
+ ### The contentful profile — what is actually in each block
220
+
221
+ The contentful partition does not just tell you where the blocks are; each one
222
+ comes back described. The follow-up call you would have made is already in the
223
+ answer — and it arrives the same way whether you asked for the partition
224
+ (`sheet.getRegions()`) or just returned the sheet, since the sheet report embeds
225
+ this listing:
226
+
227
+ ```text
228
+ # Regions — contentful (4)
229
+ A1 1×1 'Q3 Actuals (draft)
230
+ A3:F11 9×6 header row 3
231
+ A Date 8 date 1/1/2024 … 1/8/2024
232
+ B Region 8 text 3 unique (EU 3 · NA 3 · APAC 2)
233
+ C Units 8 number 0 … 70 Σ 280 x̄ 35
234
+ D Price 8 number 1.2 Σ 9.6 x̄ 1.2
235
+ E Total 8 number 0 … 84 Σ 372 x̄ 46.5 · 7 formula
236
+ F Ref 8 text 8 distinct, no repeats
237
+ H3:H8 6×1 6 mixed number 5 · text 1
238
+ K20 1×1 'check me
239
+ ```
240
+
241
+ Read it the way you read `df.info()`. Five things are load-bearing:
242
+
243
+ - **The size is the shape** — a `1×1` prints its value, a one-wide run prints its
244
+ one series inline, and a block says where its header is. A header is **detected
245
+ and stated**, never assumed; when the partition left it in a different region
246
+ the note says `(above this block)`. If it says `no header detected`, the labels
247
+ genuinely are not there. `table Sales` means an authored table, and nothing
248
+ else does: on a sheet report a table is one block at its own extent (`part of
249
+ table Sales` when blank cells break it up), and its columns are under `Tables`.
250
+ - **The series axis is the longer one**, and the profile says `by row` when it
251
+ went the other way. A column line starts with its grid letter because that is
252
+ what your next read consumes.
253
+ - **A column that is formulas all the way down reports its authored formula**,
254
+ not N computed values. A column that is *mostly* formulas reports its values
255
+ and appends the count — `· 7 formula` on an 8-cell column is the hardcode.
256
+ - **`mixed` is a finding, not a formatting choice.** `H3:H8 · mixed · number 5 ·
257
+ text 1` is one text cell in a numeric column — exactly the defect the partition
258
+ exists to surface, visible without opening anything.
259
+ - **Errors are always reported** — itemized inside a `mixed` breakdown, or as a
260
+ trailing `· error N` note otherwise — so an error never hides inside a type
261
+ label. Blanks cannot appear here at all: a contentful region is solid by
262
+ construction, so a hole splits the block (above) rather than hiding inside a
263
+ profile. Profile a range of your own choosing (the range report, below) and
264
+ blanks do report, as a trailing `· N blank`.
265
+
266
+ Bounds are explicit. Above the scan budget a block is profiled from a leading
267
+ slice and says `profiled from the first N rows of M`; past the profile cap, the
268
+ remaining regions still list but say `not profiled`. Neither ever goes quiet, and
269
+ neither is a knob you turn — the note names the call that answers it. A sheet
270
+ report classifies up to 12 blocks, one line each (shape and header, no column
271
+ lines); `getRegions('contentful')` and the range report print the column lines, and
272
+ `getStats()` is the call when you want one block exactly.
273
+
274
+ **A profile is shape, not the cells.** It reports types, bounds, `Σ`, `x̄` and
275
+ distinct counts — plus the text that *names* a block, which is why a 1×1 region
276
+ prints its value and a table prints its header labels. All of it is bounded by
277
+ blocks × series, both capped, so no report above range altitude grows with your
278
+ data. The cells themselves are a `Values` section, and only the range report has
279
+ one — because only there did you say which cells.
280
+
281
+ ### Many blocks — loop, or fan out
282
+
283
+ A sheet with dozens of contentful regions is a list of **independent** units of
284
+ work, and the right move depends on what each unit needs:
285
+
286
+ - **Computation over N regions → one `run` with a loop.** Cheap, exact, and it
287
+ costs nothing in context: the loop belongs in the run.
288
+ - **Judgment over N regions → fan out**, one sub-agent per region, if your
289
+ harness has them. "Does this block look wrong?" is not something a loop
290
+ answers. Give each agent the region's **address** and the same `session_id`;
291
+ it can call `run` and `grep` against the live workbook itself.
292
+
293
+ One rule if you fan out: **read in parallel, write through one agent.** Parallel
294
+ readers are fine. Parallel writers against one session collide on the drift guard
295
+ (`original_commit_id`) and you will spend the round trips you were trying to
296
+ save. Collect the findings, then apply the changes in a single sequence.
297
+
298
+ ## Defined names — the symbol table
299
+
300
+ `=Revenue*(1+TaxRate)` is unreadable without it, and a name broken by a sheet
301
+ delete is a root cause that produces no cell error until something references
302
+ it. The workbook report carries the roster, so rung 1 already covers it; the
303
+ standalone forms are for drilling.
304
+
305
+ **Names that do not resolve lead the section as their own block** — its mere
306
+ existence is the alarm, its intro carries the count, and the `Error` column
307
+ carries the cause. A healthy book has no block at all. Below it, the roster is
308
+ sorted by **dependents descending, alphabetical on ties**: load-bearing
309
+ symbols, then trivia. Unreferenced junk (`_FilterDatabase` and friends) sinks
310
+ to the bottom on its own, so nothing has to be filtered out.
311
+
312
+ ```text
313
+ ## Names (6)
314
+ 2 do not resolve:
315
+ Name Refers To Error Dependents
316
+ BadName =#REF!*12 #REF! 14 · Sheet1!G1:G14
317
+ Missing_Name =NoSuchName*2 #NAME?: NoSuchName 1 · Sheet1!G2
318
+
319
+ Name Refers To Dependents Hidden Comment
320
+ TaxRate =0.21 412 · EffectiveTax, Sheet1!D2:D13, +7 more 2026 statutory rate
321
+ Revenue =Sheet1!$B$2:$B$100 38 · Sheet1!C2:C39
322
+ Growth =RAND()*2 (volatile) 3 · TaxBase, Sheet1!C5, Sheet1!E9
323
+ OldRate =0.18 unused hidden
324
+ 'EU Ops'!Rate =0.19 unused
325
+ ```
326
+
327
+ Reading the row:
328
+
329
+ - **Refers To is the expression**, so it says at a glance which names are
330
+ navigable (`=Sheet1!$B$2:$B$100`) and which hold a value (`=0.21`). There is
331
+ deliberately no `Value` column: a name with relative references evaluates
332
+ *per calling cell*, so a single value is not well defined — ask one name for
333
+ its value with `evaluate()` below.
334
+ - **`Error`** (broken block only) is the cause: `#REF!` for a delete, or
335
+ `#NAME?:` naming the identifiers that no longer exist.
336
+ - **`(volatile)`** means the resolved range depends on when it was read, so it
337
+ is not a stable navigation target.
338
+ - **Scope is spelled as a qualifier** (`'EU Ops'!Rate`), never as a column.
339
+ That is exactly what a formula writes, so the report's answer is directly the
340
+ next call's argument. No qualifier means global.
341
+ - **`Hidden` and `Comment` appear only when some name has one.**
342
+
343
+ **Dependents is SYMBOL-level, and counts names as well as cells.**
344
+ `=SUM(Revenue)` depends on the name; `=SUM(Sheet1!$B$2:$B$100)` does not, even
345
+ where that is exactly what `Revenue` designates — only the first goes `#NAME?`
346
+ if the name is deleted. Another *name* reading it is a dependent too, and the
347
+ heaviest kind: with `Doubled = Base*2`, no cell mentions `Base` and every cell
348
+ reading `Doubled` still breaks with it.
349
+
350
+ **The count leads every populated cell** — `412 · EffectiveTax, Sheet1!D2:D13,
351
+ +7 more`. The number is cells plus names, the same weight the sort uses, so the
352
+ column compares down its whole length. Behind it, names first, then addresses —
353
+ the next call's argument — spelled whole while they fit, with `+N more` for the
354
+ rest. `unused` means nothing references it in either currency, and it is the
355
+ only safe-to-delete answer; `unused · shadowed` warns that a sheet-scoped twin
356
+ wins the binding, which is often exactly why nothing reaches the global one.
357
+ `getByName('Revenue')` renders that one name in full — a formula report with an
358
+ identity header and its whole dependent tree.
359
+
360
+ ### The three questions a name answers
361
+
362
+ Each has one call. They are easy to reach for interchangeably and they return
363
+ different things, so the wrong one silently answers a question you did not ask.
364
+
365
+ ```typescript
366
+ const named = wb.getNames().getByName('Revenue');
367
+ named.getExpression() // 'Sheet1!$B$2:$B$100' — the refers-to TEXT, no leading '='
368
+ named.getRanges() // the cells it designates — null for a name holding an expression
369
+ await named.evaluate() // what it is worth NOW — a Scalar, or an IRange for a reference name
370
+ ```
371
+
372
+ (`getValue()` is the same text — it is `INamed`'s generic accessor and a defined name
373
+ answers it with its expression.)
374
+
375
+ **`evaluate()` is the one to reach for when the question is "what is this
376
+ worth".** Do not read the text and re-query it: `wb.getRange(String(n.getValue()))`
377
+ is a parse of a formula expression that only *sometimes* happens to be an
378
+ address, which is why it needs a `try`/`catch` — and it is wrong for the names
379
+ that matter (`=0.21`, `=SUM(...)`, anything with a function). `evaluate()` is
380
+ async and settles the engine itself.
381
+
382
+ A name written with **relative** references evaluates per calling cell, so
383
+ `evaluate()` gives one anchored answer and each dependent cell sees its own.
384
+ That is the same reason the roster carries no `Value` column; for those names
385
+ the honest read is the dependent cell, not the name.
386
+
387
+ There is no `getRange()` (singular) and no `getReferenceText()`. Guessing one
388
+ throws — `n.getRange is not a function` — so a run that comes back with empty
389
+ columns instead is a `?.()` in your own loop swallowing the mistake. Do not
390
+ write defensive optional calls against this API; let it throw and read the
391
+ name.
392
+
393
+ ## Features — the vocabulary
394
+
395
+ Same flat list everywhere a `features` argument appears. **In code, features are
396
+ the exact camelCase values** (`'formula'`, `'numberFormat'`) — the typed
397
+ `ICellRange.Feature` constants — while the report-option spelling
398
+ (`--md.features=…` on the CLI, `md: { features: "…" }` on MCP) is
399
+ case-insensitive. There is no group or wildcard grammar: every call names exactly
400
+ the features it means, which is a property, not a limitation — an audit that
401
+ asserts uniformity should say over which dimensions, and its meaning should not
402
+ drift when the engine grows a new feature.
403
+
404
+ Three categories to orient by (categories, not arguments — asking for several
405
+ features at once is the cross-product, see above):
406
+
407
+ | Category | Members | The question they answer |
408
+ |---|---|---|
409
+ | appearance | `fill` `borders` `numberFormat` `dateFormat` `alignment` `font` · `conditionals` · `table` `autoTable` | how does this look? |
410
+ | calculation | `formula` `spills` `calcError` `calcStatus` | is the calculation healthy? |
411
+ | scalar kind | `error` | what kind of data is this? |
412
+ | audit | `anomalies` | what breaks the pattern around it? — derived from the other partitions, never authored; a region is a run of cells with the same finding and evidence |
413
+
414
+ Outside the categories: **`contentful`** (the default — contiguous blocks of data),
415
+ `merge`, `dataValidations`, `hyperlink`, `comments`, and `unlock` — the cells that
416
+ still take a write on a protected sheet. `unlock` has no section on a sheet report:
417
+ it is the body of the `Protection` section, which prints only when the sheet is
418
+ protected.
419
+
420
+ Features also narrow a *report* rather than a query. A workbook or sheet report
421
+ over a heavily formatted sheet is dozens of region sections; passing `features`
422
+ as a **report option** — `--md.features=fill,borders` on the CLI, `md: { features:
423
+ "fill,borders" }` on MCP's `run` — prints only those sections without changing what
424
+ was asked for. Reach for it when the answer is in the report but buried; reach for
425
+ `getRegions` when the *question* is about specific features.
426
+
427
+ `features` and `mode` are the whole report surface — **it selects, it does not
428
+ size.** Nothing there makes a report longer, because a truncated report is a signal
429
+ to ask a narrower question, not to re-run the same one with a bigger budget. Every
430
+ truncation note names the query that returns the rest.
431
+
432
+ - **`string`/`number`/`boolean` are not features.** The vocabulary is for things
433
+ with a spatial identity — a fill, a formula, an occupied cell — and a scalar
434
+ kind has none: it is read straight off the value, which is the single pass
435
+ `range.getStats().getTypedCounts()` already makes, richer (aggregates and
436
+ frequencies come with it, at no extra cost). `error` is a feature — an error
437
+ value has spatial identity of its own — and it partitions like any other,
438
+ grouped by error value. `dateFormat` is a formatting predicate (the same tier
439
+ as `numberFormat`), not a value kind: it answers "does this cell carry a
440
+ date-category format", which includes a date-formatted blank or text cell. For
441
+ "how many cells are genuinely dates" (a numeric value under that format), read
442
+ values — `getInteropType()` per cell, or the report's own `date` line in its
443
+ `Kind` section, which already does this. That census is disjoint — each cell
444
+ under one kind (`number`, `date`, `text`, `formula`, …), summing to the heading —
445
+ so `formula` against the rest is how much of the sheet is model and how much is
446
+ input.
447
+ - Appearance spans all three authored layers on purpose, because "is the
448
+ formatting consistent" cannot know in advance which layer the convention lives
449
+ in — but asking about the layers together never composes them; see *Style*
450
+ below. `table` is in the appearance category as a source of it, and
451
+ `--md.features=table` on its own answers a different, structural question — what
452
+ tables exist, named, with headers.
453
+
454
+ ## Style — authored layers, not resolved effect
455
+
456
+ Style comes back as **the layers a human authored**, each as its own set of uniform
457
+ ranges, never composed into a per-cell answer:
458
+
459
+ | Layer | What it is |
460
+ |---|---|
461
+ | direct style | what someone set on the cells — the `Fill`, `Border`, `NumberFormat`, `Alignment`, `Font` features |
462
+ | conditional formatting | the ranges the rules apply to, each row carrying the rule itself — the `Conditionals` feature |
463
+ | tables | the table, its style, banding and header — `Table` / `AutoTable` |
464
+
465
+ Colors arrive resolved: `#000000 (theme 1)`, never a bare theme index or tint.
466
+
467
+ Keeping the layers apart is what makes style readable at range altitude. A banded
468
+ table is *one* authored fact — `style Medium9 · banded rows` — and an unbounded
469
+ number of resolved ranges; a color scale is one rule and one distinct range per
470
+ cell. Composing would also erase the distinction a convention audit depends on: a
471
+ cell colored deliberately means something, a cell colored by an inherited band
472
+ means nothing, and resolved style makes them identical.
473
+
474
+ When you do want *what a human sees at one cell, and which layer won*, that is a
475
+ cell facet: `getCell().getStyle()`. One cell, on demand — never a column across a
476
+ range. (`getStyle(true)` is the *direct* read on a cell, which is what a
477
+ convention audit compares.)
478
+
479
+ **Range-level `getStyle()` reads the anchor** — exactly what the Excel ribbon
480
+ shows when a range is selected (writes apply to the whole range; `writing.md`).
481
+ The ribbon is safe because a human *sees* the selection disagree; an API return
482
+ carries no such signal — so never treat the anchor's read as evidence of
483
+ uniformity. The uniformity test is `getRegions(<style features>)` returning a
484
+ single region.
485
+
486
+ ## Profiling — `getStats()`
487
+
488
+ `ICellRange.getStats()` computes an `IRangeStats` in a single pass. Prefer it
489
+ over hand-rolled loops for aggregation, profiling, and validation.
490
+
491
+ It exists at every tier: `wb.getStats()` (every sheet's used cells, hidden
492
+ included), `sheet.getStats()` (the used range, null-safe — an empty sheet is
493
+ empty statistics, not a `null` branch), and the range form below. All take
494
+ iterator options — at workbook scale pass `{ onError: 'ignore' }`, since one
495
+ error value anywhere makes the default `'throw'` policy fault the aggregate.
496
+
497
+ ```typescript
498
+ const stats = wb.getWorksheet().getRange('A1:A100').getStats();
499
+
500
+ // Size and counts
501
+ stats.getSize() // total cells, including blanks
502
+ stats.getCount() // non-empty cells
503
+
504
+ // Type breakdown — keys are ScalarType values:
505
+ // 'number' | 'string' | 'boolean' | 'error' | 'richData' | 'null'
506
+ const counts = stats.getTypedCounts();
507
+ // counts.number ?? 0 → numeric cells; counts.error → error cells;
508
+ // counts.null → blanks
509
+
510
+ // Numeric aggregates (null when no numbers)
511
+ const agg = stats.getAggregates();
512
+ // agg.sum, agg.min, agg.max, agg.average, agg.stdDev — and more in the types
513
+
514
+ // Order statistics (LARGE, SMALL, PERCENTILE, RANK, MEDIAN)
515
+ const sorted = stats.getSortedNumbers();
516
+ sorted.getLarge(1); // maximum
517
+ sorted.getSmall(1); // minimum
518
+ sorted.getPercentile(0.5); // median
519
+ sorted.getRankOf(value); // 1-based rank
520
+ ```
521
+
522
+ **Distinct values are also available directly off `getStats()`.**
523
+ `getFrequencies()` gives `getUniqueCount()` and `getValueCounts()` (top-N,
524
+ sorted by frequency or value) over the whole population — the contentful
525
+ profile's `3 unique (EU 3 · NA 3 · APAC 2)` and `8 distinct, no repeats` lines
526
+ are exactly this, already computed for you. Reach for `getFrequencies()`
527
+ directly when you want the full breakdown rather than the profile's capped
528
+ top-N, or need it restricted to one kind (`{ filterFn }`). `getRanked()`
529
+ answers top/bottom-N (LARGE/SMALL) without a full sort.
530
+
531
+ ## Reading values — the contract
532
+
533
+ **A range is a reference, not its contents** — `getRange('B2:D10')` names a section
534
+ of a sheet and holds no values, which is why naming one is free at any size.
535
+
536
+ **Its report is another matter: returning the range prints the values.** That is
537
+ the read, and it is the better one — an A1-labelled table where `getValues()` is a
538
+ bare nested array you have to count rows against by eye. Reach past it only when
539
+ the values must *leave*, or when you are computing over them; *how* you ask decides
540
+ whether the work happens inside the engine or inside your loop.
541
+
542
+ ```text
543
+ # Cell Range — 'Cover Page'!C12:C18, 7×1
544
+
545
+ ## Kind (3 cells · 1 kind)
546
+ text 3
547
+
548
+ ## Profile
549
+ 3 text 3 distinct, no repeats · 4 blank
550
+
551
+ ## Values (C12:C15, 4×1 · 3 cells)
552
+ C
553
+ 12 'Profit and Loss Statement
554
+ 14 'Table of Contents
555
+ 15 'Profit and Loss (Monthly)
556
+ ```
557
+
558
+ The table is capped (1000 cells) and elides rows and columns that came back
559
+ empty, which is why its labels are real A1 labels rather than `1..n` — with row
560
+ `13` gone, an index would assert an adjacency that is not there. The heading
561
+ states the shrunk bounds when they differ from what you asked for. Past the cap
562
+ the answer is a narrower address or `getStats()`, not a bigger table.
563
+
564
+ Below the values, the same report carries the formula blocks (one row per
565
+ authored formula, addressed as a range — not one row per cell), any spills, the
566
+ tables and names that intersect, and the precedents and dependents trees.
567
+
568
+ ### `IRange` — the vector surface
569
+
570
+ `getValuesRange()` bridges a cell range into **`IRange`**: an immutable,
571
+ two-dimensional, mixed-type sparse array with functional vector semantics, shaped
572
+ for NumPy/JAX familiarity. Transforms are zero-copy and reads are SIMD-optimized;
573
+ computation happens inside the engine rather than in your runtime.
574
+
575
+ **The operations are in [vector](vector.md)**, along with `setComputedValues`, the
576
+ write half. Load it whenever you are about to transform, filter, sort or broadcast
577
+ over more than a couple of cells. The rule for choosing: `getStats()` when you are
578
+ **reducing** to an answer, `IRange` when you are **producing** new values,
579
+ `getValues()` only when the grid is leaving.
580
+
581
+ ## The dependency graph — the tree and the flat list
582
+
583
+ The calculation graph renders in two shapes, and they answer different questions.
584
+
585
+ **The tree** is a section of the cell, range and name reports — `## Precedents`
586
+ and `## Dependents` — walked one hop at a time from the subject, so the *shape*
587
+ of the chain survives: the top level is one hop, anything nested is where the
588
+ influence keeps travelling.
589
+
590
+ ```text
591
+ ## Dependents
592
+
593
+ D2:D4 3×1 =B2*C2
594
+ D6 6308.8 =SUM(D2:D4)
595
+ B6 400 =SUM(B2:B4)
596
+ D6 ↑ shown above
597
+ ```
598
+
599
+ - **Each node carries its payload at the right altitude** — a single cell shows
600
+ its value and formula, a multi-cell range its dimensions and the formula
601
+ shared across it. A range node is never expanded into its cells, and addresses
602
+ qualify with their sheet only when the tree spans sheets.
603
+ - **A defined name appears as a labeled node** — `EffectiveTax name`, or
604
+ `Revenue name → Sheet1!$B$2:$B$13` when it designates a range — and the tree
605
+ continues through it to whatever reads or feeds it. `=SUM(Revenue)` therefore
606
+ shows BOTH the `Revenue` node (the symbol that breaks if the name is deleted)
607
+ and the resolved cells (the data the value came from); they are different
608
+ facts, not a duplicate.
609
+ - **Two revisit marks, and they are opposite findings.** `↑ shown above` is
610
+ re-convergence — a node reached by more than one path, ordinary in any model:
611
+ a total fed both directly and through an intermediate. `↺ circular` is a
612
+ genuine cycle — deliberate in an iterative calculation, a defect otherwise.
613
+ - **Bounded three ways, each stated rather than silent** — depth (3 hops by
614
+ default), node count, and revisits. A cut at nodes means the graph is *wide*,
615
+ and the answer is to stand on one node and walk from there; a cut at depth is
616
+ what the flat list answers outright.
617
+
618
+ **The flat list** is what the graph calls themselves render. `getPrecedents()` /
619
+ `getDependents()` resolve to the whole transitive reach as ranges (an `ICellRanges`,
620
+ whose `getCount()` is the number of areas — cells are `getCounts()`), and
621
+ `getDirectPrecedents()` / `getDirectDependents()` one hop — on `ICell`,
622
+ `ICellRange` and defined names alike. All four are promises - the engine answers
623
+ them - so a script awaits one before reading it (`(await r.getPrecedents())?.getCount()`);
624
+ a snippet awaits its final value for you. Returning one prints a `# Ranges` listing
625
+ with the same per-row payloads as the tree and no hop structure, which is the
626
+ point: it is the countable, diffable form, and the answer to a tree branch cut
627
+ at the depth bound. It qualifies the way the tree does — a set that stays on one
628
+ sheet names it once in the heading and leaves its rows bare, one that crosses
629
+ qualifies every row instead. The same graph the tree above walked, flat:
630
+
631
+ ```text
632
+ # Ranges — Sales (3)
633
+ D2:D4 3×1 =B2*C2
634
+ B6 400 =SUM(B2:B4)
635
+ D6 6308.8 =SUM(D2:D4)
636
+ ```
637
+
638
+ The graph is indexed by range, so either shape reduces a column of four hundred
639
+ dependent cells to one entry. What a defect *feeds* and what a fix *moves* is
640
+ `analysis.md` §"Before you edit — the blast radius"; this section is only how
641
+ the answer prints.
642
+
643
+ ### `getValues()` materializes — use it deliberately
644
+
645
+ `getValues()` copies the range into JavaScript. It is for values you are going to
646
+ *compute with* in your runtime — hand to another tool, write to a file — not
647
+ values you want to look at. **A loop over `getValues()` is the slow path twice
648
+ over**: it copies, and it moves the work out of the engine and into your code.
649
+
650
+ ```typescript
651
+ range.getValues() // Scalar[][] — a real array in your runtime, maxSize-capped
652
+ range.getValue() // one Scalar — the top-left cell
653
+ range.getCell() // ICell — per-cell detail, top-left by default
654
+ ```
655
+
656
+ Display text is a **cell** lens, not a range one: `getCell().getText()` for the
657
+ one cell you are diagnosing — there is no `getText()` on a range. Reaching for it
658
+ in a loop is the tell that the range report was the call.
659
+
660
+ One boundary to keep straight. `getValues()` hands back **typed** scalars, where
661
+ the JavaScript type carries the type: `"123"` is a string, `45292` a date serial.
662
+ The `'` prefix belongs to the *text* encoding — reports, grep, anything crossing a
663
+ text boundary — where type would otherwise be lost, and it is what makes
664
+ `'10/23/95` (text) distinguishable from `10/23/95` (a formatted number). The rule
665
+ and both directions are the **Value encoding** section of the root `SKILL.md`;
666
+ per-cell writing is `writing.md`.
667
+
668
+ ## Common patterns
669
+
670
+ ### Orient to an unfamiliar sheet
671
+
672
+ ```typescript
673
+ wb.getSelectedWorksheet() // kind census, every feature partition, and the data blocks classified
674
+ ```
675
+
676
+ One call. Reach for `getRegions()` on its own when you want a *single* partition
677
+ without the rest of the report around it, or the column profiles of its blocks.
678
+
679
+ When the profile is not the question you were sent with, the loop belongs in the
680
+ run:
681
+
682
+ ```typescript
683
+ const report = [];
684
+ for (const region of wb.getWorksheet().getRegions()) {
685
+ const stats = region.getRange().getStats(); // getRange() = "now I want to read"
686
+ report.push(`${region.getAddress()}: ${stats.getCount()} values`);
687
+ }
688
+ report.join('\n')
689
+ ```
690
+
691
+ ### Profile a column for data quality
692
+
693
+ ```typescript
694
+ const counts = wb.getWorksheet().getRange('B2:B100').getStats().getTypedCounts();
695
+ // (counts.null ?? 0) > 0 → blanks present
696
+ // (counts.error ?? 0) > 0 → errors present
697
+ // (counts.string ?? 0) > 0 in a numeric column → suspect cells
698
+ ```
699
+
700
+ Bound the range. `A:A` is a million cells, and its `null` count is the million
701
+ empty ones — a true answer to a question nobody asked.
702
+
703
+ ### Check a range is purely numeric
704
+
705
+ ```typescript
706
+ const counts = wb.getWorksheet().getRange('B2:B100').getStats().getTypedCounts();
707
+ !(counts.string || counts.boolean || counts.error)
708
+ ```