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

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

package/skills/shared/sql/scripts/verify.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — sql skill gate. Run from your PROJECT root.
+#
+# What it does (read-only, idempotent, NEVER connects to a database):
+#   1. Discovers *.sql files (skips vendor dirs).
+#   2. Heuristic foot-gun scan — ALL advisory [warn], never fail the build:
+#        - NOT IN (SELECT ...)            -> suggest NOT EXISTS (NULL-eating 3VL footgun)
+#        - comma-join in FROM + WHERE-side join predicate -> suggest explicit JOIN ... ON
+#        - window OVER (... ORDER BY ...) with no ROWS/RANGE/GROUPS -> implicit-frame trap
+#        - SELECT * co-occurring with GROUP BY in the same file
+#   3. Balanced-delimiter sanity (dollar-quote, literal and comment aware).
+#   4. Optional: sqlfluff lint --dialect ansi IF sqlfluff is installed.
+#
+# Exit code: non-zero ONLY on unbalanced parens/quotes (after stripping literals/comments)
+# or a real sqlfluff lint error. Every heuristic above is advisory. An empty or clean
+# target exits 0. Stock macOS bash 3.2 (no mapfile, no associative arrays).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { 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)"
+
+# Discover .sql files. bash 3.2 has no mapfile; read NUL-delimited names into an
+# explicitly-initialised array so expansion is safe under `set -u`.
+SQL_FILES=()
+while IFS= read -r -d '' f; do
+  SQL_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f -name '*.sql' -print0 2>/dev/null
+)
+
+if [ "${#SQL_FILES[@]}" -eq 0 ]; then
+  skip "no .sql files found under $ROOT — nothing to lint"
+  ok "verify.sh passed (empty target)"
+  exit 0
+fi
+
+# Strip line/block comments, single-quoted literals and dollar-quoted bodies, so delimiter
+# counting and pattern matching don't trip on text that lives inside strings/comments.
+strip_for_counting() {
+  awk '
+    BEGIN { inblock = 0; dq = "" }
+    {
+      line = $0; n = length(line); out = ""; i = 1
+      while (i <= n) {
+        rest = substr(line, i)
+        if (inblock) {
+          if (substr(line, i, 2) == "*/") { inblock = 0; i += 2; continue }
+          i += 1; continue
+        }
+        if (dq != "") {
+          if (substr(rest, 1, length(dq)) == dq) { i += length(dq); dq = ""; continue }
+          i += 1; continue
+        }
+        ch  = substr(line, i, 1)
+        ch2 = substr(line, i, 2)
+        if (ch2 == "--") { i = n + 1; continue }
+        if (ch2 == "/*") { inblock = 1; i += 2; continue }
+        if (ch == "$") {
+          if (match(rest, /^\$[A-Za-z_]*\$/)) { dq = substr(rest, RSTART, RLENGTH); i += RLENGTH; continue }
+        }
+        if (ch == "'\''") {
+          i += 1
+          while (i <= n) {
+            c = substr(line, i, 1)
+            if (c == "'\''") {
+              if (substr(line, i + 1, 1) == "'\''") { i += 2; continue }
+              i += 1; break
+            }
+            i += 1
+          }
+          continue
+        }
+        out = out ch
+        i += 1
+      }
+      print out
+    }
+  ' "$1"
+}
+
+for f in "${SQL_FILES[@]}"; do
+  body="$(strip_for_counting "$f")"
+
+  # --- heuristics (advisory) ---
+
+  # NOT IN (SELECT ...) — the NULL three-valued-logic footgun.
+  if printf '%s' "$body" | grep -Eiqz 'not[[:space:]]+in[[:space:]]*\([[:space:]]*select'; then
+    note "$f: NOT IN (SELECT ...) — a NULL in the subquery returns zero rows; prefer NOT EXISTS"
+  fi
+
+  # Comma-join in FROM combined with a WHERE that joins two aliases (t1.x = t2.y).
+  if grep -Eiq 'from[[:space:]]+[a-z_][a-z0-9_]*([[:space:]]+(as[[:space:]]+)?[a-z_][a-z0-9_]*)?[[:space:]]*,[[:space:]]*[a-z_]' "$f" \
+     && grep -Eiq 'where[^;]*[a-z_][a-z0-9_]*\.[a-z0-9_]+[[:space:]]*=[[:space:]]*[a-z_][a-z0-9_]*\.[a-z0-9_]+' "$f"; then
+    note "$f: comma-join in FROM with a join predicate in WHERE — use explicit JOIN ... ON"
+  fi
+
+  # Window with ORDER BY inside OVER() but no explicit frame keyword -> implicit-frame trap.
+  if grep -Eiq 'over[[:space:]]*\([^)]*order[[:space:]]+by' "$f" \
+     && ! grep -Eiq '(rows|range|groups)[[:space:]]+(between|unbounded|current|[0-9])' "$f"; then
+    note "$f: window OVER(... ORDER BY ...) with no ROWS/RANGE/GROUPS frame — implicit RANGE groups tied rows; state ROWS for a true running total"
+  fi
+
+  # SELECT * alongside a GROUP BY in the same file.
+  if grep -Eiq 'select[[:space:]]+\*' "$f" && grep -Eiq 'group[[:space:]]+by' "$f"; then
+    note "$f: SELECT * with a GROUP BY — name the grouped columns explicitly"
+  fi
+
+  # --- balanced-delimiter sanity (hard fail) ---
+  sq=$(printf '%s' "$body" | tr -cd "'" | wc -c | tr -d ' ')
+  op=$(printf '%s' "$body" | tr -cd '(' | wc -c | tr -d ' ')
+  cp=$(printf '%s' "$body" | tr -cd ')' | wc -c | tr -d ' ')
+  if [ $((sq % 2)) -ne 0 ]; then err "$f: unbalanced single quotes (after stripping literals/comments)"; fi
+  if [ "$op" -ne "$cp" ]; then err "$f: unbalanced parentheses ($op '(' vs $cp ')')"; fi
+done
+ok "scanned ${#SQL_FILES[@]} .sql file(s)"
+
+# --- optional sqlfluff (ANSI dialect) ---
+if command -v sqlfluff >/dev/null 2>&1; then
+  if sqlfluff lint --dialect ansi "${SQL_FILES[@]}"; then
+    ok "sqlfluff lint clean (--dialect ansi)"
+  else
+    err "sqlfluff reported lint errors"
+  fi
+else
+  skip "sqlfluff not installed — skipping standard-SQL lint"
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"

