@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/drizzle-orm/references/relations-and-drivers.md

@@ -0,0 +1,118 @@
+# Drizzle: driver matrix & v1↔v2 relations migration
+
+Offloaded depth for `../SKILL.md`. Facts current as of 2026-06-02: npm `latest` is
+`drizzle-orm@0.45.2` (0.45 line `latest` since 2025-12-04), and the `rc` dist-tag is
+`1.0.0-rc.3` (2026-05-18).
+
+## Driver entrypoint matrix
+
+`drizzle()` is imported from a driver-specific path and wraps that driver's own client. Match the
+import to your database and host runtime.
+
+| Database / host | Import | Client dep | Notes |
+|---|---|---|---|
+| Postgres (Node, pooled) | `drizzle-orm/node-postgres` | `pg` | `new Pool(...)`; classic Node server |
+| Postgres (postgres-js) | `drizzle-orm/postgres-js` | `postgres` | fast; fine for Node and long-lived workers |
+| Neon (HTTP, edge) | `drizzle-orm/neon-http` | `@neondatabase/serverless` | HTTP — no TCP; ideal for edge/serverless. Platform setup → `../neon/SKILL.md` |
+| Neon (WebSocket) | `drizzle-orm/neon-serverless` | `@neondatabase/serverless` | supports transactions over WS |
+| Turso / libSQL | `drizzle-orm/libsql` | `@libsql/client` | SQLite-compatible; edge. Platform → `../sqlite-turso/SKILL.md` |
+| PlanetScale | `drizzle-orm/planetscale-serverless` | `@planetscale/database` | MySQL over HTTP; serverless. Platform → `../planetscale/SKILL.md` |
+| MySQL (Node) | `drizzle-orm/mysql2` | `mysql2` | standard MySQL server |
+| SQLite (Node native) | `drizzle-orm/better-sqlite3` | `better-sqlite3` | synchronous local SQLite |
+| SQLite (Bun) | `drizzle-orm/bun-sqlite` | built into Bun | Bun runtime only |
+| SQLite (`node:sqlite`) | `drizzle-orm/node-sqlite` | Node ≥ built-in | auto-detected by recent drizzle-kit for migrate + Studio |
+
+Supabase: it is Postgres — connect with `postgres-js` or `node-postgres` against the Supabase
+connection string. Platform/auth specifics → `../supabase/SKILL.md`.
+
+### Edge / serverless caveats
+
+- Edge runtimes (Vercel Edge, Cloudflare Workers) have no TCP sockets — use HTTP drivers
+  (`neon-http`, `planetscale-serverless`, libSQL HTTP).
+- HTTP drivers run each statement as a separate request; multi-statement interactive transactions
+  need a WebSocket driver (`neon-serverless`) or a pooled TCP connection.
+- Create the client at module scope and reuse it; do not open a new client per request in a
+  long-lived process.
+
+### Connect shapes
+
+```ts
+// node-postgres
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+export const db = drizzle(new Pool({ connectionString: process.env.DATABASE_URL }), { schema });
+
+// neon-http (edge)
+import { drizzle } from 'drizzle-orm/neon-http';
+import { neon } from '@neondatabase/serverless';
+export const db = drizzle(neon(process.env.DATABASE_URL!), { schema });
+
+// libsql / Turso
+import { drizzle } from 'drizzle-orm/libsql';
+import { createClient } from '@libsql/client';
+export const db = drizzle(createClient({ url: process.env.TURSO_URL!, authToken: process.env.TURSO_TOKEN }), { schema });
+```
+
+## Relations v1 vs v2
+
+### 0.45 / v1-compat — `relations()`
+
+Define relations next to the tables, pass the whole module as `{ schema }`.
+
+```ts
+import { relations } from 'drizzle-orm';
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}));
+export const postsRelations = relations(posts, ({ one }) => ({
+  author: one(users, { fields: [posts.authorId], references: [users.id] }),
+}));
+```
+
+```ts
+import * as schema from './schema';
+export const db = drizzle(client, { schema });
+
+const data = await db.query.users.findMany({ with: { posts: true } });
+```
+
+### v1.0 beta — `defineRelations()`
+
+One call describes every relation; pass the result as `{ relations }`.
+
+```ts
+import { defineRelations } from 'drizzle-orm';
+import * as schema from './schema';
+
+export const relations = defineRelations(schema, (r) => ({
+  users: { posts: r.many.posts() },
+  posts: { author: r.one.users({ from: r.posts.authorId, to: r.users.id }) },
+}));
+```
+
+```ts
+export const db = drizzle(client, { relations });
+
+// db.query is RQBv2
+const data = await db.query.users.findMany({ with: { posts: true } });
+
+// db._query keeps the v1 syntax for back-compat during migration
+const legacy = await db._query.users.findMany({ with: { posts: true } });
+```
+
+### Migration walkthrough (v1 → v2)
+
+1. Upgrade `drizzle-orm` to `1.0.0-beta.x` and `drizzle-kit` to the matching beta.
+2. Keep tables in `schema.ts` unchanged — only the relation declarations move.
+3. Replace each `relations(table, ...)` block with one entry in a single `defineRelations(schema, ...)`.
+4. Swap `drizzle(client, { schema })` → `drizzle(client, { relations })`.
+5. New code calls `db.query`; existing v1 relational calls can stay on `db._query` until ported.
+6. Do not leave both `relations()` and `defineRelations` active for the same tables — pick one.
+
+## Decision: relational query vs manual join
+
+- **Relational query (`db.query` + `with`)** → nested reads: a user with their posts as a tree. The
+  builder returns shaped objects.
+- **Manual `.leftJoin()` / `.innerJoin()`** → flat projections, aggregates, `GROUP BY`, or when you
+  need exact control over the emitted SQL. Returns rows, not trees; you assemble the shape.

