rsc-universal 0.1.1

package/skills/sql/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: sql
+description: "Use when writing or reviewing advanced SQL query logic independent of any one engine — multi-table joins, window functions, CTEs (incl. recursive), GROUP BY/GROUPING SETS aggregation, or UNION/INTERSECT/EXCEPT set ops — or when a query returns too many rows, too few rows, or wrong totals. Triggers: 'top N per group', 'running total', 'period over period', 'gaps and islands', 'recursive CTE', 'why is my SUM doubled', 'NOT IN returns nothing', 'dedup keep latest', 'consulta SQL avanzada', 'función de ventana', 'per què el JOIN duplica files'. NOT engine internals/indexes/EXPLAIN (that is postgresdb), NOT MySQL config (that is mysql), NOT OLAP columnar specifics (that is duckdb)."
+tags: [sql, query, joins, window-functions, cte]
+recommends: [postgresdb, mysql, duckdb, drizzle-orm]
+origin: risco
+---
+
+# SQL — engine-agnostic query craft
+
+This skill is the portable query-writing layer that sits *above* any one database engine. It owns
+the SELECT-side craft: joins and what each does to row count and NULLs, window functions
+(`PARTITION`/`ORDER`/frame), CTEs (including recursive), aggregation (`GROUP BY`/`GROUPING SETS`/`HAVING`),
+set operations (`UNION`/`INTERSECT`/`EXCEPT`), conditional logic (`CASE`/`COALESCE`/`NULLIF`), and the
+NULL three-valued-logic traps that quietly corrupt results across *every* engine. You write queries a
+reviewer accepts on Postgres, MySQL 8, SQLite, DuckDB, SQL Server, or BigQuery with minimal change, and
+you flag exactly where a construct is non-portable and what the dialect substitute is. The target
+standard is **SQL:2023 (ISO/IEC 9075:2023)**, the ninth edition published June 2023; window functions
+have been standard since **SQL:2003**, so they are safe to assume everywhere.
+
+This is about *thinking in sets and frames*, not about one product's planner, DDL, indexing, or ops.
+
+## When to use
+
+- Writing a non-trivial read query: multi-table join, "top-N per group", running totals,
+  period-over-period deltas, dedup, pivots, cohort/funnel shaping.
+- Reaching for a window function and unsure about `PARTITION BY` vs `GROUP BY`, or `ROWS` vs `RANGE`
+  vs `GROUPS` frames.
+- Structuring a query with CTEs or recursive CTEs (hierarchies, graph walks, generated series).
+- Aggregation shaping: `GROUP BY`, `HAVING`, `GROUPING SETS`/`ROLLUP`/`CUBE`, conditional aggregates.
+- Combining result sets with `UNION`/`INTERSECT`/`EXCEPT`; deciding `ALL` vs distinct.
+- Debugging a query that returns *too many rows* (join fan-out), *too few* (NULL-eating `NOT IN`), or
+  *wrong aggregates* (counting joined duplicates).
+- Translating a procedural loop ("for each row, query again") into one set-based statement.
+- Reviewing SQL for portability and correctness regardless of the target engine.
+
+## When NOT to use
+
+| The ask | Route to |
+| --- | --- |
+| Engine-level Postgres: DDL types, indexes, EXPLAIN, VACUUM, RLS, pooling | `../postgresdb/SKILL.md` |
+| MySQL-specific behavior/config (InnoDB, buffer pool) | `../mysql/SKILL.md` |
+| DuckDB local-analytics / columnar specifics | `../duckdb/SKILL.md` |
+| ClickHouse columnar OLAP engine specifics | `../clickhouse-analytics/SKILL.md` |
+| ORM/builder API ergonomics (the API, not the emitted SQL) | `../drizzle-orm/SKILL.md`, `../prisma-orm/SKILL.md` |
+| Schema design / DDL / migrations | `../db-migrations/SKILL.md` |
+| BI dashboards, reporting layout, metric definitions | `../business-intelligence/SKILL.md` |
+| Cleaning messy data as a pipeline task | `../data-cleaning/SKILL.md` |
+
+The defining line: **`sql` = portable query-language craft; engine skills = one product's behavior,
+storage, and operations.** When the engine isn't decided, or the question is "how do I express this in
+SQL at all" rather than "how does Postgres run it" — you are in the right place.
+
+## Non-negotiables
+
+1. **Explicit `JOIN` syntax, never comma-joins.** `FROM a, b WHERE a.id = b.a_id` hides the join
+   condition in the filter — drop the `WHERE` clause by accident and you get a silent cross product.
+2. **Alias and qualify every column in a multi-table query.** `SELECT id, name` is ambiguous and breaks
+   the moment two joined tables share a column name; `SELECT o.id, c.name` survives schema changes.
+3. **`NOT EXISTS` over `NOT IN` whenever the inner side is nullable.** `NOT IN` returns *zero rows* if the
+   subquery yields a single NULL (3VL `UNKNOWN` is never `TRUE`); `NOT EXISTS` is NULL-safe. Standard, not
+   engine-specific.
+4. **Know your implicit window frame.** A window function with `ORDER BY` but no explicit frame defaults to
+   `RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`, which lumps *tied* rows together — not `ROWS`. This
+   silently wrong running total is the single most common window bug, identical across engines. Write the
+   frame explicitly.
+5. **Every non-aggregated SELECT column appears in `GROUP BY`.** Engines that let you skip it (old MySQL)
+   return an arbitrary row per group — a correctness landmine, not a convenience.
+6. **`UNION ALL` unless you genuinely need dedup.** Bare `UNION` sorts/hashes to remove duplicates — real
+   cost — and silently collapses rows you meant to keep. Add `ALL` by default; remove it deliberately.
+7. **Reason about NULL 3VL before writing any predicate.** `NULL = NULL` is `UNKNOWN`, `x <> 5` excludes
+   NULL `x`, and `COUNT(col)` skips NULLs while `COUNT(*)` does not. Decide what NULL means before the WHERE.
+8. **One set-based statement beats a procedural loop.** "For each row, run another query" is almost always a
+   join or a window function — orders of magnitude faster and atomic. Reach for sets first.
+
+## Decision tables
+
+### JOIN chooser
+
+| Want | Use | Row-count effect | NULL behavior |
+| --- | --- | --- | --- |
+| Only matching pairs | `INNER JOIN` | Can shrink **and** fan out on 1-to-many | Unmatched rows dropped |
+| All left rows + matches | `LEFT JOIN` | ≥ left row count | Right columns NULL when no match |
+| All rows from both | `FULL JOIN` | ≥ max(left, right) | NULLs on whichever side lacks a match |
+| Every combination | `CROSS JOIN` | left × right (multiplies!) | None |
+| "Left rows that have a match" | semi-join via `EXISTS` | = left, no duplication | No right columns added |
+| "Left rows with no match" | anti-join via `NOT EXISTS` | ≤ left | NULL-safe (unlike `NOT IN`) |
+
+A 1-to-many `JOIN` *fans out* the left row once per match. If you then `SUM`/`COUNT`, the aggregate is
+inflated. Use a semi-join (`EXISTS`) when you only want existence, not the joined columns.
+
+### GROUP BY vs window function
+
+| You want… | Use | Result |
+| --- | --- | --- |
+| One row per group (collapse detail) | `GROUP BY` | Fewer rows; only group keys + aggregates survive |
+| Keep every row **and** add a per-group number | `... OVER (PARTITION BY …)` | Same row count; aggregate alongside detail |
+
+Rule of thumb: if the question is "per X, the total/rank/previous," and you still want the individual
+rows, it is a window function. If you only want the rollup, it is `GROUP BY`.
+
+### Frame chooser (`ROWS` / `RANGE` / `GROUPS`)
+
+| Frame unit | Counts by | Use for | Portability |
+| --- | --- | --- | --- |
+| `ROWS` | Physical rows | Running totals, moving averages | Everywhere |
+| `RANGE` | Value range of the `ORDER BY` key | "All rows within ±N of this value/date" | Everywhere |
+| `GROUPS` | Peer groups (tied rows) | "N distinct ordering-value steps back" | **Not in MySQL 8** |
+
+`ROWS` and `RANGE` plus `EXCLUDE` and numeric `RANGE` offsets work on Postgres 11+ and SQLite 3.28+.
+**MySQL 8 supports only `ROWS` and `RANGE` — no `GROUPS`, no `EXCLUDE`.** See `references/window-functions.md`.
+
+### Subquery vs JOIN vs CTE
+
+| Need | Reach for |
+| --- | --- |
+| Existence / anti-existence test | correlated `EXISTS` / `NOT EXISTS` |
+| Combine columns from another table | `JOIN` |
+| Name an intermediate result, reuse or read it cleanly | CTE (`WITH`) |
+| Hierarchy, graph walk, generated series | recursive CTE (`WITH RECURSIVE`) |
+
+## Copy-paste patterns
+
+Every fence is `sql`. Full depth in `references/`.
+
+**Top-N per group** — never `LIMIT` inside a correlated subquery.
+
+```sql
+-- Bad: correlated subquery runs once per customer; non-portable LIMIT placement
+SELECT * FROM orders o
+WHERE o.id IN (
+  SELECT id FROM orders i WHERE i.customer_id = o.customer_id
+  ORDER BY i.amount DESC LIMIT 3
+);
+
+-- Good: one pass, ranked, then filtered
+SELECT customer_id, id, amount
+FROM (
+  SELECT customer_id, id, amount,
+         ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY amount DESC) AS rn
+  FROM orders
+) ranked
+WHERE rn <= 3;
+```
+
+**Running total** — make the frame explicit so ties don't lump.
+
+```sql
+-- Bad: no frame -> implicit RANGE, tied dates collapse into one running value
+SELECT day, SUM(amount) OVER (ORDER BY day) AS running FROM sales;
+
+-- Good: explicit ROWS frame counts physical rows
+SELECT day,
+       SUM(amount) OVER (ORDER BY day ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS running
+FROM sales;
+```
+
+**Period-over-period with `LAG`.**
+
+```sql
+-- Good: previous row's value per partition; NULL on the first row is expected
+SELECT month, revenue,
+       revenue - LAG(revenue) OVER (PARTITION BY product_id ORDER BY month) AS delta,
+       ROUND(100.0 * (revenue - LAG(revenue) OVER (PARTITION BY product_id ORDER BY month))
+             / NULLIF(LAG(revenue) OVER (PARTITION BY product_id ORDER BY month), 0), 2) AS pct_change
+FROM monthly_revenue;
+```
+
+`NULLIF(prev, 0)` guards against divide-by-zero; the first row's `LAG` is NULL by design.
+
+**Dedup keeping latest** — `QUALIFY` is convenient but narrow.
+
+```sql
+-- Portable: rank then filter in an outer query
+SELECT * FROM (
+  SELECT *, ROW_NUMBER() OVER (PARTITION BY email ORDER BY updated_at DESC) AS rn
+  FROM users
+) d WHERE rn = 1;
+
+-- DuckDB / BigQuery / Snowflake only: QUALIFY skips the wrapper. NOT in Postgres/MySQL/SQLite.
+SELECT * FROM users
+QUALIFY ROW_NUMBER() OVER (PARTITION BY email ORDER BY updated_at DESC) = 1;
+```
+
+**Recursive CTE with a depth guard** — always bound the recursion.
+
+```sql
+-- Good: org chart walk; depth column stops runaway / cyclic graphs
+WITH RECURSIVE tree AS (
+  SELECT id, manager_id, name, 1 AS depth
+  FROM employees WHERE manager_id IS NULL
+  UNION ALL
+  SELECT e.id, e.manager_id, e.name, t.depth + 1
+  FROM employees e JOIN tree t ON e.manager_id = t.id
+  WHERE t.depth < 50            -- hard ceiling; for true cycles track a path array
+)
+SELECT * FROM tree;
+```
+
+**Conditional aggregation / pivot** — `FILTER` reads cleaner than `CASE`.
+
+```sql
+-- Portable everywhere: CASE inside the aggregate
+SELECT region,
+       SUM(CASE WHEN status = 'paid' THEN amount ELSE 0 END) AS paid,
+       SUM(CASE WHEN status = 'open' THEN amount ELSE 0 END) AS open
+FROM invoices GROUP BY region;
+
+-- Postgres/SQLite/DuckDB: FILTER is the standard, more readable form. NOT in MySQL/SQL Server.
+SELECT region,
+       SUM(amount) FILTER (WHERE status = 'paid') AS paid,
+       SUM(amount) FILTER (WHERE status = 'open') AS open
+FROM invoices GROUP BY region;
+```
+
+**`GROUPING SETS` / `ROLLUP`** — one scan, multiple aggregation levels.
+
+```sql
+-- Good: subtotals per (region, product), per region, and grand total in one query
+SELECT region, product, SUM(amount) AS total
+FROM sales
+GROUP BY ROLLUP (region, product);   -- = GROUPING SETS ((region,product),(region),())
+```
+
+**Anti-join via `NOT EXISTS`** — the NULL-safe "rows with no match."
+
+```sql
+-- Good: customers who never ordered; correct even if orders.customer_id has NULLs
+SELECT c.id, c.name FROM customers c
+WHERE NOT EXISTS (SELECT 1 FROM orders o WHERE o.customer_id = c.id);
+```
+
+**The `NOT IN`-NULL footgun.**
+
+```sql
+-- Bad: if ANY returned customer_id is NULL, this yields ZERO rows, silently
+SELECT * FROM customers
+WHERE id NOT IN (SELECT customer_id FROM orders);
+
+-- Good: NOT EXISTS, or NOT IN with an explicit IS NOT NULL filter on the inner column
+SELECT * FROM customers c
+WHERE NOT EXISTS (SELECT 1 FROM orders o WHERE o.customer_id = c.id);
+```
+
+## Portability quick map
+
+| Construct | Notes |
+| --- | --- |
+| `QUALIFY` | DuckDB / BigQuery / Snowflake only — elsewhere wrap in a subquery and filter `rn` |
+| `FILTER (WHERE …)` | Postgres / SQLite / DuckDB — MySQL & SQL Server need `CASE` |
+| `GROUPS` frame, `EXCLUDE` | Postgres 11+, SQLite 3.28+ — **not in MySQL 8** |
+| `EXCEPT` | Standard; Oracle spells it `MINUS` |
+| Row limiting | `LIMIT … OFFSET` (Postgres/MySQL/SQLite/DuckDB) vs `FETCH FIRST n ROWS ONLY` (standard/SQL Server 2012+) vs `TOP n` (SQL Server) |
+| Set-op column match | By **position and type**, not by name — order your columns identically |
+
+Full six-engine matrix in `references/portability.md`.
+
+## Anti-patterns / rationalizations -> STOP
+
+| Rationalization | Reality | STOP |
+| --- | --- | --- |
+| "`NOT IN` is clearer than `NOT EXISTS`" | One NULL in the inner set returns zero rows, silently | Use `NOT EXISTS` for nullable inner columns |
+| "`SELECT *` is fine in this query" | Hides which columns matter; breaks `GROUP BY`, ambiguous on joins | Project explicit, qualified columns |
+| "Old MySQL let me skip the GROUP BY column" | You get an arbitrary row per group | List every non-aggregated column |
+| "No frame needed, I just want a running sum" | Implicit `RANGE` lumps tied rows -> wrong total | Write `ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW` |
+| "I'll loop in app code and query per row" | N+1 round trips; a window function does it in one scan | Express it as one set-based statement |
+| "`UNION` to merge these results" | Pays a dedup sort and drops rows you wanted | `UNION ALL` unless dedup is the goal |
+| "`COUNT(*)` after the join is the real count" | A 1-to-many join fanned the rows out | Count on the base table or use a semi-join |
+| "Add `DISTINCT` to fix the duplicate rows" | Masks a fan-out join instead of fixing it | Find the join multiplying rows; fix the grain |
+
+## Verify
+
+Run `scripts/verify.sh` from your project root. It is read-only, never connects to a database, and runs
+on stock macOS bash 3.2. It heuristically scans discovered `.sql` files and warns on the footguns above
+(`NOT IN (SELECT …)`, comma-joins with WHERE-join predicates, `SELECT *` alongside `GROUP BY`, window
+`OVER (… ORDER BY …)` with no explicit frame) and, if `sqlfluff` is installed, lints with `--dialect ansi`.
+It exits non-zero only on a real `sqlfluff` lint error or unbalanced parens/quotes (dollar-quote aware);
+every heuristic is advisory `[warn]`, and an empty target passes clean.
+
+## See Also
+
+- `references/window-functions.md` — ranking/offset/aggregate-over catalog, every frame unit worked, `EXCLUDE`, named windows, implicit-frame trap, per-engine matrix.
+- `references/joins-and-sets.md` — every join type with row-count reasoning, semi/anti/lateral joins, set ops + `ALL`/dedup/`MINUS`, the fan-out-inflates-aggregates bug.
+- `references/ctes-and-recursion.md` — CTE structuring, recursive template (hierarchy/graph/series) with cycle + depth guards, the optimization-fence portability note.
+- `references/portability.md` — full dialect matrix across Postgres / MySQL 8 / SQLite / DuckDB / SQL Server / BigQuery.
+- Siblings: `../postgresdb/SKILL.md`, `../mysql/SKILL.md`, `../duckdb/SKILL.md`, `../clickhouse-analytics/SKILL.md`, `../drizzle-orm/SKILL.md`, `../prisma-orm/SKILL.md`, `../db-migrations/SKILL.md`. ORM/engine internals are out of scope here — this skill owns the SQL those tools ultimately emit.

