rsc-universal 0.1.1

package/skills/mysql/references/online-ddl-and-migrations.md

@@ -0,0 +1,120 @@
+# Online DDL and migrations (the MySQL mechanics)
+
+This file owns the MySQL-only knobs — `ALGORITHM=`, `LOCK=`, pt-online-schema-change, gh-ost — that
+make a schema change run without an outage. The vendor-neutral *strategy* (expand-contract, batched
+backfill, dual-write) lives in `db-migrations`; this is the InnoDB machinery that strategy rides on.
+
+## ALGORITHM / LOCK matrix per operation
+
+Every `ALTER TABLE` resolves to one of three algorithms. **Always state it explicitly** — if you
+omit `ALGORITHM=`, MySQL silently picks the cheapest one that works, and "cheapest that works" can
+quietly be `COPY`, which locks and rebuilds a multi-GB table.
+
+| Operation | Best algorithm | Notes |
+|---|---|---|
+| Add column at the end | `INSTANT` | metadata-only since 8.0.12; near-free |
+| Add column in the middle | `INSTANT` (8.0.29+) | older versions fall back to INPLACE/COPY |
+| Drop a column | `INSTANT` (8.0.29+) | else INPLACE |
+| Rename a column | `INSTANT` | metadata-only |
+| Set / drop a column DEFAULT | `INSTANT` | metadata-only |
+| Add a secondary index | `INPLACE, LOCK=NONE` | rebuilds the index without blocking writes |
+| Drop an index | `INPLACE` (often INSTANT) | metadata change |
+| Change column NULL → NOT NULL | `INPLACE` | requires the data to already satisfy it |
+| Change column data type / charset | `COPY` | full table rebuild — this is the dangerous one |
+| Add / drop a PRIMARY KEY | `COPY` (usually) | rebuilds the clustered index and every secondary |
+| Change ROW_FORMAT / KEY_BLOCK_SIZE | `INPLACE` (rebuild) | not blocking but rewrites the table |
+
+```sql
+-- Always be explicit. If the operation can't be done with the algorithm you named, the statement
+-- FAILS LOUDLY instead of silently degrading to a locking COPY.
+ALTER TABLE orders ADD COLUMN note VARCHAR(255) NULL, ALGORITHM=INSTANT, LOCK=NONE;
+
+-- Adding a secondary index on a live table: rebuild without blocking writes.
+ALTER TABLE orders ADD INDEX idx_user_created (user_id, created_at),
+  ALGORITHM=INPLACE, LOCK=NONE;
+```
+
+There is a hard limit on `INSTANT` add-column: each `INSTANT` add increments a row-version counter,
+and after a number of them the table needs a rebuild before more `INSTANT` adds are allowed. Check
+`information_schema.INNODB_TABLES.INSTANT_COLS` / row-version columns if `INSTANT` starts refusing.
+
+## When INSTANT/INPLACE can't do it non-blockingly → gh-ost or pt-osc
+
+For a `COPY`-only change on a large *hot* table (type change, PK change, charset migration), don't
+run it in place at peak. Use an external tool that builds a shadow table, copies rows in chunks,
+keeps it in sync, and swaps atomically.
+
+### gh-ost (GitHub) — binlog-based, triggerless
+
+gh-ost reads the binlog to keep the shadow table in sync, so it adds no triggers to your hot table
+and throttles cleanly on replica lag.
+
+```bash
+# Always --dry-run (omit --execute) first; read the plan, then add --execute.
+gh-ost \
+  --host=primary.db --database=shop --table=orders \
+  --alter="MODIFY COLUMN total DECIMAL(19,4) NOT NULL" \
+  --max-load="Threads_running=25" \
+  --critical-load="Threads_running=100" \
+  --max-lag-millis=1500 \
+  --throttle-control-replicas="replica1.db,replica2.db" \
+  --chunk-size=1000 \
+  --cut-over=default \
+  --postpone-cut-over-flag-file=/tmp/ghost.postpone \
+  --execute
+# Touch/remove the postpone file to control exactly when the atomic cutover happens.
+```
+
+gh-ost needs `binlog_format=ROW` and either a connection to a replica or `--allow-on-master` with
+binlog access. It can't follow a table that already has triggers.
+
+### pt-online-schema-change (Percona) — trigger-based
+
+Use pt-osc when gh-ost can't read the binlog (no replica, restricted binlog). It installs AFTER
+INSERT/UPDATE/DELETE triggers on the original table to mirror writes into the shadow copy.
+
+```bash
+pt-online-schema-change \
+  --alter "MODIFY COLUMN total DECIMAL(19,4) NOT NULL" \
+  --max-lag=1.5 --check-slave-lag replica1.db \
+  --chunk-time=0.5 \
+  --dry-run \
+  D=shop,t=orders
+# Replace --dry-run with --execute once the dry run is clean.
+```
+
+Caveat: pt-osc's triggers conflict with any pre-existing triggers on the table, and foreign keys
+referencing the table need `--alter-foreign-keys-method` chosen deliberately (rebuild_constraints
+vs drop_swap) — a wrong choice can briefly break FK integrity at cutover.
+
+### Choosing between them
+
+| Situation | Tool |
+|---|---|
+| You have a replica and ROW binlog, no existing triggers | gh-ost (lighter, no triggers on hot table) |
+| No replica / restricted binlog access | pt-osc (triggers) |
+| Table already has triggers | pt-osc with care, or refactor first |
+| Foreign keys point at the table | pt-osc with an explicit `--alter-foreign-keys-method` |
+
+## Rollback
+
+- An `INSTANT`/`INPLACE` `ALTER` is a single transaction-like operation: if it fails it leaves the
+  table unchanged. There is no half-applied state to clean up.
+- gh-ost / pt-osc: before cutover, the original table is untouched — abort freely (gh-ost: remove
+  the panic flag or kill it; the `_gho`/`_new` shadow + `_del` old table are left for you to drop).
+  *After* cutover, "rollback" means running the reverse `ALTER` as a new migration. Design the
+  reverse step before you cut over.
+
+## How this composes with db-migrations expand-contract
+
+The vendor-neutral pattern from `db-migrations` is: **expand** (add the new column/index, both old
+and new readable), **migrate** (backfill + dual-write), **contract** (drop the old). Each phase maps
+to a specific MySQL mechanic here:
+
+- *Expand* = an `ALGORITHM=INSTANT` add-column / `INPLACE` add-index — cheap, non-blocking.
+- *Backfill* = chunked `UPDATE ... WHERE id BETWEEN ? AND ?` in small batches (never one giant
+  `UPDATE` that holds gap locks across the whole table); or let gh-ost do it for a type change.
+- *Contract* = an `INSTANT` drop-column once nothing reads the old one.
+
+Keep each phase a separate, forward-only migration so the reverse is always a clean step.
+`db-migrations` owns *why* and *in what order*; this skill owns *which `ALGORITHM=` / which tool*.

