rsc-universal 0.1.1

package/skills/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/sqlite-turso/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: sqlite-turso
+description: "Use when deciding whether plain SQLite is enough or wiring SQLite/Turso/libSQL for local-first, edge, or 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. Triggers: 'is SQLite enough', 'database is locked'/SQLITE_BUSY, 'embedded replica', 'edge database', 'createClient @libsql/client', 'database per user', 'sync local file to the cloud', 'base de datos local-first', 'base de dades a l'edge', 'rèplica incrustada'. NOT Drizzle schema/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: risco
+---
+
+# 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/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/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"

package/skills/sqlite-turso/references/embedded-replicas.md

@@ -0,0 +1,96 @@
+# Embedded replicas — deep reference
+
+Offloaded from SKILL.md because it is branch-specific and longer than the body should carry. Read
+this when you are actually building or operating an embedded-replica deployment.
+
+## What a replica actually is
+
+An embedded replica is a real local SQLite file (`url: "file:local.db"`) plus a `syncUrl` pointing at
+a remote primary. The client maintains the local copy and pulls a stream of **frames** (the unit of
+replication — roughly a batch of committed changes) from the primary. Reads execute against the local
+file with in-process latency. Writes are forwarded to the primary; they do not mutate the local file
+directly, they come back via the next sync.
+
+This is why the local file is mandatory: there is no replica without somewhere local to materialize
+the data. A `syncUrl` next to a `libsql://` url is a contradiction — there is no local store to sync
+into, so the client behaves as a plain remote client and never replicates.
+
+## Sync mechanics and frame numbers
+
+`await client.sync()` returns `{ frame_no, frames_synced }`:
+
+- `frame_no` — the replication frame the local replica is now at (a monotonically advancing
+  position in the primary's change log). Useful for logging/observability and reasoning about how far
+  behind a replica was.
+- `frames_synced` — how many frames this particular `sync()` call pulled. `0` means the replica was
+  already current.
+
+Two ways to drive sync:
+
+- **`syncInterval` (seconds)** in `createClient` — background periodic pull. Good for read-mostly
+  apps that tolerate eventual consistency up to one interval. Pick the interval from how stale a read
+  may be, not from a default.
+- **Manual `client.sync()`** — pull on demand: at request start, after a known remote write, on app
+  resume from background. Combine both: a slow `syncInterval` safety net plus targeted manual syncs
+  where freshness matters.
+
+Calling `sync()` on a client without a `syncUrl` + local `file:` (a remote-only or pure HTTP/WS
+client) throws `LibsqlError` with code `SYNC_NOT_SUPPORTED`. Guard the call by construction — only
+sync clients you built as replicas.
+
+## `readYourWrites` semantics
+
+Default is `true`. With it on, a write you issue through the client is immediately visible to your
+own subsequent reads on that client, even before the next background sync — the client tracks your
+write position and waits for the local replica to catch up to it on read. This is what most apps
+want: you click "save", you re-read, you see your change.
+
+Set `readYourWrites: false` only when you deliberately want a sync's effect to be observable on its
+own timeline — e.g. tests that assert "this row is not visible until I explicitly `sync()`", or
+benchmarks measuring pure replica staleness. If you turn it off in a normal app you will get
+confusing "I just wrote that, why is it gone?" reports.
+
+## Offline and bidirectional writes
+
+Classic libSQL embedded replicas are read-local / write-through-primary: you need connectivity to
+the primary to commit a write. True **offline writes** with bidirectional sync (write locally while
+disconnected, reconcile later) is a capability of **Turso Database (the Rust rewrite)**, not the
+production libSQL path. If a requirement says "must accept writes fully offline and merge later",
+that is the Rust engine's roadmap territory — flag it as not-yet-default-production rather than
+promising it on libSQL today.
+
+## Database-per-user / per-tenant patterns
+
+Turso's unlimited-databases free tier makes a separate database per tenant economical, which gives
+hard data isolation without row-level-security gymnastics.
+
+- **One primary per tenant**, each with its own `libsql://` URL and token. Mint tokens per database
+  with the `turso` CLI.
+- **Connection management**: do not create one `createClient` per request — cache clients keyed by
+  tenant id (a `Map<tenantId, Client>`), and reuse. Each embedded replica holds an open local file;
+  thousands of unmanaged replicas will exhaust file handles and disk.
+- **Replica per tenant** only where the access pattern is local-heavy for that tenant (e.g. a desktop
+  or edge node dedicated to one tenant). For a multi-tenant server hitting many tenants, prefer
+  remote clients (shape #2) and let the edge do the work, or you will be syncing a fleet of files.
+- **Provisioning**: tenant signup creates a database (`turso db create`) and a scoped token; store
+  the URL/token in your secrets store keyed by tenant, never in source.
+
+## Staleness, failure, and consistency
+
+- A replica serves the **last successfully synced state**. If sync fails (network, auth), reads keep
+  working against the stale local copy — this is a feature for availability, a trap for correctness.
+  Surface sync errors; do not swallow them.
+- `frames_synced: 0` over many calls when you expect changes means the primary genuinely has nothing
+  new, or your client is pointed at the wrong primary — check `syncUrl` and token scope.
+- Writes are linearized at the primary, so cross-tenant/global invariants belong at the primary, not
+  asserted against a possibly-stale replica.
+- For "must always read the absolute latest", call `sync()` immediately before the read, or use a
+  remote-only client (shape #2) for that path and accept the round-trip.
+
+## Where this hands off
+
+- Type-safe schema and queries on top of any of these clients → `drizzle-orm`.
+- Versioned, ordered, reversible schema changes (up/down files, a runner) → `db-migrations`. This
+  reference only covers ad-hoc DDL through `execute`/`batch`.
+- Backup/restore and point-in-time strategy as the goal → `backups`.
+- Generic SQL authoring independent of engine (window functions, query tuning) → `sql`.

package/skills/sqlite-turso/scripts/verify.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — sqlite-turso skill gate. Read-only, no network, deterministic.
+#
+# Statically checks @libsql/client integration file(s) for the foot-guns this skill exists to
+# prevent. Pass a file or a directory; with no arg it scans the current directory.
+#
+#   bash verify.sh                 # scan ./ for *.ts / *.js / *.mjs / *.mts
+#   bash verify.sh src/db.ts       # check one file
+#   bash verify.sh src/            # scan a directory
+#
+# What it checks PER FILE that imports @libsql/client:
+#   1. uses createClient (else: not really wiring the client) ......... FAIL
+#   2. if `syncUrl` appears, a local `file:` url must also appear ...... FAIL
+#      (an embedded replica must be backed by a local file)
+#   3. no hardcoded auth token literal (require process.env/Deno.env) .. FAIL
+#   4. file-backed client (`file:`) should set PRAGMA ... WAL .......... advisory [warn]
+#
+# Exit code: non-zero ONLY when a FAIL is recorded. Files with no @libsql/client import are
+# skipped. An empty/clean target prints nothing actionable and exits 0 (no false failure).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+warn() { 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; }
+
+TARGET="${1:-.}"
+
+# Collect candidate files (bash 3.2: no mapfile; NUL-delimited into an initialised array).
+FILES=()
+if [ -f "$TARGET" ]; then
+  FILES+=("$TARGET")
+elif [ -d "$TARGET" ]; then
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(
+    find "$TARGET" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/dist/*' -o -path '*/build/*' \) -prune -o \
+      -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.mjs' -o -name '*.mts' \) -print0 2>/dev/null
+  )
+else
+  warn "target not found: $TARGET (nothing to check)"
+  exit 0
+fi
+
+CHECKED=0
+for f in "${FILES[@]+"${FILES[@]}"}"; do
+  # Only inspect files that actually pull in the libSQL client.
+  grep -Eq "@libsql/client" "$f" 2>/dev/null || continue
+  CHECKED=$((CHECKED + 1))
+
+  # 1. must call createClient
+  if grep -Eq "createClient[[:space:]]*\(" "$f"; then
+    ok "$f: imports @libsql/client and calls createClient"
+  else
+    err "$f: imports @libsql/client but never calls createClient"
+  fi
+
+  # 2. embedded replica must be file-backed
+  if grep -Eq "syncUrl" "$f"; then
+    if grep -Eq "[\"'\`]file:" "$f"; then
+      ok "$f: syncUrl is backed by a local file: url (embedded replica)"
+    else
+      err "$f: syncUrl present but no local 'file:' url — that is a confused remote client, not a replica"
+    fi
+  fi
+
+  # 3. no hardcoded auth token literal. authToken must come from an env source.
+  if grep -Eq "authToken" "$f"; then
+    if grep -Eq "authToken[[:space:]]*:[[:space:]]*[\"'\`]" "$f"; then
+      err "$f: authToken assigned a string literal — read it from process.env / Deno.env instead"
+    elif grep -Eq "authToken[[:space:]]*:[[:space:]]*(process\.env|Deno\.env|import\.meta\.env|Bun\.env)" "$f"; then
+      ok "$f: authToken read from an environment source"
+    else
+      warn "$f: authToken present — confirm it comes from the environment, not a literal"
+    fi
+  fi
+
+  # 4. advisory: a file-backed client should set WAL
+  if grep -Eq "[\"'\`]file:" "$f"; then
+    if grep -Eiq "journal_mode[[:space:]]*=[[:space:]]*WAL" "$f"; then
+      ok "$f: file-backed client sets journal_mode=WAL"
+    else
+      warn "$f: file-backed client — consider PRAGMA journal_mode=WAL (advisory)"
+    fi
+  fi
+done
+
+if [ "$CHECKED" -eq 0 ]; then
+  ok "no @libsql/client integration files found — nothing to verify"
+fi
+
+exit "$EXIT"