package/skills/sql/evals/README.md

@@ -0,0 +1,9 @@
+# Eval harness — `sql`
+
+These cases are hand-graded prompts, not an automated test suite. Run them through an agent harness and grade honestly.
+
+**Triggering.** For each prompt in `cases.yaml`, start a fresh agent session with only the `sql` skill discoverable, paste the prompt verbatim, and run 3–5 trials (the decision is stochastic). A `should_trigger` case passes if the skill fires in the majority of trials; a `should_not_trigger` case passes if it stays quiet and the agent would plausibly route to the named `route_to` sibling (or `none`). Aim for ≥ 90% trigger accuracy across all cases — the near-misses (indexing, MySQL config, ORM builder, migrations, ClickHouse) deliberately share vocabulary with this skill, so they test intent, not keywords.
+
+**Capability.** Run each `capability` scenario twice — once WITHOUT the skill (clean agent) and once WITH it loaded — and score each transcript against its `must_include` rubric, one point per bullet that is specifically and correctly covered (not merely name-dropped). The skill passes if WITH-coverage reaches ≥ 80% of the bullets and clearly beats WITHOUT (target ≥ +30 points or fail→pass). If a baseline agent already nails the rubric, tighten it.
+
+**Artifact check.** `scripts/verify.sh` lints emitted `.sql` files heuristically (read-only, no DB connection); it complements the capability eval but does not replace it. Record trial counts and per-bullet verdicts so a reviewer can audit.