package/skills/shared/sqlite-turso/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: sqlite-turso
+description: "Use when deciding whether plain SQLite is enough, or wiring SQLite, Turso or libSQL for local-first, edge and embedded-replica apps — a local file DB, a remote Turso URL, or a local replica synced to a remote primary — plus WAL mode and SQLite's single-writer model and its lock errors. NOT Drizzle schema or queries on libSQL (that is `drizzle-orm`), NOT versioned up/down migrations (that is `db-migrations`), NOT serverless Postgres with branching (that is `neon`)."
+tags: [sqlite, turso, libsql, edge, embedded-replica, local-first, wal]
+recommends: [drizzle-orm, db-migrations, postgresdb, neon, backups, sql]
+origin: ai-hub
+---
+
+# SQLite & Turso/libSQL — decide, connect, operate
+
+SQLite is an in-process, single-file, **single-writer** relational engine. Turso/libSQL is the
+fork that adds a remote edge database and — the part people actually want — **embedded replicas**:
+a local SQLite file that syncs to a remote primary, so reads are microsecond-local and writes still
+land durably in the cloud.
+
+This skill is **decide + connect + operate**. It owns the engine truths (WAL, single writer,
+pragmas), the three deployment shapes, and wiring the current `@libsql/client`. It does NOT own
+schema modeling or type-safe queries (that is `drizzle-orm`), versioned migration files (that is
+`db-migrations`), or backup strategy as a primary task (that is `backups`).
+
+## Is SQLite/Turso the right tool?
+
+Decide first. Picking SQLite for a high-write multi-writer workload is the mistake that wastes a week.
+
+| Workload | Verdict | Why / route |
+|---|---|---|
+| Read-heavy, single-tenant, low-to-moderate writes | **SQLite/Turso** | One writer is plenty; reads are local and fast. |
+| Local-first / offline / edge app needing cloud durability | **Turso embedded replica** | Local file for reads, syncs to a remote primary. |
+| Database-per-user / per-tenant at scale | **Turso** | Unlimited databases on the free tier; cheap isolation. |
+| Many concurrent writers, complex roles, extensions | No → `postgresdb` (or `mysql`) | SQLite serializes writers; one writer at a time. |
+| Serverless Postgres with branching | No → `neon` | Turso is serverless *SQLite*, not Postgres. |
+| MySQL-compatible serverless | No → `planetscale` | Different engine and protocol. |
+| Auth + realtime + storage + Postgres bundled | No → `supabase` | You want a BaaS, not a raw SQL engine. |
+| Columnar OLAP / analytical aggregates | No → `duckdb` | SQLite/Turso is OLTP, row-oriented. |
+| Ephemeral cache / KV | No → `redis` | Not a durable relational store. |
+
+## Three deployment shapes
+
+Every Turso/libSQL decision reduces to which of these three you are wiring. The URL scheme picks the
+transport automatically.
+
+| Shape | `createClient` config | Latency | When |
+|---|---|---|---|
+| **Local file** | `url: "file:local.db"` | In-process | Dev, CLI tools, single-node app, tests. |
+| **Remote edge DB** | `url: "libsql://<db>.turso.io"` + `authToken` | Network round-trip | Serverless/stateless functions; no local disk to sync. |
+| **Embedded replica** | `url: "file:local.db"` + `syncUrl` + `authToken` | Microsecond reads | Local-first/edge with cloud durability — the flagship. |
+
+`libsql://` resolves to HTTPS/WSS. `file:` is native. `https:`/`http:` is Hrana HTTP, `wss:`/`ws:`
+is Hrana WebSocket. You rarely set the scheme by hand — you set the URL and the client chooses.
+
+## Connect with `@libsql/client`
+
+Current client is **`@libsql/client` v0.17.x**. Never hardcode the auth token — read it from the
+environment. Convention: `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN`.
+
+```ts
+// 1. Local file — dev, tests, single node
+import { createClient } from "@libsql/client";
+
+const db = createClient({ url: "file:local.db" });
+```
+
+```ts
+// 2. Remote edge DB — serverless, no local disk
+import { createClient } from "@libsql/client";
+
+const db = createClient({
+  url: process.env.TURSO_DATABASE_URL!,   // libsql://<db>.turso.io
+  authToken: process.env.TURSO_AUTH_TOKEN!,
+});
+```
+
+```ts
+// 3. Embedded replica — local reads, syncs to the primary
+import { createClient } from "@libsql/client";
+
+const db = createClient({
+  url: "file:local.db",                   // MUST be a local file
+  syncUrl: process.env.TURSO_DATABASE_URL!,
+  authToken: process.env.TURSO_AUTH_TOKEN!,
+  syncInterval: 60,                        // seconds; or call db.sync() manually
+});
+```
+
+Rule: an embedded replica's `url` is **always** a local `file:` — `syncUrl` is the remote. If you
+set `syncUrl` next to a `libsql://` url you have not built a replica, you have a confused remote
+client. (verify.sh enforces exactly this.)
+
+In serverless/edge runtimes the import is the same; just confirm the runtime exposes a writable temp
+path for the `file:` replica, or fall back to shape #2 (remote-only).
+
+## WAL and the pragmas you must set
+
+For any **local file** or **embedded replica** connection, set these per-connection on open. They do
+not apply to a remote-only client (the primary already runs WAL server-side).
+
+```sql
+PRAGMA journal_mode = WAL;     -- concurrent readers + one writer; default rollback-journal blocks readers during writes
+PRAGMA busy_timeout = 5000;    -- wait up to 5s for the write lock instead of erroring SQLITE_BUSY immediately
+PRAGMA foreign_keys = ON;      -- FK enforcement is OFF by default and is PER-CONNECTION — set it every time
+PRAGMA synchronous = NORMAL;   -- safe with WAL; far fewer fsyncs than the default FULL
+```
+
+`journal_mode` is persistent once set on the file; `busy_timeout`, `foreign_keys`, and `synchronous`
+are per-connection — re-issue them on every new connection (and in pooled environments, on checkout).
+
+## Writes, batches, transactions
+
+Always parameterize. String-concatenated SQL is an injection hole and defeats statement caching.
+
+```ts
+// Bad — string interpolation
+await db.execute(`INSERT INTO users (email) VALUES ('${email}')`);
+
+// Good — positional ? args (named $name and tuple [sql, args] forms also work)
+await db.execute({ sql: "INSERT INTO users (email) VALUES (?)", args: [email] });
+```
+
+`batch` runs many statements **atomically in one transaction** — all commit or all roll back.
+
+```ts
+// mode: "write" (default), "read", or "deferred"
+const rs = await db.batch(
+  [
+    { sql: "INSERT INTO orders (user_id, total) VALUES (?, ?)", args: [userId, total] },
+    { sql: "UPDATE users SET order_count = order_count + 1 WHERE id = ?", args: [userId] },
+  ],
+  "write",
+);
+```
+
+Single-writer rule: SQLite allows exactly one writer at a time. Under concurrent writes you get
+`SQLITE_BUSY` / "database is locked". The fix is WAL + `busy_timeout` above, plus keeping write
+transactions short. If you genuinely need many simultaneous writers, that is the signal to route to
+`postgresdb` — do not paper over it with retries forever.
+
+## Embedded replica sync
+
+A replica keeps a local copy of the data and pulls changes from the primary. Reads hit the local
+file; writes are sent to the primary and propagate back on the next sync.
+
+- **Periodic**: pass `syncInterval` (seconds) to `createClient` and the client syncs in the background.
+- **On-demand**: call `await db.sync()` yourself — it returns `{ frame_no, frames_synced }` (the
+  replication frame you are now at, and how many frames this call pulled).
+- `readYourWrites` (default `true`) guarantees a connection sees its own writes immediately. Set it
+  to `false` only when you specifically want a sync's effect to become observable on its own timeline.
+- **Gotcha**: calling `db.sync()` on a remote-only or pure HTTP/WS client throws `LibsqlError` with
+  code `SYNC_NOT_SUPPORTED`. Only embedded-replica clients (those with a local `file:` + `syncUrl`)
+  can sync.
+
+Deeper material — sync internals, frame numbers, `readYourWrites` semantics, offline/bidirectional
+writes, per-tenant database-per-user patterns, stale-read handling — lives in
+[references/embedded-replicas.md](references/embedded-replicas.md).
+
+## libSQL today vs Turso Database (Rust) tomorrow
+
+Two things wear the "Turso" name; do not confuse them.
+
+- **libSQL** is the SQLite fork and the battle-tested foundation. For production today, **use
+  libSQL** via `@libsql/client`. This is the official guidance — mission-critical workloads run here.
+- **Turso Database** is a from-scratch rewrite of SQLite in Rust (formerly "Limbo"), adding MVCC
+  concurrent writes and bidirectional offline sync. It is the future direction and where new features
+  land, but it is not the default production target yet.
+
+Separately: **"edge replicas" are being discontinued for new users** (data showed ~70% never used
+them), along with multi-DB schemas and `ATTACH`. Existing paid customers keep them. This is **not**
+the same as embedded replicas — embedded replicas remain the flagship. Do not design a new account
+around edge replicas.
+
+Turso/libSQL also has native vector search (DiskANN). For a dedicated vector store, route to
+`vector-db` regardless.
+
+## Operate — the `turso` CLI
+
+```bash
+turso db create my-app                          # create a database
+turso db show my-app --url                       # get the libsql:// URL for TURSO_DATABASE_URL
+turso db tokens create my-app                    # mint an auth token for TURSO_AUTH_TOKEN
+turso db shell my-app                            # interactive SQL shell against the primary
+```
+
+Pricing note: the free tier offers **unlimited databases** (post "Database Freedom Day", mid-2025),
+usage-based with generous read/storage allowances — exact GB and row-read numbers shift, so verify on
+turso.tech/pricing before quoting a figure. This is what makes database-per-user economical.
+
+Route out: backups/restore strategy → `backups`; versioned migrations → `db-migrations`; type-safe
+schema and queries → `drizzle-orm`; generic SQL authoring (window functions, tuning) → `sql`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Treating SQLite like multi-writer Postgres | One writer at a time → `SQLITE_BUSY` storms under load | Keep writes serial + short, or route to `postgresdb` |
+| Forgetting `PRAGMA journal_mode=WAL` | Default journal blocks readers during every write | Set WAL on local file / replica connections |
+| Embedded replica with a `libsql://` url | Not a replica — a confused remote client; reads aren't local | `url:` is a local `file:`, remote goes in `syncUrl` |
+| Hardcoding the auth token in source | Leaks a credential into VCS | Read `process.env.TURSO_AUTH_TOKEN` |
+| Calling `db.sync()` on a remote/HTTP client | Throws `LibsqlError` `SYNC_NOT_SUPPORTED` | Only sync embedded-replica clients |
+| Assuming FK constraints are enforced | `foreign_keys` is OFF by default, per-connection | `PRAGMA foreign_keys=ON` on every connection |
+| Designing a new account around edge replicas | Discontinued for new users | Use embedded replicas (the flagship) |
+| String-concatenated SQL | Injection + no statement caching | Parameterize with `?` / `$name` / tuple args |
+| Reaching for Turso for OLAP dashboards | Row-store, single writer — wrong shape | Use `duckdb` for columnar analytics |
+| Layering migrations/ORM logic into this skill | Out of scope; duplicates sibling rigor | `db-migrations` / `drizzle-orm` |
+
+## Verify
+
+When you emit a connection/config file, gate it:
+
+```bash
+bash scripts/verify.sh path/to/db.ts        # or a directory; defaults to cwd
+```
+
+It statically checks (no network): `@libsql/client` import + `createClient` use; that a `syncUrl`
+always sits next to a local `file:` url; no hardcoded token literal; and (advisory) WAL pragma
+presence on file-backed clients. Read-only; exits 0 on a clean/empty target.