package/skills/mysql/references/replication-and-ha.md

@@ -0,0 +1,115 @@
+# Replication and HA
+
+MySQL 8.4 / MariaDB 11.8 replication mechanics: binlog formats, GTID, the topologies, lag diagnosis,
+and failover. Backup *strategy* as a discipline lives in `backups`; this owns the binlog/PITR and
+replication-setup mechanics.
+
+## Binlog format — ROW, and why
+
+| Format | What it logs | Verdict |
+|---|---|---|
+| `ROW` | The actual before/after row images | **The only safe default.** Deterministic; replicas apply exactly what happened. |
+| `STATEMENT` | The literal SQL text | Non-deterministic statements (`NOW()`, `UUID()`, `LIMIT` without `ORDER BY`, triggers) replicate *differently* on the replica → silent data drift. |
+| `MIXED` | STATEMENT, switching to ROW when it detects non-determinism | Better than STATEMENT but the detection is imperfect; prefer ROW outright. |
+
+```ini
+# my.cnf — the replication baseline.
+[mysqld]
+server_id              = 1            # unique per host in the topology
+log_bin                = mysql-bin
+binlog_format          = ROW
+gtid_mode              = ON
+enforce_gtid_consistency = ON
+binlog_expire_logs_seconds = 604800   # 7 days of binlog retained for replicas/PITR
+```
+
+## GTID-based replication, end to end
+
+A GTID (Global Transaction ID) tags every committed transaction with `source_uuid:sequence`. The
+replica records which GTIDs it has applied, so with `SOURCE_AUTO_POSITION=1` it requests exactly the
+transactions it's missing — no manual log-file/position bookkeeping, and each transaction applies
+**at most once** (auto-skip on reconnect/failover).
+
+**MySQL 8.4 adds tagged GTIDs**: an optional third, colon-separated component
+(`source_uuid:tag:sequence`) that groups related transactions — useful to mark, filter, or
+selectively skip a logical batch.
+
+```sql
+-- On the replica (8.4 syntax: CHANGE REPLICATION SOURCE TO, not the old CHANGE MASTER TO).
+CHANGE REPLICATION SOURCE TO
+  SOURCE_HOST='primary.db',
+  SOURCE_USER='repl',
+  SOURCE_PASSWORD='***',
+  SOURCE_SSL=1,                 -- caching_sha2_password needs TLS
+  SOURCE_AUTO_POSITION=1;       -- GTID auto-positioning
+START REPLICA;
+SHOW REPLICA STATUS\G
+```
+
+The replication user authenticates with `caching_sha2_password` by default, so the channel must use
+`SOURCE_SSL=1` or the first-time auth fails.
+
+## Topology chooser
+
+| Topology | Durability on primary loss | Use when |
+|---|---|---|
+| **Async** (default) | Can lose the last un-replicated transactions | Read scaling, geo replicas, where small data-loss-on-failover is acceptable |
+| **Semi-synchronous** | Primary waits for ≥1 replica to *receive* (not apply) each commit | You need "committed means at least one replica has it" without full consensus cost |
+| **Group Replication / InnoDB Cluster** | Quorum-committed (Paxos-style); automatic failover | You need automatic failover and a single logical primary with managed membership |
+
+InnoDB Cluster = Group Replication + MySQL Shell (`dba.createCluster()`) for orchestration + **MySQL
+Router** as the connection front-end that routes writes to the primary and reads to replicas. Apps
+connect to the Router's port (6446 read-write / 6447 read-only), never directly to a node, so a
+failover is transparent to the application.
+
+```ini
+# Semi-sync (loadable component in 8.4): primary waits for one replica to ACK receipt.
+[mysqld]
+rpl_semi_sync_source_enabled  = 1
+rpl_semi_sync_source_timeout  = 1000   # ms before falling back to async if no ACK
+rpl_semi_sync_replica_enabled = 1
+```
+
+## Replica-lag diagnosis — read the field, don't eyeball
+
+```sql
+SHOW REPLICA STATUS\G
+-- Read in this order:
+--   Replica_IO_Running  / Replica_SQL_Running  → both must be 'Yes'
+--   Last_IO_Error / Last_SQL_Error             → why it stopped
+--   Seconds_Behind_Source                      → coarse; NULL means BROKEN, not "0 lag"
+```
+
+`Seconds_Behind_Source` is a blunt instrument (it's relative to the SQL thread's current event, and
+goes NULL the moment a thread stops). For real, per-worker lag use performance_schema:
+
+```sql
+SELECT WORKER_ID,
+       LAST_APPLIED_TRANSACTION,
+       APPLYING_TRANSACTION,
+       APPLYING_TRANSACTION_ORIGINAL_COMMIT_TIMESTAMP
+FROM performance_schema.replication_applier_status_by_worker;
+
+-- End-to-end lag = now() - the original commit timestamp of the transaction being applied.
+```
+
+If lag is structural, enable multi-threaded apply (`replica_parallel_workers > 0`,
+`replica_parallel_type = LOGICAL_CLOCK`) so the replica applies independent transactions in parallel.
+
+## Failover
+
+- **Async/semi-sync, manual**: pick the most-caught-up replica (highest applied GTID set), point the
+  other replicas and the app at it, `RESET REPLICA ALL` on the new primary. GTID auto-positioning
+  means surviving replicas resync from exactly where they were.
+- **InnoDB Cluster**: failover is automatic — the group elects a new primary; MySQL Router redirects
+  writes. Your job is to monitor `cluster.status()` and re-add the recovered node with
+  `cluster.rejoinInstance()`.
+- Always confirm the old primary is truly down (fenced) before promoting — a split brain where two
+  nodes both accept writes is the worst outcome, far worse than a few seconds of downtime.
+
+## Read-replica routing
+
+Route reads to replicas but **never read your own just-written row from a lagging async replica** —
+that's the read-after-write consistency trap. Either route a user's reads to the primary for a short
+window after their write, or use `WAIT_FOR_EXECUTED_GTID_SET()` on the replica to block until it has
+caught up to the GTID your write produced. InnoDB Cluster's Router can be configured for this.