package/skills/sql/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: sql
+
+should_trigger:
+  - prompt: "Get the top 3 orders per customer by amount"
+    why: Classic top-N-per-group — ROW_NUMBER partitioned by customer, filtered on the rank. Core window-function craft.
+  - prompt: "My SUM is double the real total after I joined order_items, why?"
+    why: Non-obvious. A one-to-many join fans out rows and inflates every downstream aggregate — the canonical wrong-total bug this skill owns.
+  - prompt: "Write a running 7-day total with a window function"
+    why: Frame-clause craft (explicit ROWS vs implicit RANGE on tied dates).
+  - prompt: "Necesito una función de ventana para el ranking por categoría"
+    why: Spanish window-function trigger (PARTITION BY category, RANK/ROW_NUMBER).
+  - prompt: "Recursive CTE to walk an org-chart hierarchy with a depth limit"
+    why: WITH RECURSIVE with a depth/cycle guard — squarely in scope.
+  - prompt: "NOT IN with a subquery returns zero rows even though data exists"
+    why: Non-obvious. The NULL three-valued-logic footgun — NOT IN over a NULL-bearing subquery; fix is NOT EXISTS.
+  - prompt: "per què el JOIN duplica files i em surten totals inflats?"
+    why: Catalan trigger for the join fan-out / inflated-aggregate diagnosis.
+  - prompt: "Gaps and islands: find consecutive login streaks per user"
+    why: Non-obvious named pattern solved with window functions (difference of row numbers).
+
+should_not_trigger:
+  - prompt: "Add an index to speed up this Postgres query and read the EXPLAIN plan"
+    route_to: postgresdb
+    why: Engine internals — indexing and planner output are Postgres behavior, not portable query craft.
+  - prompt: "Configure MySQL InnoDB buffer pool size for better throughput"
+    route_to: mysql
+    why: MySQL engine configuration, not SQL query logic.
+  - prompt: "Write this query using Drizzle's query builder API"
+    route_to: drizzle-orm
+    why: ORM builder ergonomics; this skill owns the raw SQL, not the builder API.
+  - prompt: "Design the schema and write the migration for this orders table"
+    route_to: db-migrations
+    why: Schema design / DDL / migration, not SELECT-side query craft.
+  - prompt: "Optimize this columnar scan in ClickHouse"
+    route_to: clickhouse-analytics
+    why: OLAP columnar-engine specifics, not engine-agnostic query language.
+
+capability:
+  - scenario: >
+      Given orders(customer_id, created_at, amount), write a portable query returning each
+      customer's most recent order plus the percent change in amount vs their previous order.
+      Note any non-portable construct you use.
+    must_include:
+      - Uses a window function (LAG, or ROW_NUMBER to pick the latest)
+      - Explicit PARTITION BY customer_id ORDER BY created_at
+      - Handles the first-order case where the previous amount is NULL or zero (NULLIF/COALESCE or a filter)
+      - Computes percent change correctly ((cur - prev) / prev * 100)
+      - Flags at least one portability caveat (e.g. QUALIFY is DuckDB/BigQuery only; otherwise wrap in a subquery)
+      - Does NOT rely on an implicit window frame where ties on created_at would change the result

