rsc-universal 0.1.1

package/skills/drizzle-orm/scripts/verify.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — drizzle-orm skill gate. Static lint of Drizzle TS source. NO DB connection.
+#
+# Usage:
+#   scripts/verify.sh [files...]            # lint the given .ts files
+#   scripts/verify.sh                       # discover *.ts under cwd (excludes vendor dirs)
+#
+# What it does (read-only, idempotent, never writes):
+#   1. Finds a drizzle.config.ts (given or discovered) and checks it carries dialect/schema/out.
+#   2. Reads the configured `dialect` and checks any table helper (pgTable/mysqlTable/sqliteTable)
+#      in the scanned files matches it.
+#   3. Checks a drizzle() call exists somewhere; and if db.query is used, that drizzle() is passed
+#      { schema } or { relations } (else db.query is undefined at runtime).
+#   4. Bans Prisma-isms (schema.prisma, PrismaClient, prisma generate) that mean the wrong ORM leaked in.
+#
+# Exit code: non-zero ONLY on a real failure. An empty/clean target (no Drizzle files found) is a
+# clean pass, not a failure. Missing optional context (e.g. no config) is a [skip], not a [fail].
+#
+# Portability: stock macOS bash 3.2 (no mapfile, no associative arrays). Arrays initialised so
+# expansion is safe under `set -u`.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+warn() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="$(pwd)"
+
+# ---- collect target files ----
+FILES=()
+if [ "$#" -gt 0 ]; then
+  for f in "$@"; do
+    if [ -f "$f" ]; then FILES+=("$f"); else err "no such file: $f"; fi
+  done
+else
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(
+    find "$ROOT" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/dist/*' -o -path '*/.next/*' \) -prune -o \
+      -type f -name '*.ts' -print0 2>/dev/null
+  )
+fi
+
+# Filter to files that actually look like Drizzle source (import from drizzle-orm/-kit, or a config).
+DRIZ_FILES=()
+for f in "${FILES[@]:-}"; do
+  [ -z "$f" ] && continue
+  if grep -Eq "drizzle-orm|drizzle-kit|drizzle\(|defineConfig" "$f" 2>/dev/null; then
+    DRIZ_FILES+=("$f")
+  fi
+done
+
+if [ "${#DRIZ_FILES[@]}" -eq 0 ]; then
+  ok "no Drizzle source found — nothing to verify (clean)"
+  exit 0
+fi
+
+# ---- locate a config among the targets, else discover one ----
+CONFIG=""
+for f in "${DRIZ_FILES[@]}"; do
+  case "$f" in *drizzle.config.ts) CONFIG="$f"; break;; esac
+done
+if [ -z "$CONFIG" ] && [ -f "$ROOT/drizzle.config.ts" ]; then
+  CONFIG="$ROOT/drizzle.config.ts"
+fi
+
+# ---- 1. config keys ----
+DIALECT=""
+if [ -n "$CONFIG" ]; then
+  miss=""
+  grep -Eq "\bdialect\b" "$CONFIG" || miss="$miss dialect"
+  grep -Eq "\bschema\b"  "$CONFIG" || miss="$miss schema"
+  grep -Eq "\bout\b"     "$CONFIG" || miss="$miss out"
+  if [ -n "$miss" ]; then
+    err "drizzle.config.ts missing key(s):$miss"
+  else
+    ok "drizzle.config.ts has dialect/schema/out"
+  fi
+  DIALECT="$(grep -Eo "dialect[[:space:]]*:[[:space:]]*['\"][a-z]+['\"]" "$CONFIG" \
+    | grep -Eo "['\"][a-z]+['\"]" | tr -d "\"'" | head -n1 || true)"
+else
+  warn "no drizzle.config.ts found — skipping config + dialect-match checks"
+fi
+
+# ---- 2. table helper matches dialect ----
+HELPERS="$(grep -hEo '\b(pgTable|mysqlTable|sqliteTable)\b' "${DRIZ_FILES[@]}" 2>/dev/null | sort -u | tr '\n' ' ' || true)"
+if [ -n "$HELPERS" ]; then
+  if [ -n "$DIALECT" ]; then
+    case "$DIALECT" in
+      postgresql) want="pgTable";;
+      mysql)      want="mysqlTable";;
+      sqlite|turso) want="sqliteTable";;
+      *) want="";;
+    esac
+    if [ -n "$want" ]; then
+      bad=""
+      for h in $HELPERS; do [ "$h" != "$want" ] && bad="$bad $h"; done
+      if [ -n "$bad" ]; then
+        err "dialect '$DIALECT' expects $want but found:$bad — table helper does not match config"
+      else
+        ok "table helper ($HELPERS) matches dialect '$DIALECT'"
+      fi
+    fi
+  else
+    note "table helper(s) found ($HELPERS) but no dialect to compare against"
+  fi
+fi
+
+# ---- 3. drizzle() present; db.query needs { schema } | { relations } ----
+HAS_DRIZZLE=0
+HAS_SCHEMA_OR_REL=0
+HAS_DBQUERY=0
+for f in "${DRIZ_FILES[@]}"; do
+  grep -Eq "\bdrizzle\(" "$f" && HAS_DRIZZLE=1
+  grep -Eq "drizzle\([^)]*\{[^}]*(schema|relations)" "$f" && HAS_SCHEMA_OR_REL=1
+  grep -Eq "\bdb\.query\b|\b_query\b" "$f" && HAS_DBQUERY=1
+done
+
+# Tolerate multi-line drizzle(...) calls: re-scan whole-file (newline-flattened) for the option.
+if [ "$HAS_SCHEMA_OR_REL" -eq 0 ] && [ "$HAS_DRIZZLE" -eq 1 ]; then
+  for f in "${DRIZ_FILES[@]}"; do
+    if tr '\n' ' ' < "$f" | grep -Eq "drizzle\(.*\{[^}]*(schema|relations)"; then
+      HAS_SCHEMA_OR_REL=1; break
+    fi
+  done
+fi
+
+if [ "$HAS_DRIZZLE" -eq 1 ]; then
+  ok "drizzle() connection call present"
+else
+  note "no drizzle() call in scanned files (schema-only file?)"
+fi
+
+if [ "$HAS_DBQUERY" -eq 1 ] && [ "$HAS_SCHEMA_OR_REL" -eq 0 ]; then
+  err "db.query used but drizzle() is not passed { schema } or { relations } — db.query will be undefined"
+elif [ "$HAS_DBQUERY" -eq 1 ]; then
+  ok "db.query usage has { schema } | { relations } on drizzle()"
+fi
+
+# ---- 4. Prisma-ism banlist ----
+for f in "${DRIZ_FILES[@]}"; do
+  if grep -Eq "schema\.prisma|PrismaClient|prisma[[:space:]]+generate" "$f"; then
+    err "$f: Prisma-ism found (schema.prisma/PrismaClient/prisma generate) — wrong ORM leaked in"
+  fi
+done
+[ "$EXIT" -eq 0 ] && ok "no Prisma-isms"
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"

package/skills/duckdb/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: duckdb
+description: "Use when you need fast analytical SQL over local files (Parquet/CSV/JSON/Arrow) with no server to run, when embedding OLAP in an app or notebook, when a pandas groupby/merge on multi-GB data is too slow, or when reading data straight from S3/HTTP/a lakehouse. Triggers: 'query a folder of parquet files in place', 'aggregate a 5GB CSV on my laptop', 'replace this slow pandas groupby', 'run SQL over a dataframe in Jupyter', 'read these parquet files from S3 without downloading', 'out-of-core aggregate', 'analizar un CSV enorme sin montar un servidor', 'consultar parquet en local sense base de dades'. NOT a multi-user production analytics server (that is clickhouse-analytics), NOT your app's transactional CRUD database (that is postgresdb)."
+tags: [duckdb, olap, analytics, parquet, embedded-database, sql, columnar]
+recommends: [clickhouse-analytics, postgresdb, sql, sqlite-turso, data-cleaning, business-intelligence]
+origin: risco
+---
+
+# DuckDB — embedded columnar OLAP, no server
+
+DuckDB is an in-process analytical (OLAP) database: it links into your process like SQLite, but stores
+data column-by-column and vectorizes execution for aggregates, joins, and window functions. There is no
+server, no port, no daemon — you `pip install duckdb` (or drop one CLI binary) and query. Its killer move
+is reading Parquet/CSV/JSON/Arrow **in place**, without a load step, so a folder of files becomes a table.
+
+The fact that drives every routing decision below: DuckDB is **one writer, many readers, single process**.
+It is brilliant for analysis on one machine and wrong for multi-user serving or transactional app writes.
+
+Latest stable is **v1.5.3** (released 2026-05-20). Pin the **LTS line (v1.4.x; v1.4.4 LTS shipped
+2026-01-26)** for anything long-lived — LTS gets ~1 year of patches and a stable storage format. Use 1.5.x
+for greenfield exploration.
+
+## Is DuckDB the tool? (decide first)
+
+| Your workload | Reach for |
+| --- | --- |
+| Analytics over local/remote files, one process, one writer | **duckdb** (this skill) |
+| Many concurrent users, production query API, dashboards-as-a-service, petabyte scale | [`clickhouse-analytics`](../clickhouse-analytics/SKILL.md) |
+| App transactional CRUD: users, orders, many small writes, FKs, connection pool | [`postgresdb`](../postgresdb/SKILL.md) |
+| Embedded single-file **transactional** store / edge / sync | [`sqlite-turso`](../sqlite-turso/SKILL.md) |
+| Pure SQL syntax question, engine-agnostic (window fns, CTEs) | [`sql`](../sql/SKILL.md) |
+| Similarity / embedding search as the core workflow | [`vector-db`](../vector-db/SKILL.md) |
+
+The two you will confuse most: DuckDB vs ClickHouse is **embedded-single-node vs server-distributed** —
+under ~10GB on one box DuckDB usually wins; pick ClickHouse when many people query concurrently. DuckDB vs
+SQLite is **same niche, opposite workload** — both embedded single-file, but SQLite is row-store OLTP and
+DuckDB is column-store OLAP. Don't run your app's writes through DuckDB. (Some recommended siblings above
+may not be built in this collection yet; the routing decision still holds.)
+
+## Install & version
+
+```bash
+# Python (replacement-scan + relational API)
+pip install 'duckdb==1.4.4'        # LTS, for long-lived projects — stable storage format + patches
+pip install duckdb                  # current stable, for greenfield exploration
+
+# CLI (single static binary)
+curl https://install.duckdb.org | sh   # or: brew install duckdb
+duckdb -version
+```
+
+Why pin LTS for production: the on-disk `.duckdb` format and extension ABI are stable within an LTS line,
+so a routine upgrade won't strand a persisted database or break an installed extension mid-project.
+
+## Query files directly — the killer feature
+
+Do **not** load a file into pandas just to query it. Point DuckDB at the path and let it scan only the
+columns and row groups it needs (Parquet metadata pushdown). A bare string path is a replacement scan, so
+`FROM 'data/*.parquet'` works without naming a reader.
+
+```python
+import duckdb
+
+# BAD: read the whole file into RAM, then aggregate in pandas
+import pandas as pd
+df = pd.read_parquet("sales/")          # pulls every column of every file into memory
+out = df.groupby("region")["amount"].sum()
+
+# GOOD: scan in place, only the two needed columns ever touch memory
+out = duckdb.sql("""
+    FROM 'sales/*.parquet'
+    SELECT region, sum(amount) AS revenue
+    GROUP BY ALL
+    ORDER BY revenue DESC
+""").df()
+```
+
+Readers and globs you will actually use:
+
+```sql
+SELECT * FROM read_parquet('s3://bkt/y=*/m=*/*.parquet', filename = true);  -- glob + source col
+SELECT * FROM read_csv_auto('events.csv');         -- sniff delimiter/types/header
+SELECT * FROM read_csv('raw.csv', header = false, types = {'id': 'BIGINT'});  -- when sniffing is wrong
+SELECT * FROM read_json_auto('logs/*.ndjson');     -- newline-delimited or array JSON
+```
+
+`filename = true` adds a `filename` column — essential when a glob mixes partitions and you need to know
+which file a row came from.
+
+## In-memory vs persistent
+
+```python
+con = duckdb.connect()                    # in-memory: default, gone when the process exits
+con = duckdb.connect("analytics.duckdb")  # single file, created if absent; extension is not significant
+```
+
+Persist when: the dataset is reused across runs, an intermediate result is larger than RAM (DuckDB spills
+to the file), or you are curating a dataset to share. Otherwise stay in-memory — it is the fast path and
+needs no cleanup. The whole database is **one file**; copy it to move the database.
+
+## Python / dataframe interop
+
+In-scope pandas/Polars/Arrow frames are queryable **by variable name** — that is a replacement scan, no
+registration needed. The relational API is lazy; nothing executes until you materialize.
+
+```python
+import duckdb, pandas as pd
+orders = pd.read_parquet("orders.parquet")        # ordinary frame in local scope
+
+rel = duckdb.sql("FROM orders SELECT region, sum(amount) AS rev GROUP BY ALL")  # lazy, by name
+rel.df()        # -> pandas        rel.pl()       # -> Polars
+rel.arrow()     # -> Arrow table   rel.fetchall() # -> list[tuple]
+```
+
+Use a single connection per thread, never share one cursor across threads. Full client surface —
+parameterized queries, relational operators, NumPy/torch round-trips, threading rules — is in
+[references/python-and-interop.md](references/python-and-interop.md).
+
+## Friendly SQL — use the dialect
+
+DuckDB's dialect removes the boilerplate that makes analytics SQL tedious. Prefer it in DuckDB-only code.
+
+```sql
+FROM events SELECT count(*);                 -- FROM-first: pipe-friendly, valid on its own
+SELECT * EXCLUDE (raw_payload) FROM events;  -- everything but the noisy column
+SELECT * REPLACE (lower(email) AS email) FROM users;  -- transform one column, keep the rest
+SELECT region, sum(amount) FROM sales GROUP BY ALL;   -- no restating non-aggregates
+SELECT * FROM sales ORDER BY ALL;            -- deterministic order without listing columns
+SELECT COLUMNS('amount_.*') FROM sales;      -- regex over column names
+SELECT 1, 2, 3,                              -- trailing commas are legal
+```
+
+`GROUP BY ALL` / `ORDER BY ALL` are the biggest wins: add a column to the SELECT and the grouping follows
+automatically, so the two clauses can't drift out of sync.
+
+## Remote + lakehouse data
+
+Read from S3/GCS/HTTP without downloading first: load `httpfs` and store credentials in a secret.
+
+```sql
+INSTALL httpfs; LOAD httpfs;
+CREATE SECRET s3 (TYPE s3, PROVIDER credential_chain);  -- picks up env/role creds
+SELECT region, sum(amount) FROM read_parquet('s3://bkt/sales/*.parquet') GROUP BY ALL;
+```
+
+Iceberg, Delta, and DuckLake (DuckDB's own SQL-catalog lakehouse format) are read via extensions. Secret
+config, hive-partition globs, and the lakehouse one-liners live in
+[references/remote-and-lakehouse.md](references/remote-and-lakehouse.md).
+
+## Export & handoff
+
+```sql
+COPY (SELECT region, sum(amount) AS rev FROM 'sales/*.parquet' GROUP BY ALL)
+  TO 'summary.parquet' (FORMAT parquet);
+
+COPY sales TO 'out/' (FORMAT parquet, PARTITION_BY (year, month));  -- hive-partitioned dataset
+```
+
+Parquet is the default handoff: it keeps types and reads straight back into DuckDB, Spark, pandas, or
+ClickHouse. Use `PARTITION_BY` so downstream readers can prune partitions.
+
+## Outgrowing DuckDB
+
+DuckDB scales **up** (more RAM/threads, out-of-core spill), not **out**. Tune within one box:
+
+```sql
+PRAGMA threads = 8;            -- match cores
+PRAGMA memory_limit = '12GB';  -- cap RAM; the rest spills to the temp dir / database file
+```
+
+Hand off when you hit the single-process wall: concurrent **writers** or a multi-user query API or an
+always-on service → [`clickhouse-analytics`](../clickhouse-analytics/SKILL.md). Want managed/shared/hybrid
+DuckDB without running infra → MotherDuck (managed DuckDB-as-a-service; `ATTACH 'md:'`) — the scale-out
+escape hatch, not the default.
+
+## Anti-patterns
+
+| Rationalization | Reality → STOP |
+| --- | --- |
+| "Load the file into pandas, then query it" | You just paged the whole file through RAM. `FROM 'file.parquet' SELECT ...` scans only needed columns. |
+| "DuckDB can be our app's database" | One writer, single process — concurrent CRUD writers corrupt the workflow. App OLTP is `postgresdb`. |
+| "Spin up DuckDB behind our dashboard API for 200 users" | It's embedded, not a server; concurrent users serialize on the writer. That's `clickhouse-analytics`. |
+| "Just use the latest version in prod" | Pin the **LTS** (1.4.x; v1.4.4 shipped 2026-01-26) so a future upgrade doesn't break the on-disk format / extension ABI. |
+| "Download the S3 files, then read them" | `INSTALL httpfs` + `CREATE SECRET` reads `s3://...` in place with row-group pushdown. No download. |
+| "`SELECT *` over this 200-column Parquet" | Columnar engine — list the columns you need so it skips the rest. `SELECT *` reads everything. |
+| "GROUP BY a, b, c (restate every column)" | Drift bait. `GROUP BY ALL` tracks the SELECT automatically. |
+| "It's embedded so I don't need to think about RAM" | Set `memory_limit` / `threads`; without a cap a runaway aggregate can thrash before it spills. |
+| "Use DuckDB as our embeddings/vector store" | VSS exists but vector search is `vector-db`'s workflow, not DuckDB's home turf. |
+
+## References
+
+- [references/python-and-interop.md](references/python-and-interop.md) — full Python client: connect/cursor, `?`/`$name` parameters, relational operators, register/unregister frames, pandas/Polars/Arrow/NumPy round-trips, transactions, threading caveat.
+- [references/remote-and-lakehouse.md](references/remote-and-lakehouse.md) — httpfs, `CREATE SECRET` for S3/GCS/Azure, hive globs, Iceberg/Delta/DuckLake reads, partitioned writes, MotherDuck `ATTACH 'md:'`.
+
+## Verify
+
+Run `scripts/verify.sh` from anywhere. It runs a tiny self-contained smoke test — prefers the `duckdb`
+CLI, falls back to `python3 -c "import duckdb"` — that runs an aggregate and a `read_csv_auto` over a
+generated file and asserts a known scalar, proving the documented commands execute on your installed
+version. If neither the CLI nor the Python module is present it prints `SKIP` and exits 0. No network.
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), record this project's
+DuckDB decisions — version pin, file layout, persistent vs in-memory, remote/secret setup — in
+`02-DOCS/wiki/stack/duckdb.md` and link it from the root `CLAUDE.md` `## Knowledge map`. Read it first on
+every use and keep choices consistent. No `02-DOCS/`? Skip silently. Conventions are recorded, never gated.

package/skills/duckdb/evals/README.md

@@ -0,0 +1,31 @@
+# Eval harness — `duckdb`
+
+This checks two things: **triggering** (does the skill fire on real DuckDB situations and stay quiet on
+near-misses that belong to a sibling?) and **capability** (does loading the skill measurably improve the
+answer?). Cases live in `cases.yaml`. These 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 the documented DuckDB commands actually run; the eval cases here grade judgment, not code.
+
+## Triggering
+
+For each prompt: start a fresh agent with only the `duckdb` skill discoverable, paste the prompt verbatim,
+and observe whether the agent reaches for DuckDB. Run 3–5 trials (the decision is stochastic).
+`should_trigger` passes if DuckDB fires in the majority of trials. `should_not_trigger` passes if it does
+**not** fire; each such case names a `route_to` sibling (`clickhouse-analytics`, `postgresdb`, `sql`,
+`sqlite-turso`, `vector-db`) — sanity-check the agent would plausibly route there, but any not-duckdb route
+still passes this skill's 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 all 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 a baseline agent already nails it, tighten the rubric.
+
+## Notes
+
+Prompts are deliberately varied: some never say "DuckDB" (slow pandas groupby, out-of-core join,
+analyze-a-CSV-without-a-server), and one is in Spanish — these test intent recognition, not keyword
+matching. Record trial counts and per-bullet verdicts so a reviewer can audit; don't report a bare
+pass/fail.

package/skills/duckdb/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: duckdb
+
+should_trigger:
+  - prompt: "I have a directory full of monthly parquet files and I want to sum revenue by region across all of them. What's the fastest way without setting up infrastructure?"
+    why: "Core case: analytical aggregate over a folder of Parquet files in place, explicitly 'without infrastructure' — DuckDB's killer read_parquet-glob feature."
+  - prompt: "My pandas groupby on a 5GB dataframe takes forever and sometimes runs out of memory. Is there a faster way to do this aggregation?"
+    why: "Replacing a slow/OOM pandas groupby/merge with a vectorized out-of-core engine is a named when-to-use; the user never says DuckDB."
+  - prompt: "Necesito analizar un CSV gigante de varios GB en mi portátil sin levantar un servidor de base de datos. ¿Qué uso?"
+    why: "Spanish phrasing for ad-hoc analytics on a large CSV on a single machine with no server — exactly DuckDB's niche."
+  - prompt: "I want to run SQL directly over a dataframe inside my Jupyter notebook without exporting it first. Possible?"
+    why: "Embedded analytics in a notebook via replacement scan over an in-scope frame — a core embedded-OLAP use case."
+  - prompt: "Can I query these parquet files straight from our S3 bucket and aggregate them, without downloading them to disk first?"
+    why: "Non-obvious: most people download first; DuckDB reads s3:// in place via httpfs with row-group pushdown. Tests intent over keywords."
+  - prompt: "I need an out-of-core aggregate that spills to disk because the join result won't fit in RAM, but I don't want to stand up Spark or a cluster."
+    why: "Non-obvious single-node out-of-core spilling workload that explicitly rejects distributed infra — DuckDB scales up, not out."
+
+should_not_trigger:
+  - prompt: "Build a production analytics API that serves dashboards to hundreds of concurrent users with sub-second queries all day."
+    route_to: "clickhouse-analytics"
+    why: "Many concurrent users + always-on production serving is the single-writer/single-process boundary DuckDB explicitly cedes to ClickHouse."
+  - prompt: "Set up the database for my web app to store users, orders, and handle lots of small writes with foreign keys and a connection pool."
+    route_to: "postgresdb"
+    why: "Transactional OLTP app database with many small writes and FKs — row-store territory, not columnar OLAP."
+  - prompt: "What's the correct syntax for a SQL window function using ROW_NUMBER with PARTITION BY and ORDER BY?"
+    route_to: "sql"
+    why: "Engine-agnostic SQL language question, not an engine choice; belongs to the generic sql skill."
+  - prompt: "I need to embed a small transactional database inside my mobile/edge app for local reads and writes that syncs later."
+    route_to: "sqlite-turso"
+    why: "Embedded single-file TRANSACTIONAL store at the edge — same niche as DuckDB but opposite (OLTP) workload."
+  - prompt: "Build a similarity search over our document embeddings to find the nearest vectors for a query."
+    route_to: "vector-db"
+    why: "Vector/embedding search as the core workflow is vector-db's job even though DuckDB ships a VSS extension."
+
+capability:
+  - scenario: "User has a folder of monthly Parquet files at `sales/2025-*.parquet`, each with columns region, amount, ts. They want to aggregate total revenue by region across ALL files and write the result to `summary.parquet`, with no infrastructure."
+    must_include:
+      - "Reads the files with a glob in place — read_parquet('sales/2025-*.parquet') or FROM 'sales/2025-*.parquet' — no intermediate pandas/Polars load step"
+      - "Aggregates with GROUP BY (ideally GROUP BY ALL) and an aggregate function like sum(amount) AS revenue"
+      - "Exports with COPY (query) TO 'summary.parquet' (FORMAT parquet) rather than writing a CSV or pickling a dataframe"
+      - "Uses DuckDB (pip install duckdb / duckdb.sql or the CLI) and does not stand up a server or a cluster"
+      - "Optionally notes only the needed columns are scanned (columnar pushdown) and/or pins the version, without over-engineering"

package/skills/duckdb/references/python-and-interop.md

@@ -0,0 +1,105 @@
+# DuckDB — Python client & dataframe interop
+
+Full surface offloaded from the SKILL body. DuckDB v1.5.2 / LTS 1.4.x.
+
+## Connect, cursor, scope
+
+```python
+import duckdb
+
+# Module-level default connection (in-memory). Convenient for scripts/notebooks.
+duckdb.sql("SELECT 42").fetchone()        # (42,)
+
+# Explicit connection — required for a persistent file or per-thread isolation.
+con = duckdb.connect("analytics.duckdb")  # created if absent
+cur = con.cursor()                        # independent cursor; safe to hand to one thread
+con.close()                               # or: with duckdb.connect(...) as con: ...
+```
+
+A replacement scan resolves a bare identifier in the SQL against Python variables in scope, so a local
+`orders` frame is queryable as `FROM orders` with no registration. This only works on the default
+connection / the connection that ran `.sql()` from that scope.
+
+## Parameterized queries — never f-string user input
+
+```python
+con.execute("SELECT * FROM t WHERE region = ? AND amount > ?", ["EU", 100]).fetchall()
+
+con.execute(
+    "SELECT * FROM t WHERE region = $region AND amount > $min",
+    {"region": "EU", "min": 100},
+).fetchall()
+```
+
+Positional `?` and named `$name` both work. Parameterizing is correctness (typing) and safety, not just
+style — string-building SQL invites injection and quoting bugs.
+
+## Relational API — lazy, chainable
+
+`duckdb.sql(...)` and the relational operators return a lazy relation. Nothing executes until you
+materialize. Chain operators or drop into SQL, whichever is clearer.
+
+```python
+rel = con.sql("FROM 'sales/*.parquet'")          # a relation, not yet executed
+(rel.filter("amount > 0")
+    .aggregate("region, sum(amount) AS rev")     # GROUP BY inferred from non-aggregates
+    .order("rev DESC")
+    .limit(10)
+    .df())                                       # materialize here
+
+rel.project("region, amount")                    # SELECT
+rel.join(other, "region")                        # join on a condition / column
+```
+
+## Materializers
+
+| Call | Returns | Use when |
+| --- | --- | --- |
+| `.df()` | pandas DataFrame | downstream pandas / plotting |
+| `.pl()` | Polars DataFrame | Polars pipeline |
+| `.arrow()` | pyarrow.Table | zero-copy handoff, Arrow Flight, Parquet |
+| `.fetchall()` | list[tuple] | small results, plain Python |
+| `.fetchone()` | tuple / None | single scalar/row |
+| `.fetchnumpy()` | dict[str, np.ndarray] | numeric columns into NumPy |
+| `.torch()` | dict of tensors | feeding a model (when torch installed) |
+
+## Registering and unregistering frames
+
+Replacement scan covers most cases, but register explicitly when the frame isn't in the calling scope
+(e.g. built inside a function) or you want a stable name across queries.
+
+```python
+con.register("v", some_dataframe)        # now queryable as FROM v
+con.sql("FROM v SELECT count(*)")
+con.unregister("v")                      # release the reference
+```
+
+`pyarrow.dataset` objects register the same way and get predicate/projection pushdown into the dataset.
+
+## Round-trips
+
+```python
+# pandas / Polars / Arrow all go in and come out without an explicit conversion step:
+con.sql("FROM my_pandas_df SELECT *").pl()        # pandas in, Polars out
+con.sql("FROM my_polars_df SELECT *").arrow()     # Polars in, Arrow out
+con.from_arrow(arrow_table).aggregate("k, count(*)").df()
+```
+
+## Transactions
+
+```python
+con.execute("BEGIN")
+con.execute("INSERT INTO t VALUES (1)")
+con.execute("COMMIT")          # or ROLLBACK
+```
+
+ACID within the single process. Remember the model: one writer. Don't open two writing connections to the
+same file from different processes expecting concurrent writes — the second blocks or errors.
+
+## Threading caveat
+
+- One connection (or one `.cursor()`) **per thread**. Never share a cursor across threads.
+- The module-level default connection is convenient but not for concurrent threads — give each thread its
+  own `duckdb.connect(...)` (or `con.cursor()`).
+- Reads parallelize internally across `PRAGMA threads`; you do not need threads to parallelize a single
+  query — DuckDB already vectorizes and multi-threads execution.

package/skills/duckdb/references/remote-and-lakehouse.md

@@ -0,0 +1,101 @@
+# DuckDB — remote data & lakehouse
+
+Offloaded from the SKILL body. DuckDB v1.5.2 / LTS 1.4.x.
+
+## httpfs: read from S3 / GCS / Azure / HTTP in place
+
+```sql
+INSTALL httpfs;        -- one-time per database/install
+LOAD httpfs;           -- per session
+SELECT count(*) FROM read_parquet('https://host/path/data.parquet');  -- plain HTTP works immediately
+```
+
+`httpfs` streams remote files with HTTP range requests, so Parquet row-group and column pushdown still
+apply — you fetch only the bytes you read, not the whole object.
+
+## CREATE SECRET — credentials done right
+
+Never inline keys into SQL. Use a secret; prefer the credential chain so creds come from the environment
+or an instance/role rather than being typed.
+
+```sql
+-- Pick up env vars / instance role / SSO automatically (recommended):
+CREATE SECRET s3 (TYPE s3, PROVIDER credential_chain);
+
+-- Explicit, when you must (e.g. a non-default region / endpoint):
+CREATE SECRET s3 (
+    TYPE s3,
+    KEY_ID '...', SECRET '...',
+    REGION 'eu-west-1'
+);
+
+-- GCS (S3-compatible) and Azure have their own TYPEs:
+CREATE SECRET gcs (TYPE gcs, KEY_ID '...', SECRET '...');
+CREATE SECRET az  (TYPE azure, CONNECTION_STRING '...');
+```
+
+```sql
+SELECT region, sum(amount) AS rev
+FROM read_parquet('s3://bkt/sales/year=*/month=*/*.parquet', filename = true)
+GROUP BY ALL;
+```
+
+## Hive-partitioned globs
+
+A glob over `key=value/` directories auto-derives partition columns; filter on them and DuckDB prunes
+whole directories before reading any data.
+
+```sql
+SELECT *
+FROM read_parquet('s3://bkt/events/year=*/month=*/*.parquet', hive_partitioning = true)
+WHERE year = 2025 AND month = 4;     -- only the matching partition dirs are scanned
+```
+
+## Iceberg
+
+```sql
+INSTALL iceberg; LOAD iceberg;
+SELECT * FROM iceberg_scan('s3://bkt/warehouse/db/table');   -- read a table snapshot
+```
+
+## Delta Lake
+
+```sql
+INSTALL delta; LOAD delta;
+SELECT * FROM delta_scan('s3://bkt/delta/events');
+```
+
+## DuckLake — DuckDB's own lakehouse catalog
+
+DuckLake (ducklake.select) stores table metadata in a SQL catalog with Parquet data files — DuckDB's
+native lakehouse format. Attach it and query like a normal schema.
+
+```sql
+INSTALL ducklake; LOAD ducklake;
+ATTACH 'ducklake:metadata.ducklake' AS lake (DATA_PATH 's3://bkt/lake/');
+USE lake;
+CREATE TABLE sales AS FROM read_parquet('s3://bkt/raw/*.parquet');
+```
+
+## Partitioned write (handoff)
+
+```sql
+COPY (SELECT * FROM 'raw/*.parquet')
+  TO 's3://bkt/curated/' (FORMAT parquet, PARTITION_BY (year, month), OVERWRITE_OR_IGNORE);
+```
+
+Writes a hive-partitioned dataset so any reader (DuckDB, Spark, ClickHouse, pandas) can prune partitions.
+
+## MotherDuck — scale-out / share escape hatch
+
+MotherDuck is managed DuckDB-as-a-service with hybrid local+cloud execution. Reach for it to share a
+database or push heavy work to the cloud without running a server yourself — not the default.
+
+```sql
+ATTACH 'md:';                       -- connect to your MotherDuck account (auth via token)
+USE my_cloud_db;
+SELECT * FROM cloud_table LIMIT 10; -- query can run partly local, partly in the cloud
+```
+
+When the real need is many concurrent users or always-on production serving, that is
+`clickhouse-analytics`, not MotherDuck.