package/skills/mysql/scripts/verify.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — mysql skill gate. Run from your PROJECT root.
+#
+# What it does (read-only, idempotent, never writes, NEVER connects to a database):
+#   Discovers *.sql and *.cnf / my.cnf files and heuristically lints them for the MySQL/InnoDB
+#   foot-guns this skill warns about:
+#     - CHARACTER SET utf8 / CHARSET=utf8 that is not utf8mb4 (silent emoji truncation)   [warn]
+#     - ENGINE=MyISAM on CREATE TABLE (no transactions/FKs)                               [warn]
+#     - likely random-UUID / CHAR(36) PRIMARY KEY (InnoDB clustered-index bloat)          [warn]
+#     - default_authentication_plugin = mysql_native_password in config                   [warn]
+#     - an indexed column wrapped in a function in WHERE (DATE(col)/LOWER(col), non-sargable) [warn]
+#     - binlog_format = STATEMENT in a committed config                                   [FAIL]
+#     - unbalanced parens/single-quotes in a SQL statement                                [FAIL]
+#   Optionally runs `sqlfluff --dialect mysql` if sqlfluff is installed.
+#
+# Exit code: non-zero ONLY on (a) unbalanced delimiters, (b) a committed binlog_format=STATEMENT,
+# or (c) a real sqlfluff lint error. Every schema heuristic is advisory [warn], never a failure.
+# An empty/clean target exits 0 with no false failure.
+#
+# Portability: stock macOS bash 3.2 — no mapfile, no associative arrays. Arrays are initialised so
+# they are safe to expand under `set -u`. Pure grep/awk; no network, no mysql client.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+skip() { printf '%s[skip]%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 files (exclude vendor dirs) -----------------------------------------------------
+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
+)
+
+CNF_FILES=()
+while IFS= read -r -d '' f; do CNF_FILES+=("$f"); done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f \( -name '*.cnf' -o -name 'my.cnf' \) -print0 2>/dev/null
+)
+
+if [ "${#SQL_FILES[@]}" -eq 0 ] && [ "${#CNF_FILES[@]}" -eq 0 ]; then
+  ok "no *.sql or *.cnf files found — nothing to lint"
+  exit 0
+fi
+
+# --- strip comments + string literals for the balance heuristic -------------------------------
+# Pure awk so it behaves identically on BSD (macOS) and GNU awk. Removes -- line comments,
+# /* */ block comments, and '...' single-quoted literals (handling '' escapes) so the
+# paren/quote balance check does not trip on legitimate content.
+strip_sql() {
+  awk '
+    BEGIN { inblock = 0; instr = 0 }
+    {
+      line = $0; out = ""; i = 1; n = length(line)
+      while (i <= n) {
+        ch  = substr(line, i, 1)
+        ch2 = substr(line, i, 2)
+        if (inblock) { p = index(substr(line,i), "*/"); if (p==0){i=n+1;continue} i+=p+1; inblock=0; continue }
+        if (instr)   {
+          if (ch == "\x27") {
+            if (substr(line,i,2) == "\x27\x27") { i+=2; continue }   # escaped quote
+            instr = 0; i++; continue
+          }
+          i++; continue
+        }
+        if (ch2 == "--") { i = n + 1; continue }
+        if (ch2 == "/*") { inblock = 1; i += 2; continue }
+        if (ch == "\x27") { instr = 1; i++; continue }
+        out = out ch; i++
+      }
+      print out
+    }
+  ' "$1"
+}
+
+# --- per-SQL-file checks ----------------------------------------------------------------------
+for f in ${SQL_FILES[@]+"${SQL_FILES[@]}"}; do
+  # legacy utf8 (not utf8mb4)
+  if grep -Eiq '(CHARACTER[[:space:]]+SET|CHARSET[[:space:]]*=)[[:space:]]*utf8([^m]|$|mb3)' "$f"; then
+    note "$f: legacy 'utf8' (utf8mb3) charset — silently truncates emoji. Use utf8mb4."
+  fi
+  # MyISAM
+  if grep -Eiq 'ENGINE[[:space:]]*=[[:space:]]*MyISAM' "$f"; then
+    note "$f: ENGINE=MyISAM — no transactions/FKs, crash-unsafe. Use InnoDB."
+  fi
+  # likely random-UUID / CHAR(36) PK
+  if grep -Eiq 'CHAR\(36\)[^,)]*PRIMARY[[:space:]]+KEY|PRIMARY[[:space:]]+KEY[^,)]*CHAR\(36\)' "$f"; then
+    note "$f: CHAR(36) PRIMARY KEY — likely a random UUID PK; bloats InnoDB secondary indexes. Prefer BIGINT AUTO_INCREMENT or UUIDv7 as BINARY(16)."
+  fi
+  # function-wrapped indexed column in WHERE (non-sargable)
+  if grep -Eiq 'WHERE[[:space:]].*(DATE|LOWER|UPPER|YEAR|MONTH|CAST|CONVERT)[[:space:]]*\([[:alnum:]_.`]+\)[[:space:]]*=' "$f"; then
+    note "$f: a function-wrapped column in WHERE (e.g. WHERE DATE(col)=...) is non-sargable — the index can't be used. Rewrite to a range, or add a functional/generated-column index."
+  fi
+  # balance check on comment/literal-stripped SQL
+  stripped="$(strip_sql "$f")"
+  opens="$(printf '%s' "$stripped" | tr -cd '(' | wc -c | tr -d ' ')"
+  closes="$(printf '%s' "$stripped" | tr -cd ')' | wc -c | tr -d ' ')"
+  quotes="$(printf '%s' "$stripped" | tr -cd "\047" | wc -c | tr -d ' ')"
+  if [ "$opens" != "$closes" ]; then
+    err "$f: unbalanced parentheses ($opens '(' vs $closes ')')."
+  fi
+  if [ $(( quotes % 2 )) -ne 0 ]; then
+    err "$f: unbalanced single-quotes after stripping comments/literals."
+  fi
+done
+
+# --- per-config-file checks -------------------------------------------------------------------
+for f in ${CNF_FILES[@]+"${CNF_FILES[@]}"}; do
+  if grep -Eiq '^[[:space:]]*binlog_format[[:space:]]*=[[:space:]]*STATEMENT' "$f"; then
+    err "$f: binlog_format = STATEMENT — non-deterministic statements drift on replicas. Use ROW."
+  fi
+  if grep -Eiq '^[[:space:]]*default_authentication_plugin[[:space:]]*=[[:space:]]*mysql_native_password' "$f"; then
+    note "$f: default_authentication_plugin = mysql_native_password — disabled by default in 8.4, removed in 9.0. Use caching_sha2_password + TLS."
+  fi
+done
+
+# --- optional sqlfluff --------------------------------------------------------------------------
+if [ "${#SQL_FILES[@]}" -gt 0 ]; then
+  if command -v sqlfluff >/dev/null 2>&1; then
+    if sqlfluff lint --dialect mysql ${SQL_FILES[@]+"${SQL_FILES[@]}"} >/dev/null 2>&1; then
+      ok "sqlfluff (dialect mysql): no lint errors"
+    else
+      err "sqlfluff (dialect mysql) reported lint errors — run: sqlfluff lint --dialect mysql <file>"
+    fi
+  else
+    skip "sqlfluff not installed — skipping SQL lint (advisory)"
+  fi
+fi
+
+if [ "$EXIT" -eq 0 ]; then
+  ok "verify passed (advisory warnings, if any, are non-blocking)"
+fi
+exit "$EXIT"