package/skills/sql/references/ctes-and-recursion.md

@@ -0,0 +1,63 @@
+# CTEs and recursion
+
+## Non-recursive CTEs
+
+`WITH name AS (…)` names an intermediate result so you can reference it (possibly multiple times) and read the query top-down instead of inside-out. Chain them; each may reference the ones above.
+
+```sql
+WITH paid AS (
+  SELECT customer_id, SUM(amount) AS spent
+  FROM orders WHERE status = 'paid'
+  GROUP BY customer_id
+),
+ranked AS (
+  SELECT *, RANK() OVER (ORDER BY spent DESC) AS rnk FROM paid
+)
+SELECT * FROM ranked WHERE rnk <= 10;
+```
+
+Use CTEs to: name a step, avoid repeating a subquery, or stage a recursive walk. Do **not** assume a CTE is materialized for free — see the optimization fence below.
+
+## Recursive CTEs
+
+`WITH RECURSIVE` has two arms joined by `UNION [ALL]`: an **anchor** (the seed rows) and a **recursive member** that references the CTE name. It iterates until the recursive arm produces no new rows.
+
+### Hierarchy (org chart) with a depth guard
+
+```sql
+WITH RECURSIVE chart AS (
+  SELECT id, manager_id, name, 1 AS depth, ARRAY[id] AS path
+  FROM employees WHERE manager_id IS NULL
+  UNION ALL
+  SELECT e.id, e.manager_id, e.name, c.depth + 1, c.path || e.id
+  FROM employees e
+  JOIN chart c ON e.manager_id = c.id
+  WHERE c.depth < 50              -- depth guard: bound the walk
+    AND e.id <> ALL(c.path)       -- cycle guard: don't revisit a node
+)
+SELECT * FROM chart ORDER BY path;
+```
+
+A real cyclic graph will loop forever (or exhaust memory) without a guard. Use **both**: a depth ceiling *and* a visited-path check. The `path` array technique is Postgres/DuckDB; SQLite/MySQL track depth and a string path instead. SQL Server requires `OPTION (MAXRECURSION n)`.
+
+### Graph walk (reachability)
+
+Same shape: anchor = start node, recursive arm follows edges, cycle guard on the accumulated path. Switch `UNION ALL` to `UNION` to collapse duplicate paths to the same node.
+
+### Generated series
+
+```sql
+-- Portable date spine without a numbers table
+WITH RECURSIVE days(d) AS (
+  SELECT DATE '2026-01-01'
+  UNION ALL
+  SELECT d + INTERVAL '1 day' FROM days WHERE d < DATE '2026-12-31'
+)
+SELECT d FROM days;
+```
+
+Postgres/DuckDB prefer `generate_series()`; SQLite and BigQuery have their own (`generate_series`, `GENERATE_DATE_ARRAY`). The recursive form above works where those don't.
+
+## The optimization fence portability note
+
+Historically Postgres **always materialized** a CTE — an optimization fence that could block predicate push-down and hurt performance. Since **Postgres 12** a CTE referenced once and free of side effects is inlined by default; force the old behavior with `WITH x AS MATERIALIZED (…)` or prevent it with `AS NOT MATERIALIZED`. Other engines (MySQL 8, SQLite, DuckDB, SQL Server) generally inline CTEs as ordinary subqueries. Do not rely on a CTE as a performance barrier across engines.