package/skills/shared/sqlite-turso/evals/README.md

@@ -0,0 +1,24 @@
+# Eval harness — `sqlite-turso`
+
+Two things get checked: **triggering** (does the skill fire on real SQLite/Turso situations and stay
+quiet on near-misses that belong to a sibling?) and **capability** (does loading it measurably
+improve the answer?). Cases live in `cases.yaml`. These run through an agent harness, not a pure
+shell script — a human or driver agent feeds each prompt and grades the output.
+
+**Triggering.** For each prompt, start a fresh session with only `sqlite-turso` discoverable, paste
+the prompt verbatim, run 3–5 trials (the decision is stochastic). `should_trigger` passes if the
+skill fires in the majority of trials; `should_not_trigger` passes if it does not fire — and when a
+`route_to` is named (drizzle-orm, db-migrations, postgresdb, neon, vector-db), sanity-check the agent
+would plausibly route there. Pass bar: ~90% accuracy across all trigger cases.
+
+**Capability.** Run the scenario twice — once WITHOUT the skill, once WITH — and grade each
+transcript against the `must_include` checklist, one point per bullet genuinely covered (not just
+name-dropped). Pass bar: WITH the skill covers ≥80% of bullets and clearly beats WITHOUT.
+
+**verify.sh spot-check (separate, deterministic).** `scripts/verify.sh` is a static, read-only,
+no-network gate for generated connection files. Sanity-check it by hand: a file with `createClient` +
+`syncUrl` + a local `file:` url + an env-var token should pass; flip the token to a string literal,
+drop the `file:` url, or call `sync()` patterns on a remote-only client and confirm it FAILs. Running
+it against an empty directory must print nothing actionable and exit 0.
+
+Record trial counts and per-bullet verdicts so a reviewer can audit; don't report a bare pass/fail.