package/skills/shared/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/shared/duckdb/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: duckdb
+description: "Use when analytical SQL must run in-process with no server: Parquet/CSV/JSON/Arrow queried in place, OLAP embedded in an app or notebook, a slow pandas groupby on multi-GB data, or S3/lakehouse data read without downloading. NOT a multi-user analytics server (that is clickhouse-analytics), NOT an app's transactional CRUD store (that is postgresdb)."
+tags: [duckdb, olap, analytics, parquet, embedded-database, sql, columnar]
+recommends: [clickhouse-analytics, postgresdb, sql, sqlite-turso, data-cleaning, business-intelligence]
+origin: ai-hub
+---
+
+# 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.
+
+## 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
+
+| Anti-pattern | Do instead |
+| --- | --- |
+| Loading a file into pandas, then querying the frame | Pages the whole file through RAM. `FROM 'file.parquet' SELECT ...` scans only needed columns. |
+| Making DuckDB the app's database | One writer, single process — concurrent CRUD writers corrupt the workflow. App OLTP is `postgresdb`. |
+| Serving a dashboard API for 200 users from DuckDB | It's embedded, not a server; concurrent users serialize on the writer. That's `clickhouse-analytics`. |
+| Running 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. |
+| Downloading the S3 files, then reading them | `INSTALL httpfs` + `CREATE SECRET` reads `s3://...` in place with row-group pushdown. No download. |
+| `SELECT *` over a 200-column Parquet | Columnar engine — list the columns you need so it skips the rest. `SELECT *` reads everything. |
+| `GROUP BY a, b, c` — restating every column | Drift bait. `GROUP BY ALL` tracks the SELECT automatically. |
+| Treating "embedded" as "no need to think about RAM" | Set `memory_limit` / `threads`; without a cap a runaway aggregate can thrash before it spills. |
+| Using DuckDB as the embeddings/vector store | VSS exists but vector search is `vector-db`'s workflow, not DuckDB's home turf. |
+
+## 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 index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md`
+keeps only a short pointer to it). Read it first on
+every use and keep choices consistent. No `02-DOCS/`? Skip silently. Conventions are recorded, never gated.

package/skills/shared/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/shared/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/shared/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.