package/skills/sql/references/joins-and-sets.md

@@ -0,0 +1,71 @@
+# Joins and set operations
+
+## Join types and what they do to row counts
+
+Reason about every join as a row-count operation first, columns second.
+
+| Join | Rows returned | When right has no match | When right has many matches |
+|---|---|---|---|
+| `INNER JOIN` | only matching pairs | left row dropped | left row **duplicated** (fan-out) |
+| `LEFT JOIN` | all left rows | right columns NULL | left row duplicated (fan-out) |
+| `RIGHT JOIN` | all right rows | left columns NULL | right row duplicated |
+| `FULL JOIN` | all rows from both | NULLs on the missing side | duplication on both sides |
+| `CROSS JOIN` | `n × m` | n/a | n/a (intentional Cartesian) |
+
+**Fan-out** is the core hazard: a one-to-many join multiplies the left row once per match. If you then `SUM` or `COUNT(*)`, every aggregate is inflated by the match count — the canonical "wrong total" bug.
+
+```sql
+-- Bad: each order row repeats once per item; SUM(o.total) is multiplied by item count
+SELECT o.customer_id, SUM(o.total)
+FROM orders o JOIN order_items i ON i.order_id = o.id
+GROUP BY o.customer_id;
+
+-- Good: pre-aggregate items, then join one row to one row
+SELECT o.customer_id, SUM(o.total) AS revenue, SUM(i.qty) AS units
+FROM orders o
+JOIN (SELECT order_id, SUM(qty) AS qty FROM order_items GROUP BY order_id) i
+  ON i.order_id = o.id
+GROUP BY o.customer_id;
+```
+
+When you only need *existence* (not item columns), never join at all — use a semi-join.
+
+## Semi-join and anti-join
+
+- **Semi-join** = "left rows that have at least one match": `WHERE EXISTS (SELECT 1 FROM r WHERE r.fk = l.id)`. Returns each left row at most once — cannot fan out.
+- **Anti-join** = "left rows with no match": `WHERE NOT EXISTS (…)`. NULL-safe, unlike `NOT IN`.
+
+```sql
+-- customers who have ordered (semi) vs never ordered (anti)
+SELECT * FROM customers c WHERE EXISTS     (SELECT 1 FROM orders o WHERE o.customer_id = c.id);
+SELECT * FROM customers c WHERE NOT EXISTS (SELECT 1 FROM orders o WHERE o.customer_id = c.id);
+```
+
+`NOT IN (SELECT customer_id FROM orders)` returns **zero rows** if any `customer_id` is NULL, because the three-valued comparison yields `UNKNOWN`, never `TRUE`. Always prefer `NOT EXISTS` for anti-joins.
+
+## LATERAL joins (correlated derived tables)
+
+A `LATERAL` subquery may reference columns from tables to its left — the per-row "for each X, get its top N" pattern as a join. Postgres/DuckDB/SQL Server (`CROSS APPLY`) support it; MySQL 8 has `LATERAL`; SQLite and BigQuery do not.
+
+```sql
+-- top 3 orders per customer, set-based, via LATERAL
+SELECT c.id, o.*
+FROM customers c
+CROSS JOIN LATERAL (
+  SELECT * FROM orders o WHERE o.customer_id = c.id
+  ORDER BY o.amount DESC LIMIT 3
+) o;
+```
+
+## Set operations
+
+| Operator | Result | Cost |
+|---|---|---|
+| `UNION` | rows from both, **deduplicated** | sort/hash to dedup |
+| `UNION ALL` | rows from both, duplicates kept | cheap, no dedup pass |
+| `INTERSECT` | rows in both | dedup |
+| `EXCEPT` | rows in first not in second | dedup |
+
+- Columns are matched **by position**, not name; the count and types must align across both arms.
+- `EXCEPT` is `MINUS` in Oracle. MySQL gained `INTERSECT`/`EXCEPT` in 8.0.31; older MySQL emulates them with joins.
+- Default to `UNION ALL` and only pay for dedup when duplicates are actually possible and unwanted.