package/skills/shared/sqlite-turso/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: sqlite-turso
+
+should_trigger:
+  - prompt: "My app is read-heavy and single-tenant. Is SQLite actually enough or do I need a real database like Postgres?"
+    why: "The core decision this skill leads with — workload fit and the route-out to postgresdb when writers multiply."
+  - prompt: "Under load I keep getting 'database is locked' and occasional SQLITE_BUSY errors. How do I fix it?"
+    why: "Non-obvious: the user names a symptom, not the engine. Owned by the WAL + busy_timeout + single-writer guidance."
+  - prompt: "I want a local SQLite file that automatically syncs to a Turso database in the cloud so reads stay fast but data is durable."
+    why: "This is the embedded-replica flagship — file: url + syncUrl + token + sync()."
+  - prompt: "How do I wire createClient from @libsql/client to my Turso edge database with an auth token?"
+    why: "Direct connection scope: the current client, env-var token convention, URL-scheme transport selection."
+  - prompt: "I'm building a SaaS and want a separate database per customer on the edge. Is that practical?"
+    why: "Non-obvious mapping: database-per-user/per-tenant economics are a Turso strength (unlimited DBs), covered in the body and reference."
+  - prompt: "Munta una base de dades local-first amb rèplica incrustada que sincronitzi amb el núvol."
+    why: "Catalan trigger for the embedded-replica / local-first flagship — language coverage plus core feature."
+  - prompt: "Should I turn on WAL mode for my SQLite file, and what other pragmas should I always set?"
+    why: "Engine-truth scope: journal_mode=WAL, busy_timeout, foreign_keys per-connection, synchronous=NORMAL."
+
+should_not_trigger:
+  - prompt: "Define my libSQL schema with tables and relations and write type-safe queries with Drizzle."
+    route_to: drizzle-orm
+    why: "Schema modeling and the type-safe query builder layer ON TOP of the client — drizzle's job, not this engine/connection skill."
+  - prompt: "Create ordered up/down migration files for my SQLite schema and a runner to apply them."
+    route_to: db-migrations
+    why: "Versioned migration discipline is engine-agnostic and explicitly out of scope; this skill only does ad-hoc DDL."
+  - prompt: "We need thousands of users writing concurrently with complex transactions and roles."
+    route_to: postgresdb
+    why: "Many concurrent writers is exactly where SQLite's single-writer model breaks — route to a client-server RDBMS."
+  - prompt: "Give me serverless Postgres with database branching for preview environments."
+    route_to: neon
+    why: "Postgres-compatible serverless with branching is neon; Turso is serverless SQLite, a different engine."
+  - prompt: "Build a vector similarity search store for my RAG pipeline with reranking."
+    route_to: vector-db
+    why: "Even though Turso has native vector search, a dedicated vector store as the goal routes to the vector specialist."
+
+capability:
+  - scenario: "User asks to add Turso to a Next.js app so local reads are sub-millisecond but data is durably stored in the cloud, and wants the connection set up correctly."
+    must_include:
+      - "Uses an embedded replica: createClient with a local `file:` url AND a `syncUrl` to the remote primary (not a bare remote client for the local-read requirement)"
+      - "Reads the auth token from the environment (process.env.TURSO_AUTH_TOKEN), never a hardcoded literal"
+      - "Provides freshness via syncInterval and/or a manual await db.sync() call, mentioning sync() returns {frame_no, frames_synced}"
+      - "Recommends PRAGMA journal_mode=WAL plus busy_timeout and foreign_keys=ON on the file-backed connection"
+      - "States that production today uses libSQL (@libsql/client v0.17.x); Turso Database (Rust) is the future direction, not the default target"
+      - "Routes type-safe schema/queries to drizzle-orm and versioned migrations to db-migrations rather than doing them here"
+      - "Warns that db.sync() on a remote-only/HTTP client throws SYNC_NOT_SUPPORTED, and that a syncUrl requires a local file: url"