package/skills/neon/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: neon
+description: "Use when you picked Neon (serverless Postgres) and need to connect it correctly from a serverless/edge runtime, wire database branching into dev/preview/CI, or stop getting burned by scale-to-zero cold starts and pooler limits — code imports @neondatabase/serverless, DATABASE_URL points at *.neon.tech, or you must choose HTTP neon() vs WebSocket Pool. Triggers: 'connect to Neon from a Cloudflare Worker / Vercel edge', 'too many connections from my serverless function', 'first request after idle is slow' (scale-to-zero cold start), 'which connection string for migrations vs app queries', 'a database branch per pull request', 'pooled vs direct -pooler endpoint', 'conexión serverless a Postgres en Neon', 'branca de base de dades per cada PR'. NOT generic Postgres schema/index/EXPLAIN/RLS/migration engine work (that is postgresdb)."
+tags: [neon, postgres, serverless, database, branching, edge]
+recommends: [postgresdb, drizzle-orm, prisma-orm, vercel]
+origin: risco
+---
+
+# Neon — serverless Postgres as a platform
+
+Neon is Postgres with three platform features the engine doesn't have: a **serverless driver** that
+talks over HTTP/WebSocket (so you can query from edge runtimes), **built-in connection pooling**, and
+**copy-on-write branching** that makes a fork of production data appear instantly. This skill owns
+that platform layer. The Postgres *engine* underneath — schema, indexes, EXPLAIN, RLS, zero-downtime
+DDL — is identical to any Postgres 16 and belongs to `../postgresdb/SKILL.md`. Don't re-derive engine
+craft here; connect correctly and branch correctly.
+
+## When to use / When NOT to use
+
+**When to use:**
+
+- Code imports `@neondatabase/serverless`, or `DATABASE_URL` points at `*.neon.tech` / `*.aws.neon.tech`.
+- Connecting from Vercel (Edge/Node), Cloudflare Workers, AWS Lambda, or any serverless/edge function — choosing HTTP `neon()` vs WebSocket `Pool`.
+- Setting up branching: dev branch off production, a branch per PR in CI, `neonctl` usage, the Neon + Vercel preview integration.
+- Neon-specific symptoms: cold start after scale-to-zero, "too many connections" despite being serverless, pooled-vs-direct string confusion, autoscaling CU sizing/cost.
+- Picking the connection string for migrations (direct) vs app queries (pooled).
+
+**When NOT to use — route to the sibling:**
+
+- Schema design, index choice, EXPLAIN/ANALYZE, query tuning, RLS, VACUUM, partitioning, expand-contract migrations → `../postgresdb/SKILL.md`. Neon adds nothing to the engine; defer.
+- Drizzle schema/migrations → `../drizzle-orm/SKILL.md`; Prisma → `prisma-orm`. Neon supplies only the *driver adapter* line.
+- A different managed Postgres/BaaS: Supabase (auth + storage + realtime) → `supabase`; PlanetScale → `planetscale`; Turso/libSQL → `sqlite-turso`.
+- Where to deploy the app talking to Neon → `../vercel/SKILL.md` / `cloudflare` / `railway`.
+- Backup/PITR strategy as a discipline → `backups` (Neon branch-as-restore is mentioned here, not owned).
+
+## Non-negotiables
+
+1. A WebSocket `Pool`/`Client` is **created and closed inside one request handler** — never at module scope in a serverless function. Module scope = a connection that outlives the invocation and leaks.
+2. **App queries use the pooled string** (host contains `-pooler`). **Migrations / DDL / advisory locks / session features use the direct string** (no `-pooler`). Mixing them is the #1 Neon foot-gun.
+3. The HTTP `neon()` driver **always** uses the pooled endpoint — don't hand it a direct string and expect session state.
+4. HTTP `neon()` has **no interactive transactions**. Need `BEGIN ... COMMIT` across round-trips? Use `sql.transaction([...])` (batched, non-interactive) or a WebSocket `Pool`.
+5. On Node.js ≤ 21 you **must** set `neonConfig.webSocketConstructor = ws` before opening a Pool/Client. Node 22+ and edge runtimes have a global `WebSocket`; don't set it there.
+6. Pin the driver: `@neondatabase/serverless` is at **v1.1.0** (npm latest, 2026-04-17). It is a drop-in replacement for `pg`.
+
+## Pick your connection method
+
+Keyed by runtime and what the query needs. Pick the lightest transport that satisfies the need.
+
+| You need | Use | Why |
+| --- | --- | --- |
+| One independent read/write per request (edge, Lambda, RSC) | HTTP `neon()` | Single fetch round-trip (~3 round trips vs ~8 for TCP setup); no connection to manage or leak. |
+| Several queries that must be atomic, no logic between them | `sql.transaction([q1, q2])` over HTTP | One round-trip, real transaction, still no socket lifecycle. |
+| Interactive transaction — read a row, branch in app code, then write | WebSocket `Pool` (open+close in handler) | HTTP can't hold `BEGIN` open; WebSocket keeps the session alive within the request. |
+| Full `pg`-API compatibility (cursors, LISTEN/NOTIFY, COPY) | WebSocket `Client`/`Pool` | HTTP is one-shot; node-postgres semantics need the socket. |
+| Migrations / DDL / `pg_advisory_lock` / session GUCs | direct (non-`-pooler`) string with `pg` or WebSocket `Client` | PgBouncer transaction-pooling breaks session-level state. |
+
+If you're behind Drizzle or Prisma, you don't call these directly — you pass the driver to the
+adapter. See the ORM pointers below.
+
+## Connection strings: pooled vs direct
+
+Neon gives every branch two connection strings that differ in **one** thing: the host of the pooled
+one contains `-pooler`.
+
+```text
+pooled:  postgresql://user:pass@ep-cool-name-123456-pooler.us-east-2.aws.neon.tech/db?sslmode=require
+direct:  postgresql://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/db?sslmode=require
+```
+
+| Use case | String | Reason |
+| --- | --- | --- |
+| App runtime (queries from your functions) | **pooled** (`-pooler`) | PgBouncer fans many short-lived serverless invocations onto a small pool; up to 10,000 concurrent client connections per project. |
+| HTTP `neon()` driver | **pooled** (it forces it regardless) | The HTTP path is stateless; pooling is the right model. |
+| Migrations, DDL, schema introspection | **direct** | Transaction pooling drops session state; advisory locks and prepared statements need a stable session. |
+| `psql` interactive / debugging | **direct** | You want one real session, not a pooled handle. |
+
+Bad → Good for a typical setup:
+
+```bash
+# Bad: one string everywhere — migrations sporadically fail under PgBouncer.
+DATABASE_URL="postgresql://...-pooler.../db?sslmode=require"
+
+# Good: split them. App uses the pooled one; the migration tool uses DIRECT.
+DATABASE_URL="postgresql://...-pooler.../db?sslmode=require"          # app runtime
+DIRECT_URL="postgresql://....../db?sslmode=require"                    # migrations/DDL
+```
+
+## Serverless driver patterns
+
+All examples assume `@neondatabase/serverless@1.1.0`.
+
+HTTP one-shot — the default for edge/serverless reads and writes:
+
+```ts
+import { neon } from "@neondatabase/serverless";
+
+const sql = neon(process.env.DATABASE_URL!); // pooled endpoint, no socket to manage
+export async function getUser(id: string) {
+  const [row] = await sql`select id, email from users where id = ${id}`;
+  return row; // parameterized; ${id} is bound, not interpolated
+}
+```
+
+Batched atomic writes over HTTP — atomicity without a WebSocket and without interactivity:
+
+```ts
+import { neon } from "@neondatabase/serverless";
+
+const sql = neon(process.env.DATABASE_URL!);
+await sql.transaction([
+  sql`insert into orders (id, total) values (${id}, ${total})`,
+  sql`update inventory set qty = qty - 1 where sku = ${sku}`,
+]); // one round-trip, both succeed or both roll back
+```
+
+Interactive transaction — WebSocket `Pool`, opened **and closed inside the handler**:
+
+```ts
+import { Pool, neonConfig } from "@neondatabase/serverless";
+import ws from "ws"; // Node ≤21 only; omit on edge / Node 22+
+
+neonConfig.webSocketConstructor = ws; // required on Node ≤21; do NOT set on edge runtimes
+
+export async function transfer(from: string, to: string, cents: number) {
+  const pool = new Pool({ connectionString: process.env.DATABASE_URL }); // inside the handler
+  const client = await pool.connect();
+  try {
+    await client.query("begin");
+    const { rows } = await client.query("select balance from accounts where id=$1 for update", [from]);
+    if (rows[0].balance < cents) throw new Error("insufficient");
+    await client.query("update accounts set balance=balance-$1 where id=$2", [cents, from]);
+    await client.query("update accounts set balance=balance+$1 where id=$2", [cents, to]);
+    await client.query("commit");
+  } catch (e) {
+    await client.query("rollback");
+    throw e;
+  } finally {
+    client.release();
+    await pool.end(); // close before the function returns — no leaked connection
+  }
+}
+```
+
+Edge runtime (Vercel Edge, Cloudflare Workers): use HTTP `neon()`; the global `WebSocket` exists, so a
+`Pool` works without `ws`, but prefer HTTP unless you truly need an interactive transaction.
+
+ORM adapters — you wire the driver, the ORM owns the query API:
+
+- Drizzle: pass `neon()`/`Pool` into `drizzle-orm/neon-http` or `neon-serverless` → `../drizzle-orm/SKILL.md`.
+- Prisma: use the `@prisma/adapter-neon` driver adapter → `prisma-orm`.
+
+## Branching for dev / preview / CI
+
+A Neon branch is **copy-on-write**: created instantly with no data copied, it forks production at a
+point in time, gets its own compute endpoint, and scales to zero independently. That makes a branch a
+cheap, isolated, full-data environment — not a backup substitute (test the restore).
+
+| Situation | Do | Why |
+| --- | --- | --- |
+| Per-developer or per-PR isolated data | **branch off production** | Instant, real prod-shaped data, separate endpoint, auto scale-to-zero → near-free idle. |
+| A genuinely separate product/tenant with its own billing & limits | **new project** | Branches share the project's quotas and pooled-connection ceiling. |
+| Throwaway query you can run against staging | **same branch** | Don't manufacture a branch for a one-off SELECT. |
+
+`neonctl` (alias `neon`) drives create/connect/teardown:
+
+```bash
+neonctl branches create --name pr-$PR_NUMBER --parent main
+neonctl connection-string pr-$PR_NUMBER --pooled   # feed to the preview app
+neonctl branches delete pr-$PR_NUMBER              # on PR merge/close
+```
+
+**Vercel preview integration:** with the Neon + Vercel integration, each preview deployment gets its
+own branch forked from production, auto-deleted when the PR merges or closes — zero CI code. If you're
+not on Vercel, replicate it in CI: create branch on PR open → run migrations (direct string) → seed →
+expose the pooled connection string to the app → delete on PR close. Full GitHub Actions workflow,
+`neonctl` reference, and the Neon API endpoints: [branching-ci](references/branching-ci.md).
+
+**Branch-as-restore (PITR):** to recover, branch from an earlier point in time and either read from it
+or promote it. It's a fast undo, not a tested backup discipline — own that in `backups`.
+
+## Autoscaling & scale-to-zero
+
+Each branch's compute endpoint **autoscales** between a min and max CU (vCPU/RAM) on its own, with no
+noisy neighbors across branches. Idle compute **scales to zero** after **5 minutes** of inactivity
+(default), then resumes on the next connection with a millisecond-to-sub-second cold start.
+
+Cost mental model: non-prod branches sit at zero almost always, so a dozen PR branches cost close to
+nothing. The cold start is the price.
+
+Prod endpoint sizing checklist:
+
+- [ ] Set a sane **min/max CU** for the prod branch — not maxed "just in case" (you pay for the max headroom you actually use).
+- [ ] Latency-sensitive prod with sparse traffic? **Disable scale-to-zero** or set **min CU > 0** so there's no cold start in p99.
+- [ ] Treat the cold start as real: warm the connection on deploy, or accept it on non-prod and account for it in latency SLOs.
+- [ ] Keep non-prod branches on scale-to-zero — that's where the near-free economics come from.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| `new Pool(...)` at module scope in a serverless function | Connection outlives the invocation; you exhaust the pool → "too many connections". | Create and `await pool.end()` inside the handler, or use HTTP `neon()`. |
+| Pooled (`-pooler`) string for migrations/DDL | PgBouncer transaction-pooling drops session state; advisory locks/prepared statements fail intermittently. | Use the **direct** string for migrations; pooled only for app runtime. |
+| Direct (non-`-pooler`) string as the app `DATABASE_URL` | No pooling → serverless concurrency exhausts raw connections fast. | App runtime always uses the **pooled** string. |
+| Expecting `BEGIN`/interactive txns from HTTP `neon()` | HTTP is one-shot, stateless — there's no open session to hold a transaction. | `sql.transaction([...])` for batched atomicity, or a WebSocket `Pool` for interactive. |
+| Opening a `Pool` without `neonConfig.webSocketConstructor = ws` on Node ≤21 | No global `WebSocket` → the connection silently fails. | Set `webSocketConstructor = ws` on Node ≤21; omit on edge / Node 22+. |
+| Ignoring scale-to-zero in p99 latency | First request after 5 min idle pays the resume cold start; users see a slow request. | Disable scale-to-zero or set min CU > 0 on latency-sensitive prod. |
+| One shared branch for all PRs | PRs clobber each other's data; no isolation. | One branch per PR, deleted on close. |
+| Treating a branch as a backup without testing restore | Branches share project quotas and aren't an exercised recovery path. | Verify branch-as-restore; own real backup strategy in `backups`. |
+| Maxing CU "to be safe" | You pay for headroom you don't use; autoscaling already handles spikes. | Set a realistic min/max; let autoscaling expand. |
+| Doing schema/index design in this skill | Engine craft is identical to any Postgres; duplicating it drifts. | Defer to `../postgresdb/SKILL.md`. |
+
+## Cross-references
+
+- Engine craft (schema, indexes, EXPLAIN, RLS, zero-downtime DDL): `../postgresdb/SKILL.md`.
+- Next.js App Router data layer that calls Neon: `../nextjs/SKILL.md`.
+- ORM query APIs over the Neon driver: `../drizzle-orm/SKILL.md`, `prisma-orm`.
+- Deployment targets: `../vercel/SKILL.md`, `cloudflare`, `railway`. Backups discipline: `backups`.
+- Other managed DBs (route away): `supabase`, `planetscale`, `sqlite-turso`.