package/skills/sql/references/portability.md

@@ -0,0 +1,38 @@
+# Portability matrix
+
+Standard reference: **SQL:2023 (ISO/IEC 9075:2023)**, the current ninth edition (published June 2023). It added a native `JSON` type, the `ANY_VALUE` aggregate, and the `GREATEST`/`LEAST` scalar functions; window functions date back to SQL:2003. No engine implements the full standard — this table is what you actually rely on across six common targets.
+
+## Feature matrix
+
+| Construct | Postgres 11+ | MySQL 8 | SQLite 3.28+ | DuckDB | SQL Server | BigQuery |
+|---|---|---|---|---|---|---|
+| `ROWS` / `RANGE` frames | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `GROUPS` frame | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
+| `EXCLUDE` frame clause | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
+| `FILTER (WHERE …)` aggregate | ✅ | ❌ (use `CASE`) | ✅ | ✅ | ❌ (use `CASE`) | ❌ (use `CASE`) |
+| `QUALIFY` | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ |
+| `GROUPING SETS` / `ROLLUP` / `CUBE` | ✅ | `ROLLUP` only | ❌ | ✅ | ✅ | ✅ |
+| `INTERSECT` / `EXCEPT` | ✅ | ✅ (8.0.31+) | ✅ | ✅ | ✅ | ✅ |
+| `LATERAL` / `CROSS APPLY` | ✅ | ✅ | ❌ | ✅ | ✅ (`APPLY`) | n/a |
+| `WITH RECURSIVE` | ✅ | ✅ | ✅ | ✅ | ✅ (no `RECURSIVE` kw) | ✅ |
+| native `JSON` type | ✅ (`jsonb`) | ✅ | text + funcs | ✅ | ✅ | ✅ |
+| boolean type | ✅ | tinyint(1) | int 0/1 | ✅ | bit | ✅ |
+
+## Common dialect swaps
+
+| Need | Postgres | MySQL 8 | SQLite | DuckDB | SQL Server | BigQuery |
+|---|---|---|---|---|---|---|
+| limit rows | `LIMIT n OFFSET m` | `LIMIT m, n` | `LIMIT n OFFSET m` | `LIMIT n` | `OFFSET m ROWS FETCH NEXT n ROWS ONLY` / `TOP n` | `LIMIT n` |
+| set difference | `EXCEPT` | `EXCEPT` | `EXCEPT` | `EXCEPT` | `EXCEPT` | `EXCEPT DISTINCT` |
+| string concat | `\|\|` | `CONCAT()` | `\|\|` | `\|\|` | `+` / `CONCAT` | `CONCAT` / `\|\|` |
+| current timestamp | `now()` | `NOW()` | `datetime('now')` | `now()` | `SYSUTCDATETIME()` | `CURRENT_TIMESTAMP()` |
+| date + interval | `d + INTERVAL '1 day'` | `DATE_ADD(d, INTERVAL 1 DAY)` | `date(d,'+1 day')` | `d + INTERVAL 1 DAY` | `DATEADD(day,1,d)` | `DATE_ADD(d, INTERVAL 1 DAY)` |
+| null coalesce | `COALESCE` | `COALESCE`/`IFNULL` | `COALESCE`/`IFNULL` | `COALESCE` | `COALESCE`/`ISNULL` | `COALESCE`/`IFNULL` |
+| cast | `x::int` or `CAST` | `CAST` | `CAST` | `x::int` or `CAST` | `CAST`/`CONVERT` | `CAST`/`SAFE_CAST` |
+
+## Rules of thumb for portable SQL
+
+- Prefer the standard spelling: `CAST(x AS int)`, `COALESCE`, `FETCH FIRST` is the most portable limiter but `LIMIT/OFFSET` covers the open-source four.
+- Avoid `QUALIFY` and `FILTER` in code that must run everywhere — use the subquery wrapper and `CASE` instead, and leave a comment naming the cleaner dialect form.
+- Set-op arms match by position and type; name your columns explicitly in each arm.
+- When you do use a non-portable construct deliberately, flag it inline so a reviewer targeting another engine sees it immediately.

