rsc-universal 0.1.1

package/skills/spreadsheet-ops/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: spreadsheet-ops
+description: "Use when you must work a spreadsheet programmatically: write or repair a formula, generate an .xlsx file with Python (charts, conditional formats, append a sheet), drive Google Sheets from a script, build a read→transform→write-to-sheet pipeline, or write an in-sheet macro/trigger. Symptoms: a formula returns #VALUE!/#REF!/#SPILL!, a nightly job hits 429 quota on the Sheets API, or openpyxl 'wrote' a formula but the cell reads back blank. Triggers: 'export this DataFrame to Excel with a chart', 'my SUMIFS returns #VALUE!', 'append rows to a Google Sheet every night', 'openpyxl formula shows blank until I open in Excel', 'service account can't see my sheet / PermissionError', 'build an XLOOKUP across sheets', 'automatitza un full de càlcul', 'haz una macro de Google Sheets que coloree filas'. NOT pure dedupe/normalize with no sheet output (that is data-cleaning), NOT scraping a web table into rows (that is data-scraper), NOT multi-app event wiring (that is automation-flows)."
+tags: [spreadsheet, excel, google-sheets, openpyxl, gspread, apps-script, formulas, automation]
+recommends: [data-cleaning, data-scraper, automation-flows, google-workspace, reporting, duckdb, document-processing]
+origin: risco
+---
+
+# spreadsheet-ops — the spreadsheet as a programmable surface
+
+A spreadsheet is a runtime, not a document. Your job is to emit a **checkable artifact** — a `.xlsx`
+file that opens, a script that compiles, a cell range you can re-read — never a hand-waved formula in
+prose. Pick the tool that matches the runtime (local file vs cloud sheet, one-shot vs event-driven),
+write the formula with comma arguments, and verify before you claim it works.
+
+The trap that bites everyone first: **openpyxl writes formulas but does not compute them.** The string
+is stored; Excel evaluates it on open. If you read the cell back with Python it is `None` until a real
+Excel/LibreOffice session has saved it. Internalize that before you touch a workbook.
+
+## Pick the tool first (this branches, so decide before coding)
+
+| Your situation | Reach for | Why |
+| --- | --- | --- |
+| Read **and** modify an existing local `.xlsx` | **openpyxl** | Only mainstream lib that round-trips an existing file. |
+| Write a new `.xlsx` rich with charts/conditional formats, possibly large | **xlsxwriter** (via pandas `ExcelWriter`) | Write-only but the richest formatting + low-memory `constant_memory` mode. |
+| Dump a DataFrame to a sheet, minimal fuss | **pandas** `df.to_excel(...)` | Wraps an engine; pass `engine=` explicitly so the result does not depend on what is installed. |
+| Read/write a cloud Google Sheet from a script | **gspread** (+ `gspread-formatting` for colors/rules) | Friendly wrapper over the Sheets API for CRUD. |
+| High-volume cloud writes, must beat quotas | **Sheets API v4** `batchUpdate` | One batched call counts as one request — survives the per-minute limit. |
+| In-sheet menus, time-driven triggers, custom functions | **Apps Script (V8)** | Runs inside the sheet; the only place for `onEdit`/menus. |
+
+Two you will confuse: **xlsxwriter cannot open an existing file** — if you need to edit one in place,
+that is openpyxl. And gspread vs the raw Sheets API is convenience vs throughput: reach for raw
+`batchUpdate` only when gspread's per-call writes would blow the quota.
+
+Versions seen on PyPI when this was written (2026-06-02): openpyxl **3.1.5**, gspread **6.2.1**
+(Python 3.8+), gspread-formatting **1.2.1**, pandas on the **3.x** line, Sheets API **v4**, Apps
+Script on the **V8** runtime. Treat these as a floor, re-check PyPI before pinning, and pin whatever
+you actually resolve — do not copy a point release from a doc as gospel.
+
+## Formula rules (each rule, one reason)
+
+1. **Arguments are comma-separated, always — never semicolons.** openpyxl and the file format use
+   commas regardless of your machine's locale; a semicolon is the single most common "my written
+   formula is broken" cause. Bad: `=SUM(A1;A2)` → Good: `=SUM(A1,A2)`.
+2. **A formula string must start with `=`.** `ws["A1"] = "SUM(1,1)"` stores literal text; `ws["A1"] =
+   "=SUM(1,1)"` stores a formula. No leading `=` means no calculation, ever.
+3. **Anchor references you intend to fill.** A lookup table dragged down breaks unless absolute: Bad:
+   `=VLOOKUP(A2,Sheet2!A:B,2,0)` → Good: `=XLOOKUP(A2,Sheet2!$A:$A,Sheet2!$B:$B)`.
+4. **Prefer XLOOKUP over VLOOKUP** — exact match by default, no magic column index to miscount, works
+   leftward. VLOOKUP's 4th arg silently defaulting to approximate match is a classic wrong-result bug.
+5. **Prefer dynamic arrays over Ctrl+Shift+Enter array formulas** — `=FILTER(...)`, `=SORT(...)`,
+   `=UNIQUE(...)` spill automatically and are readable. A spill blocked by data below it raises
+   `#SPILL!`; clear the range, do not array-enter.
+6. **Never deep-nest IFs.** Past two levels use `LET` (name sub-expressions once) or a helper column.
+   Bad: `=IF(A1>90,"A",IF(A1>80,"B",IF(A1>70,"C","D")))` → Good: a lookup table + `XLOOKUP`, or
+   `=LET(g,A1, IF(g>90,"A", IF(g>80,"B","C")))` kept shallow.
+
+When generating cross-sheet formulas, `SHEET()` returns a sheet's index and `SHEETS()` returns the
+sheet count — both have shipped in Excel for years (SHEET/SHEETS since Excel 2013) and exist in Google
+Sheets, so they are safe to emit. Full XLOOKUP/SUMIFS/LET patterns and the `#VALUE!/#REF!/#N/A/#NAME?`
+error decoder live in [`references/formula-cookbook.md`](references/formula-cookbook.md).
+
+## Python → Excel
+
+The no-compute trap, stated as code:
+
+```python
+from openpyxl import load_workbook
+wb = load_workbook("report.xlsx")
+ws = wb.active
+ws["C2"] = "=A2*B2"          # stores the FORMULA string, not a number
+wb.save("report.xlsx")
+# Re-reading C2 now returns "=A2*B2" (the formula), or with data_only=True
+# returns None — because no Excel has opened+saved the file to cache a value.
+back = load_workbook("report.xlsx", data_only=True)
+assert back.active["C2"].value is None   # last cached value: none yet
+```
+
+So: if a downstream step needs the computed number, either compute it in Python and write the value, or
+open the file once in Excel/LibreOffice headless to populate the cache. Do not assume openpyxl evaluated it.
+
+Append a sheet to an existing file (the only mode that does not silently truncate):
+
+```python
+import pandas as pd
+with pd.ExcelWriter("report.xlsx", engine="openpyxl", mode="a",
+                    if_sheet_exists="replace") as xl:
+    df.to_excel(xl, sheet_name="2026-Q2", index=False)
+```
+
+Charts and conditional formatting on a new file go through **xlsxwriter** (richer) — it is write-only,
+so never point it at a file you need to keep. Recipes (chart, conditional format, `write_only`/
+`constant_memory` for big files) are in [`references/python-excel.md`](references/python-excel.md).
+
+## Google Sheets from a script
+
+```python
+import gspread
+gc = gspread.service_account(filename="bot-key.json")  # service account
+sh = gc.open_by_key("SPREADSHEET_ID")
+ws = sh.worksheet("Orders")
+ws.append_rows([["2026-06-02", "INV-1001", 240.00]],
+               value_input_option="USER_ENTERED")      # parses formulas/dates
+```
+
+The failure that wastes the most time: **a service account has zero access until the sheet is shared
+with its email.** Open the key JSON, copy `client_email`, and share the sheet with it (Editor) — a
+`PermissionError`/`SpreadsheetNotFound` here is almost always an unshared sheet, not bad code.
+
+Quotas (as published 2026-06-02 — re-check Google's "Usage limits" page, these shift): **300 read
+req/min/project, 60 read req/min/user** (writes mirror this), refilled each minute, no daily cap under
+the per-minute ceiling. A `batchUpdate` — with all its sub-requests inside — counts as **one** request.
+So batch: build one `batchUpdate` body instead of N `update` calls, and wrap calls in exponential
+backoff on HTTP 429. Batching is the difference between a nightly job that survives and one that 429s.
+
+Creating the OAuth client or service account itself is [`google-workspace`](../google-workspace/SKILL.md)'s
+job; this skill assumes the credential exists and owns the Sheets surface. `batchUpdate` request shapes
+and backoff code are in [`references/sheets-api-appsscript.md`](references/sheets-api-appsscript.md).
+
+## In-sheet automation (Apps Script V8)
+
+Write for **V8** — Google deprecated the legacy Rhino runtime (Feb 2025) and set its retirement for on
+or after 2026-01-31, so new code should never target it. V8 has **no `fetch`, no timers, no streams**
+— use `UrlFetchApp.fetch()` (or `fetchAll()` for parallel) for HTTP. No ES6 `import/export`, no private
+`#fields`.
+
+Read and write the sheet in **one** range operation, never a per-cell loop — `getValue()`/`setValue()`
+inside a loop makes one API round-trip per cell and times out on real data:
+
+```javascript
+function colorOverdue() {
+  const sh = SpreadsheetApp.getActiveSheet();
+  const data = sh.getDataRange().getValues();   // ONE read, all rows
+  const out = data.map(r => r[3] === "OVERDUE" ? ["#fde0e0"] : ["#ffffff"]);
+  sh.getRange(1, 1, out.length, 1).setBackgrounds(out.map(c => c)); // ONE write
+}
+```
+
+Time-driven triggers (run nightly), `onEdit` simple triggers, and custom menus are covered in
+[`references/sheets-api-appsscript.md`](references/sheets-api-appsscript.md).
+
+## Pipeline pattern: read → transform → write
+
+A pipeline that reruns must not duplicate rows. Decide the write mode first:
+
+1. **Define a header contract** — the exact columns and order. Assert the live header matches before
+   writing; a shifted column silently corrupts everything downstream.
+2. **Choose the write mode:**
+   - *Full overwrite* — clear the data range, write all rows. Simple, safe when the sheet is yours alone.
+   - *Keyed upsert* — read existing keys (e.g. `order_id`) into a map, update matched rows, append the
+     rest. Idempotent: rerunning yields the same sheet, no duplicates.
+3. **Dry-run first.** Compute the diff (rows to add/update) and log it; only write when a `--apply` flag
+   is set. This catches a wrong key or a header drift before it touches the live sheet.
+4. **Batch the write** (`batchUpdate` / `setValues`) and back off on 429.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Semicolon arguments `=SUM(A1;A2)` | File format is comma-only; locale display fools you | Always commas `=SUM(A1,A2)` |
+| Formula string without leading `=` | Stored as literal text, never calculates | Start the string with `=` |
+| Assuming openpyxl computed the result | It only stores the formula; value is `None` until Excel opens it | Write the value, or open once to cache |
+| Per-cell `getValue()`/`setValue()` loop (Apps Script) | One round-trip per cell → timeout | `getValues()`/`setValues()` once per range |
+| N single `update` calls to the Sheets API | Blows 60/user-min, 300/project-min quota | One `batchUpdate`; backoff on 429 |
+| Service account not shared with the sheet | `PermissionError`, looks like a code bug | Share the sheet with `client_email` from the key |
+| Deep-nested `IF` chains | Unreadable, miscounted parens, hard to repair | `LET`, a lookup table, or a helper column |
+| xlsxwriter to modify an existing file | It is write-only; you lose the original | openpyxl for read+modify |
+| `df.to_excel("f.xlsx")` over an existing file | Default mode truncates the whole workbook | `ExcelWriter(..., mode="a")` to append |
+| VLOOKUP with a hardcoded column index | Index miscounts when columns move; approximate-match default | `XLOOKUP` with explicit ranges |
+
+## Verify
+
+Run `scripts/verify.sh` (read-only by default; pass a path to a generated `.py`/`.xlsx`). It
+`py_compile`s generated scripts, opens produced workbooks with openpyxl to confirm a sheet + header row,
+and lints formula strings for the semicolon-argument bug. Cloud paths are validated by structure, not
+live Google calls — no network or credentials required. On an empty/clean target it exits 0.
+
+References: [`python-excel.md`](references/python-excel.md) ·
+[`sheets-api-appsscript.md`](references/sheets-api-appsscript.md) ·
+[`formula-cookbook.md`](references/formula-cookbook.md).

package/skills/spreadsheet-ops/evals/README.md

@@ -0,0 +1,33 @@
+# Eval harness — `spreadsheet-ops`
+
+Two things are graded: **triggering** (does the skill fire on real spreadsheet work and stay quiet on
+near-misses that belong to a sibling?) and **capability** (does loading the skill make the produced
+script measurably better?). Cases are in `cases.yaml`. They are graded by a human or a driver agent
+feeding prompts to a fresh session — not an automated runner. The executable check is
+`scripts/verify.sh`, which smoke-tests that generated artifacts actually compile/open and that formulas
+use comma arguments; the eval cases here grade judgment, not code.
+
+## Triggering
+
+For each prompt, start a fresh agent with only `spreadsheet-ops` discoverable, paste the prompt
+verbatim, and observe whether the agent reaches for this skill. Run 3–5 trials (the decision is
+stochastic). `should_trigger` passes if the skill fires in the majority of trials. `should_not_trigger`
+passes if it does **not** fire; each names a `route_to` sibling (`data-cleaning`, `data-scraper`,
+`automation-flows`, `google-workspace`, `reporting`) — sanity-check the agent would plausibly route
+there, though any not-this-skill route still passes the gate. Some routed siblings may not be built in
+this collection yet; the routing intent is what's graded. Pass bar: ≥ 90% trigger accuracy across cases.
+
+## Capability
+
+Run the scenario twice — WITHOUT the skill (clean agent) and WITH it — and grade each transcript against
+the `must_include` checklist, one point per bullet that is specifically and correctly covered (not just
+name-dropped). WITH the skill should cover ≥ 80% of bullets and clearly beat WITHOUT (target ≥ +30
+points or crossing fail→pass). If the script the WITH-skill agent emits is real, run it through
+`scripts/verify.sh` to confirm the comma-args and compile bullets objectively.
+
+## Notes
+
+Prompts are deliberately varied: several never say "spreadsheet" (the #VALUE! SUMIFS repair, the blank
+openpyxl cell, the service-account PermissionError), and one is in Spanish — these test intent over
+keywords. Record trial counts and per-bullet verdicts so a reviewer can audit; don't report a bare
+pass/fail.

package/skills/spreadsheet-ops/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: spreadsheet-ops
+
+should_trigger:
+  - prompt: "Write a Python script that exports this DataFrame to an .xlsx with a column chart and conditional formatting on overdue rows."
+    why: "Core Python→Excel artifact generation with charts + conditional formats — the xlsxwriter/pandas path."
+  - prompt: "My SUMIFS keeps returning #VALUE! and I can't see why. Here's the formula."
+    why: "Symptom-led formula repair; the user names the error, not the skill. Mismatched range shapes is the classic cause."
+  - prompt: "Every night my job needs to append a few rows to a Google Sheet. What's the right way to do it from Python?"
+    why: "Cloud read→write pipeline via gspread/Sheets API, including append + quota awareness."
+  - prompt: "I set a formula with openpyxl and saved, but when I read the cell back it's blank. What's wrong?"
+    why: "Non-obvious no-compute trap: openpyxl stores the formula; data_only returns None until Excel opens the file."
+  - prompt: "Haz una macro de Google Sheets que coloree las filas según el estado de cada pedido."
+    why: "Spanish + in-sheet automation → Apps Script V8, batched setBackgrounds. Tests language + intent."
+  - prompt: "My service account gets PermissionError / SpreadsheetNotFound when it tries to open the sheet, but the key is valid."
+    why: "Non-obvious share trap — a service account has no access until the sheet is shared with its client_email."
+
+should_not_trigger:
+  - prompt: "These columns have mixed date formats and duplicate rows — clean and normalize them, no spreadsheet output needed."
+    route_to: data-cleaning
+    why: "Pure data hygiene with no spreadsheet artifact is data-cleaning's job."
+  - prompt: "Scrape this HTML pricing table from a webpage into structured rows."
+    route_to: data-scraper
+    why: "Extracting structured data from a web table is data-scraper, not spreadsheet authoring."
+  - prompt: "When a Typeform is submitted, post to Slack and add a row to a Sheet — wire the whole flow."
+    route_to: automation-flows
+    why: "Multi-app event chaining (Zapier/Make/n8n style) is automation-flows; spreadsheet-ops only owns the sheet step."
+  - prompt: "Set up OAuth and Drive access for my Google account so my app can authenticate."
+    route_to: google-workspace
+    why: "Credential/OAuth/Drive setup is google-workspace; this skill consumes the credential, it doesn't create it."
+  - prompt: "Build the recurring weekly stakeholder report deliverable for the leadership team."
+    route_to: reporting
+    why: "A finished recurring report deliverable is reporting; spreadsheet-ops stops at the programmable sheet."
+
+capability:
+  - scenario: "Given a CSV of orders (order_id, customer, amount, status, due_date), produce a runnable Python script that writes an orders.xlsx with a header row, a SUMIFS total of amounts where status is OPEN, conditional formatting highlighting OVERDUE rows, and an idempotent keyed upsert by order_id so rerunning does not duplicate rows."
+    must_include:
+      - "Formula arguments are comma-separated, never semicolons (=SUMIFS(...,...,...) with commas)"
+      - "Any formula string written into a cell starts with a leading '=' "
+      - "States/handles that openpyxl stores the formula and does NOT compute it (value None / data_only caveat), or writes computed values"
+      - "Chart and/or conditional formatting via the correct engine (xlsxwriter for a new rich file, or openpyxl rules), not hand-waved"
+      - "Idempotent upsert keyed by order_id — reads existing keys, updates matches, appends the rest; no duplicate rows on rerun"
+      - "Script is runnable: passes python -m py_compile (valid syntax, real imports)"

package/skills/spreadsheet-ops/references/formula-cookbook.md

@@ -0,0 +1,70 @@
+# Formula cookbook
+
+Rule one, repeated because it causes the most broken formulas: **arguments are comma-separated, never
+semicolons** — the file format is comma-only regardless of your locale's display separator.
+
+## Lookups
+
+```text
+# Exact match, no column-index counting, works leftward:
+=XLOOKUP(A2, Sheet2!$A:$A, Sheet2!$B:$B, "not found")
+
+# Multi-criteria with FILTER (dynamic array):
+=FILTER(Orders!B:B, (Orders!A:A=A2)*(Orders!C:C="PAID"))
+
+# Avoid: VLOOKUP with a hardcoded index and approximate-match default
+# Bad:  =VLOOKUP(A2, Sheet2!A:B, 2)        ' 4th arg defaults to TRUE → wrong row
+# Good: =VLOOKUP(A2, Sheet2!$A:$B, 2, FALSE)  ' or just use XLOOKUP
+```
+
+## Conditional sums
+
+```text
+# Sum amount where region=EU AND status=OPEN:
+=SUMIFS(amount, region, "EU", status, "OPEN")
+
+# Common #VALUE! cause: the sum range and a criteria range are different sizes.
+# Bad:  =SUMIFS(B2:B100, C2:C50, "EU")     ' mismatched lengths → #VALUE!
+# Good: =SUMIFS(B2:B100, C2:C100, "EU")    ' all ranges identical shape
+```
+
+## Readability: LET and helper columns
+
+```text
+# Name a sub-expression once instead of recomputing it:
+=LET(rate, VLOOKUP(A2, Rates!$A:$B, 2, FALSE),
+     net,  B2 * (1 - rate),
+     ROUND(net, 2))
+
+# Replace a deep IF chain (Bad) with a lookup table + XLOOKUP (Good):
+# Bad:  =IF(A1>90,"A",IF(A1>80,"B",IF(A1>70,"C","D")))
+# Good: =XLOOKUP(A1, Bands!$A:$A, Bands!$B:$B, "F", -1)  ' -1 = exact-or-next-smaller
+```
+
+## Dynamic arrays
+
+```text
+=SORT(UNIQUE(FILTER(A2:A100, B2:B100<>"")))   ' spills automatically
+```
+A spill blocked by data in its target range raises `#SPILL!` — clear the cells below; do not
+Ctrl+Shift+Enter.
+
+## Error decoder
+
+| Error | Means | Usual fix |
+| --- | --- | --- |
+| `#VALUE!` | A wrong argument type, or mismatched range sizes in SUMIFS/array math | Make all ranges the same shape; coerce text-numbers with `VALUE()` |
+| `#REF!` | A reference no longer exists (deleted row/column/sheet) | Repoint the reference; check after structural edits |
+| `#N/A` | Lookup found nothing | Add the 4th arg / `if_not_found`: `XLOOKUP(...,"")` |
+| `#SPILL!` | A dynamic array cannot spill — something blocks the range | Clear the blocking cells below/right |
+| `#NAME?` | Unknown function or name — often a typo or a locale/semicolon artifact | Fix the name; switch semicolons to commas |
+| `#DIV/0!` | Division by zero/empty | Guard: `=IFERROR(a/b, 0)` or `=IF(b=0,0,a/b)` |
+| `#NUM!` | Invalid numeric argument (e.g. negative sqrt) | Validate the input range |
+
+## Cross-sheet helpers (long-standing — Excel since 2013, also in Google Sheets)
+
+```text
+=SHEET()          ' index of the current sheet
+=SHEET("Q2")      ' index of a named sheet
+=SHEETS()         ' count of sheets in the workbook
+```

package/skills/spreadsheet-ops/references/python-excel.md

@@ -0,0 +1,87 @@
+# Python → Excel: openpyxl vs xlsxwriter vs pandas
+
+Versions seen on PyPI 2026-06-02: openpyxl 3.1.5, pandas on the 3.x line, plus xlsxwriter (a separate
+install — pandas does not bundle it). Re-check PyPI before pinning.
+
+## Choosing the engine
+
+| Need | Library | Notes |
+| --- | --- | --- |
+| Open + modify an existing `.xlsx` | openpyxl | Only one that round-trips an existing file. |
+| New file, charts + conditional formats | xlsxwriter | Write-only. Richest formatting. |
+| New file, very large, low memory | xlsxwriter `constant_memory` or openpyxl `write_only` | Stream row-by-row; cannot revisit written cells. |
+| Quick DataFrame dump | pandas `to_excel` | Wraps an engine — pass `engine=` explicitly (see below). |
+| Append a sheet to an existing file | pandas `ExcelWriter(engine="openpyxl", mode="a")` | xlsxwriter cannot append — it is write-only. |
+
+For `.xlsx`, pandas `ExcelWriter`/`to_excel` resolves its engine from the `io.excel.xlsx.writer`
+option: **xlsxwriter when it is installed, otherwise openpyxl**. That makes the effective default
+environment-dependent — the same script writes through different engines on two machines, and append
+mode silently needs openpyxl regardless. Do not rely on the implicit pick: always pass `engine=`
+(`"xlsxwriter"` for a new formatted file, `"openpyxl"` for read/modify/append). Being explicit is the
+whole fix for the long-standing default-engine confusion.
+
+## The no-compute trap (full)
+
+openpyxl stores the formula string; it never evaluates it. Excel/LibreOffice computes on open and
+caches the result.
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook("book.xlsx")
+ws = wb.active
+ws["C2"] = "=A2*B2"
+wb.save("book.xlsx")
+
+# default load: cell holds the formula text
+print(load_workbook("book.xlsx").active["C2"].value)            # "=A2*B2"
+# data_only: cell holds the LAST CACHED value — None if never opened in Excel
+print(load_workbook("book.xlsx", data_only=True).active["C2"].value)  # None
+```
+
+If a downstream consumer needs the number, either compute it in Python and write the literal value, or
+open the file once headless (e.g. `libreoffice --headless --convert-to xlsx`) so the cache is populated.
+
+Array and data-table formulae are preserved on read/write but, likewise, not evaluated.
+
+## Chart + conditional format (xlsxwriter, new file)
+
+```python
+import pandas as pd
+
+df = pd.DataFrame({"month": ["Jan", "Feb", "Mar"], "revenue": [100, 140, 90]})
+with pd.ExcelWriter("report.xlsx", engine="xlsxwriter") as xl:
+    df.to_excel(xl, sheet_name="data", index=False)
+    wb, ws = xl.book, xl.sheets["data"]
+
+    # conditional format: highlight revenue < 100
+    ws.conditional_format("B2:B4", {
+        "type": "cell", "criteria": "<", "value": 100,
+        "format": wb.add_format({"bg_color": "#fde0e0"}),
+    })
+
+    # column chart bound to the data range
+    chart = wb.add_chart({"type": "column"})
+    chart.add_series({
+        "categories": "=data!$A$2:$A$4",
+        "values":     "=data!$B$2:$B$4",
+        "name":       "Revenue",
+    })
+    ws.insert_chart("D2", chart)
+```
+
+Conditional formats on an **existing** file go through openpyxl's `openpyxl.formatting.rule` instead
+(xlsxwriter cannot reopen the file).
+
+## Large files
+
+- xlsxwriter: `Workbook(path, {"constant_memory": True})` — flushes each row, near-flat memory; you
+  cannot go back and rewrite an already-written cell.
+- openpyxl: `Workbook(write_only=True)` then `ws.append([...])` per row. Same constraint.
+
+## Append-mode gotchas
+
+- `df.to_excel("f.xlsx")` with the default mode **truncates** the whole workbook. To keep existing
+  sheets use `ExcelWriter(..., engine="openpyxl", mode="a")`.
+- `if_sheet_exists` must be set in append mode: `"error"` (default), `"replace"`, `"overlay"`, `"new"`.
+- xlsxwriter ignores `mode="a"` — it has no read path. Use openpyxl to append.

package/skills/spreadsheet-ops/references/sheets-api-appsscript.md

@@ -0,0 +1,118 @@
+# Google Sheets API v4 + Apps Script V8
+
+Versions seen on PyPI 2026-06-02: gspread 6.2.1, gspread-formatting 1.2.1; Sheets API v4; Apps Script
+on the V8 runtime. Re-check before pinning.
+
+## Credentials (handoff)
+
+Creating the OAuth client / service account is `../google-workspace/SKILL.md`. This skill assumes a
+credential exists. gspread auth modes:
+
+| Mode | Call | Use for |
+| --- | --- | --- |
+| Service account | `gspread.service_account(filename="key.json")` | Bots, cron, servers |
+| End-user OAuth | `gspread.oauth()` | Acting as a human |
+| Public read | `gspread.api_key("API_KEY")` | Read-only public sheets |
+
+**Service account access requirement:** a service account sees nothing until the sheet is shared with
+its `client_email` (read it from the key JSON). A `PermissionError`/`SpreadsheetNotFound` is almost
+always an unshared sheet. Share with Editor for writes.
+
+## Quota math
+
+- 300 read req/min/project, 60 read req/min/user (writes mirror these), as published 2026-06-02.
+- Refilled each minute; no daily cap when under the per-minute ceiling.
+- A `batchUpdate` counts as **one** request no matter how many sub-requests it carries.
+- These numbers move — confirm against Google's current "Usage limits" page before sizing a job.
+
+Implication: collapse N writes into one `batchUpdate`, and back off on 429.
+
+## batchUpdate request shape
+
+```python
+service.spreadsheets().batchUpdate(
+    spreadsheetId=SID,
+    body={"requests": [
+        {"updateCells": {  # write a block of values
+            "range": {"sheetId": 0, "startRowIndex": 0, "startColumnIndex": 0},
+            "rows": [{"values": [{"userEnteredValue": {"stringValue": "order_id"}}]}],
+            "fields": "userEnteredValue",
+        }},
+        {"repeatCell": {  # conditional-style formatting on a range
+            "range": {"sheetId": 0, "startRowIndex": 1, "endRowIndex": 100},
+            "cell": {"userEnteredFormat": {"backgroundColor": {"red": 0.99, "green": 0.88, "blue": 0.88}}},
+            "fields": "userEnteredFormat.backgroundColor",
+        }},
+    ]},
+).execute()
+```
+
+## Exponential backoff on 429
+
+```python
+import time, random
+from googleapiclient.errors import HttpError
+
+def with_backoff(call, tries=5):
+    for n in range(tries):
+        try:
+            return call()
+        except HttpError as e:
+            if e.resp.status != 429 or n == tries - 1:
+                raise
+            time.sleep((2 ** n) + random.random())  # 1s, 2s, 4s... + jitter
+```
+
+A1 (`Sheet1!A1:C10`) vs R1C1 indices: gspread uses A1 strings; the raw API `GridRange` uses
+zero-based `startRowIndex`/`endRowIndex` (end-exclusive). Mixing them off-by-one is a common bug.
+
+## Apps Script V8
+
+Target **V8**: Google deprecated the legacy Rhino runtime (Feb 2025) with retirement set for on or
+after 2026-01-31, so never author new code against it. V8 has no `fetch`, no timers, no streams; no ES6
+`import/export`; no private `#fields`.
+
+HTTP — use UrlFetchApp:
+
+```javascript
+function pull() {
+  const res = UrlFetchApp.fetch("https://api.example.com/data", {
+    method: "get", muteHttpExceptions: true,
+  });
+  if (res.getResponseCode() !== 200) throw new Error(res.getContentText());
+  return JSON.parse(res.getContentText());
+}
+// Parallel requests: UrlFetchApp.fetchAll([{url: ...}, {url: ...}]);
+```
+
+Batch reads/writes — never per-cell:
+
+```javascript
+function fillTotals() {
+  const sh = SpreadsheetApp.getActiveSheet();
+  const rows = sh.getDataRange().getValues();          // ONE read
+  const totals = rows.slice(1).map(r => [r[1] * r[2]]); // qty * price
+  sh.getRange(2, 4, totals.length, 1).setValues(totals); // ONE write
+}
+```
+
+Time-driven trigger (run nightly at 02:00):
+
+```javascript
+function install() {
+  ScriptApp.newTrigger("fillTotals").timeBased().everyDays(1).atHour(2).create();
+}
+```
+
+Custom menu (`onOpen` simple trigger):
+
+```javascript
+function onOpen() {
+  SpreadsheetApp.getUi().createMenu("Ops")
+    .addItem("Fill totals", "fillTotals").addToUi();
+}
+```
+
+For cross-sheet formulas, `SHEET()` (sheet index) and `SHEETS()` (sheet count) have shipped for years
+(Excel since 2013; present in Google Sheets) — safe to emit. For richer integrations, check Apps
+Script's current advanced-services list rather than assuming a given service exists.