package/skills/neon/evals/README.md

@@ -0,0 +1,11 @@
+# Evals for the `neon` skill
+
+These cases are routing and trigger checks, not executed code. Run them by reading each prompt and
+confirming the behavior: every `should_trigger` prompt should make an agent load and apply this skill
+(including the non-obvious "too many connections" / cold-start phrasings and the Spanish/Catalan
+ones); every `should_not_trigger` prompt should route to the named sibling (`postgresdb`,
+`drizzle-orm`, `supabase`, `vercel`, `backups`) instead of firing here. The `capability` case is a
+rubric: have an agent answer the Neon-wiring scenario and grade the response against each
+`must_include` item — pooled-vs-direct strings, HTTP vs WebSocket choice, Pool lifecycle inside the
+handler, atomic-operation handling, per-PR branching with teardown, and deferring engine craft to
+postgresdb. No network or database is required.

package/skills/neon/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: neon
+
+should_trigger:
+  - prompt: "Connecting to Neon from a Cloudflare Worker — should I use neon() or Pool?"
+    why: Core driver/transport decision for an edge runtime; the heart of this skill.
+  - prompt: "Set up a database branch per pull request so previews get isolated data."
+    why: Per-PR copy-on-write branching workflow, Neon's signature platform feature.
+  - prompt: "I keep getting 'too many connections' from my Vercel function hitting Neon."
+    why: Non-obvious foot-gun — pooled endpoint and module-scope Pool leak, not an engine issue.
+  - prompt: "The first request after the app's been idle a while is super slow against our Neon DB."
+    why: Non-obvious symptom phrasing for scale-to-zero cold start (5-min idle resume).
+  - prompt: "Conexión serverless a Postgres en Neon: ¿qué connection string uso para las migraciones?"
+    why: Spanish; pooled-vs-direct rule (migrations need the direct, non -pooler string).
+  - prompt: "Vull una branca de base de dades per cada PR amb neonctl i que s'esborri al tancar."
+    why: Catalan; per-PR branching with neonctl and teardown — directly in scope.
+
+should_not_trigger:
+  - prompt: "Design the schema and pick indexes for my orders table in Postgres."
+    route_to: postgresdb
+    why: Engine craft — provider-agnostic schema and indexing, identical on any Postgres 16.
+  - prompt: "Write the Drizzle schema and a migration for my Neon DB."
+    route_to: drizzle-orm
+    why: ORM authoring; Neon only supplies the driver adapter line, not the query/schema API.
+  - prompt: "Set up auth and storage with realtime subscriptions for my app."
+    route_to: supabase
+    why: Different BaaS owning auth/storage/realtime, not the Neon serverless-Postgres layer.
+  - prompt: "Deploy my Next.js app to Vercel with preview deployments."
+    route_to: vercel
+    why: Deployment target and platform config, not the database connection or branching.
+  - prompt: "Plan a backup and point-in-time recovery strategy for production."
+    route_to: backups
+    why: Backup discipline; Neon's branch-as-restore is mentioned but the strategy belongs to backups.
+
+capability:
+  - scenario: >
+      Wire a Next.js app deployed on Vercel to Neon. The agent must choose connection strings,
+      pick the right driver per access pattern, handle a multi-step atomic operation safely from a
+      serverless function, and outline per-PR branch isolation in CI.
+    must_include:
+      - Uses the pooled (-pooler) string for app runtime and the direct (non -pooler) string for migrations.
+      - HTTP neon() for one-shot read paths (edge/serverless, single round-trip).
+      - WebSocket Pool created AND closed inside the request handler, never at module scope.
+      - Uses sql.transaction([...]) or a WebSocket Pool for the multi-step atomic operation, not HTTP single statements expecting interactivity.
+      - Per-PR branch via neonctl or the Neon API with teardown on PR close.
+      - Defers schema and index design to postgresdb rather than redoing engine craft.