package/skills/sql/references/window-functions.md

@@ -0,0 +1,72 @@
+# Window functions — full catalog
+
+A window function computes across a set of rows *related to the current row* without collapsing them. Shape: `func(args) OVER (PARTITION BY … ORDER BY … <frame>)`. `PARTITION BY` resets the calculation per group; `ORDER BY` defines order *within* the partition; the frame defines which rows feed the current calculation.
+
+## Function families
+
+| Family | Functions | Needs ORDER BY? | Frame applies? |
+|---|---|---|---|
+| Ranking | `ROW_NUMBER`, `RANK`, `DENSE_RANK`, `NTILE(n)`, `PERCENT_RANK`, `CUME_DIST` | yes | no (ignore frame) |
+| Offset | `LAG(col, n, default)`, `LEAD(col, n, default)`, `FIRST_VALUE`, `LAST_VALUE`, `NTH_VALUE` | yes | `FIRST_VALUE`/`LAST_VALUE`/`NTH_VALUE` honor it |
+| Aggregate-over | `SUM`, `AVG`, `COUNT`, `MIN`, `MAX`, `ANY_VALUE` `OVER (…)` | optional | yes |
+
+- `ROW_NUMBER` is always unique (1,2,3,4); `RANK` leaves gaps after ties (1,1,3); `DENSE_RANK` does not (1,1,2). Pick by intent.
+- `LAG`/`LEAD` take an optional default so the first/last row is not NULL: `LAG(amount, 1, 0)`.
+- `FIRST_VALUE`/`LAST_VALUE` are frame-sensitive. `LAST_VALUE` under the default frame returns the *current* row, not the partition's last — extend the frame to `ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING`.
+
+## Frame units, worked
+
+Given a partition ordered by `day` with values for `amount`:
+
+```sql
+-- ROWS: N physical rows regardless of value ties. Trailing 7-row average:
+AVG(amount) OVER (ORDER BY day ROWS BETWEEN 6 PRECEDING AND CURRENT ROW)
+
+-- RANGE: a value window. With numeric offset, "all rows whose day is within 7 of current":
+SUM(amount) OVER (ORDER BY day RANGE BETWEEN INTERVAL '7' DAY PRECEDING AND CURRENT ROW)
+
+-- GROUPS: N distinct peer-groups (Postgres 11+, SQLite 3.28+; NOT MySQL 8):
+SUM(amount) OVER (ORDER BY day GROUPS BETWEEN 2 PRECEDING AND CURRENT ROW)
+```
+
+Frame bounds: `UNBOUNDED PRECEDING`, `n PRECEDING`, `CURRENT ROW`, `n FOLLOWING`, `UNBOUNDED FOLLOWING`.
+
+## The implicit-frame trap
+
+A window with `ORDER BY` but **no explicit frame** defaults to:
+
+```sql
+RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+```
+
+`RANGE` groups *peer* rows (rows tied on the `ORDER BY` value) into the same frame end — so on tied keys, a "running total" assigns every tied row the *same* cumulative value rather than incrementing row by row. For a true row-by-row cumulative, write `ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`. This default is identical across every engine; it is the single most common window bug.
+
+## EXCLUDE clause (Postgres 11+, SQLite 3.28+; not MySQL 8)
+
+Refines the frame after the bounds: `EXCLUDE CURRENT ROW`, `EXCLUDE GROUP` (current row + its peers), `EXCLUDE TIES` (peers but keep current), `EXCLUDE NO OTHERS` (default). Useful for "average of the others" calculations.
+
+## Named windows
+
+Define once with `WINDOW`, reuse by name — fewer repeated clauses, no drift:
+
+```sql
+SELECT id,
+       SUM(amount) OVER w  AS running,
+       AVG(amount) OVER w  AS avg_to_date
+FROM t
+WINDOW w AS (PARTITION BY cust ORDER BY day ROWS UNBOUNDED PRECEDING);
+```
+
+Supported in Postgres, MySQL 8, SQLite 3.28+, DuckDB. Window functions themselves were standardized in SQL:2003.
+
+## Per-engine support matrix
+
+| Feature | Postgres 11+ | MySQL 8 | SQLite 3.28+ | DuckDB | SQL Server | BigQuery |
+|---|---|---|---|---|---|---|
+| `ROWS` / `RANGE` frames | yes | yes | yes | yes | yes | yes |
+| `GROUPS` frame | yes | **no** | yes | yes | no | no |
+| `EXCLUDE` | yes | **no** | yes | yes | no | no |
+| numeric `RANGE` offset | yes | yes | yes | yes | yes | yes |
+| `FILTER (WHERE …)` on agg | yes | **no** | yes | yes | no | no |
+| `QUALIFY` | **no** | no | no | yes | no | yes |
+| named `WINDOW` | yes | yes | yes | yes | no | yes |