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

package/skills/shared/domains-dns/references/tls-and-acme.md

@@ -0,0 +1,90 @@
+# TLS & ACME
+
+## The 2026 lifetime schedule
+
+The CA/Browser Forum (ballot SC-081v3, voting closed 2025-04-11) ratcheted the **maximum public-TLS certificate lifetime** down on a fixed timeline. Domain-validation (DCV) reuse shrinks in lockstep.
+
+| Effective | Max cert lifetime | Max DCV reuse |
+| --- | --- | --- |
+| 2026-03-15 | 200 days | 200 days |
+| 2027-03-15 | 100 days | 100 days |
+| 2029-03-15 | 47 days | 10 days |
+
+Consequence: a human renewing once a year cannot keep up. Every cert path must auto-renew. Let's Encrypt's own default lifetime is moving 90 → 64 → 45 days across 2025–2026, ahead of the CA/B floor.
+
+## HTTP-01 vs DNS-01
+
+| | HTTP-01 | DNS-01 |
+| --- | --- | --- |
+| Proof | Serve a token at `http://host/.well-known/acme-challenge/...` | Publish a `_acme-challenge` TXT |
+| Needs | Inbound port 80 on the host | API access to the DNS zone |
+| Wildcards | No | **Yes — wildcards require DNS-01** |
+| Off-box issuance | No (must answer on the host) | Yes (issue anywhere) |
+
+Pick DNS-01 when you need `*.example.com`, when port 80 is closed, or when the cert is issued somewhere other than the serving host.
+
+## certbot (HTTP-01, single host)
+
+```bash
+# Test against STAGING first so retries don't burn the production rate limit.
+certbot certonly --standalone \
+  --staging \
+  -d example.com -d www.example.com \
+  --agree-tos -m admin@example.com --non-interactive
+
+# Then production once the dry run is clean:
+certbot certonly --standalone \
+  -d example.com -d www.example.com \
+  --agree-tos -m admin@example.com --non-interactive
+```
+
+certbot installs a systemd timer (`certbot.timer`) or cron entry that renews automatically. Verify it:
+
+```bash
+systemctl list-timers | grep certbot
+certbot renew --dry-run        # exercises the full renewal path without issuing
+```
+
+## acme.sh (DNS-01, wildcard)
+
+```bash
+# DNS-01 via the provider's API (Cloudflare token in env) for a wildcard.
+export CF_Token="..."; export CF_Account_ID="..."
+acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --staging
+acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'   # production
+```
+
+acme.sh registers its own cron renewal on install. Always serve the **fullchain**, not the leaf.
+
+## Serve the full chain
+
+```nginx
+ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;  # leaf + intermediates
+ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
+```
+
+A leaf-only config validates in browsers (they cache intermediates from prior sites) and fails on `curl`, mobile, and fresh clients. Always point at `fullchain.pem`.
+
+## Rate limits & ARI
+
+- Let's Encrypt: **50 certificates per registered domain per rolling 7 days**, counted globally across all your ACME accounts.
+- **Renewals recognized via ARI (ACME Renewal Info) are exempt** from the limit, so well-behaved auto-renewal never trips it.
+- Testing/CI loops must hit the **staging** endpoint, or one bad loop locks you out for a week.
+
+## Platform-managed certs
+
+Let the host do it when it can — Vercel, Netlify, and Cloudflare provision and renew automatically once the DNS record resolves to them. Do not stack certbot on top.
+
+- **Cloudflare SSL mode** matters: *Flexible* terminates TLS at the edge and talks plaintext to your origin (insecure, can loop-redirect). *Full* encrypts edge↔origin but doesn't validate the origin cert. *Full (strict)* validates it — use Full (strict) in production with a real or Cloudflare Origin cert.
+- The apex must flatten (see record-cookbook.md) before any of these can validate.
+
+## Cert error → cause → fix
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `ERR_CERT_AUTHORITY_INVALID` on curl/mobile but OK in browser | Leaf-only chain, missing intermediate | Serve `fullchain.pem` |
+| `ERR_CERT_COMMON_NAME_INVALID` / name mismatch | Cert doesn't cover the hostname (e.g. apex cert, www request) | Add the SAN; reissue covering both names |
+| ACME fails with a CAA error | CAA omits your CA, or wildcard lacks `issuewild` | Add `CAA 0 issue "<ca>"` (+ `issuewild` for `*`) |
+| Cert valid but site still warns | Mixed content (HTTP assets on an HTTPS page) | Serve all assets over HTTPS |
+| Expired cert in prod | No working auto-renew | Fix the timer/cron; `certbot renew --dry-run` |
+| Rate-limit / "too many certificates" | Tested against production repeatedly | Use staging; rely on ARI-aware renewal |

package/skills/shared/domains-dns/references/verify-and-debug.md

@@ -0,0 +1,64 @@
+# Verify & debug playbook
+
+Always query the authoritative answer and the wire. Your laptop's resolver caches the old answer for the record's full TTL and will lie to you.
+
+## dig — resolution
+
+```bash
+dig +short app.example.com                 # what your resolver returns right now
+dig +short app.example.com @1.1.1.1         # what a public resolver returns (bypasses local cache)
+dig +trace example.com                      # walk root → TLD → authoritative; reveals stale/wrong NS
+dig NS example.com +short                   # the delegated nameservers
+dig @ns1.provider.net example.com A +short  # ask the authoritative NS directly — the source of truth
+dig CAA example.com +short                  # CA authorization at the apex
+dig TXT _dmarc.example.com +short           # confirm a TXT row took
+```
+
+- `dig +short` shows the resolved value; drop `+short` to see the TTL counting down (low number = recently changed or short TTL).
+- If `dig @<authoritative>` is correct but `dig +short` is wrong, it's **caching** — wait out the TTL or query a fresh resolver. Don't re-edit the record.
+
+## openssl — the served chain
+
+```bash
+openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null \
+  | openssl x509 -noout -subject -issuer -dates
+```
+
+- `-servername` sends SNI; without it a multi-tenant host serves the wrong/default cert and you misdiagnose.
+- Check `notAfter` is comfortably ahead. Check `issuer` matches your CAA.
+- To see whether the **chain is complete**, look at the full handshake output for the intermediate; an incomplete chain is the curl/mobile-only failure.
+
+## curl — the HTTP verdict
+
+```bash
+curl -vI https://example.com 2>&1 | grep -Ei 'HTTP/|location|SSL certificate'
+curl -sI https://www.example.com -o /dev/null -w '%{http_code} %{redirect_url}\n'
+```
+
+- `SSL certificate verify ok` = chain validates from curl's bundle (catches missing intermediates browsers hide).
+- Confirm www and apex resolve to the same canonical host and one 301s to the other.
+
+## Propagation, the right way
+
+Propagation is the **TTL**, not a fixed window (RFC 2181). To make a change land fast:
+
+1. Lower the record's TTL to 300s **before** you change the value.
+2. Wait for the old TTL to elapse so resolvers re-query at the new rate.
+3. Change the value; new value is picked up within ~5 min.
+4. Raise the TTL back afterward.
+
+NS/registrar delegation changes can lag longer because of registry/TLD TTLs — that's the parent zone, outside your control.
+
+## Error → cause → fix
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `NXDOMAIN` | Name doesn't exist in the zone, or wrong zone is authoritative | Confirm record exists; `dig NS` that delegation points at the right provider |
+| `SERVFAIL` | Broken delegation, or DNSSEC DS mismatch | Match registrar NS to provider; fix/remove stale DS |
+| `dig +short` right but browser wrong | Local/OS/browser cache | Flush OS cache or query `@1.1.1.1`; wait the TTL |
+| `dig +trace` shows old IP | Authoritative zone not updated, or queried a stale secondary | Edit at the authoritative provider; bump SOA serial |
+| `ERR_CERT_AUTHORITY_INVALID` (curl/mobile) | Incomplete chain | Serve `fullchain.pem` |
+| `ERR_CERT_COMMON_NAME_INVALID` | Cert SAN doesn't cover the hostname | Reissue covering apex + www |
+| ACME CAA error | CAA forbids your CA | Add `CAA 0 issue "<ca>"` |
+| HTTPS warns despite valid cert | Mixed content | Serve all subresources over HTTPS |
+| Redirect loop on HTTPS | Cloudflare SSL set to Flexible against an HTTPS origin | Set Full (strict) |

package/skills/shared/domains-dns/scripts/verify.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+#
+# verify.sh — audit a domain's DNS + TLS posture (read-only).
+#
+# WHAT IT DOES (read-only; never edits a zone, never issues a cert, no credentials)
+#   Takes ONE domain and runs deterministic checks against the banlist of common mistakes:
+#     1. apex has A/AAAA or ALIAS-style answer and is NOT a CNAME (CNAME-at-apex is illegal).
+#     2. CAA at the apex is parseable; reports the allowed issuers (informational).
+#     3. TLS chain on :443 validates end-to-end (no incomplete-chain) and notAfter is > N days out.
+#     4. HTTPS is reachable (2xx/3xx) and www resolves to the same target as the apex (canonical).
+#
+#   Needs network + `dig`. If `dig` is unavailable OR the domain has no public DNS at all
+#   (nothing to audit), it exits 0 — never a false failure on an empty/unconfigured target.
+#
+# HOW TO RUN
+#   ./verify.sh example.com
+#   ./verify.sh example.com --days 14      # warn-window for cert expiry (default 21)
+#
+# EXIT CODES
+#   0  all checks passed, OR nothing to audit (no dig / domain has no DNS)
+#   1  one or more checks failed (one labeled [fail] line each)
+#   2  bad usage (no domain argument)
+#
+# Stock macOS bash 3.2 safe: no mapfile, no associative arrays, no process substitution required.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; }
+info() { printf '       %s\n' "$*"; }
+
+DOMAIN=""
+DAYS=21
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --days) DAYS="${2:-21}"; shift 2 ;;
+    -*)     printf 'unknown flag: %s\n' "$1" >&2; exit 2 ;;
+    *)      DOMAIN="$1"; shift ;;
+  esac
+done
+
+if [ -z "$DOMAIN" ]; then
+  printf 'usage: %s <domain> [--days N]\n' "$0" >&2
+  exit 2
+fi
+
+# strip any scheme / path / port the user may have pasted
+DOMAIN=$(printf '%s' "$DOMAIN" | sed -E 's#^[a-zA-Z]+://##; s#/.*$##; s#:[0-9]+$##')
+RESOLVER="@1.1.1.1"
+FAILURES=0
+
+# No dig -> we cannot audit DNS; do not invent a failure.
+if ! command -v dig >/dev/null 2>&1; then
+  warn "dig not found — skipping DNS audit (nothing to check)."
+  exit 0
+fi
+
+# Nothing in DNS at all -> nothing to audit, clean exit.
+APEX_NS=$(dig +short "$RESOLVER" NS "$DOMAIN" 2>/dev/null || true)
+APEX_ANY=$(dig +short "$RESOLVER" A "$DOMAIN" 2>/dev/null || true)
+if [ -z "$APEX_NS" ] && [ -z "$APEX_ANY" ]; then
+  warn "no NS or A records found for $DOMAIN — nothing to audit."
+  exit 0
+fi
+
+printf 'Auditing %s (cert warn-window: %s days)\n\n' "$DOMAIN" "$DAYS"
+
+# --- 1. apex must not be a CNAME, and must have an address answer ----------------
+APEX_CNAME=$(dig +short "$RESOLVER" CNAME "$DOMAIN" 2>/dev/null || true)
+APEX_A=$(dig +short "$RESOLVER" A "$DOMAIN" 2>/dev/null || true)
+APEX_AAAA=$(dig +short "$RESOLVER" AAAA "$DOMAIN" 2>/dev/null || true)
+
+if [ -n "$APEX_CNAME" ]; then
+  fail "apex $DOMAIN returns a CNAME ($APEX_CNAME) — illegal at the zone apex."
+  info "Use ALIAS/flattening or hard A/AAAA at the apex instead."
+  FAILURES=$((FAILURES + 1))
+elif [ -n "$APEX_A" ] || [ -n "$APEX_AAAA" ]; then
+  ok "apex resolves to an address (A/AAAA or flattened ALIAS), no CNAME at apex."
+else
+  fail "apex $DOMAIN has no A/AAAA answer — it will not resolve to a host."
+  FAILURES=$((FAILURES + 1))
+fi
+
+# --- 2. CAA sanity (informational; absence = open policy, not a failure) ---------
+APEX_CAA=$(dig +short "$RESOLVER" CAA "$DOMAIN" 2>/dev/null || true)
+if [ -z "$APEX_CAA" ]; then
+  warn "no CAA record — any CA may issue. Consider locking with: CAA 0 issue \"letsencrypt.org\"."
+else
+  ok "CAA present:"
+  printf '%s\n' "$APEX_CAA" | sed 's/^/         /'
+fi
+
+# --- 3. TLS chain completeness + expiry window -----------------------------------
+if command -v openssl >/dev/null 2>&1; then
+  CHAIN=$(echo | openssl s_client -connect "$DOMAIN:443" -servername "$DOMAIN" \
+            -showcerts 2>/dev/null || true)
+  if [ -z "$CHAIN" ]; then
+    fail "no TLS handshake on $DOMAIN:443 — HTTPS not serving."
+    FAILURES=$((FAILURES + 1))
+  else
+    VERIFY_LINE=$(printf '%s' "$CHAIN" | grep -E 'Verify return code|verify error' | head -1 || true)
+    if printf '%s' "$VERIFY_LINE" | grep -qi 'unable to get local issuer\|incomplete\|verify error'; then
+      fail "TLS chain does not validate ($VERIFY_LINE) — likely an incomplete chain; serve fullchain.pem."
+      FAILURES=$((FAILURES + 1))
+    else
+      ok "TLS chain validates from a clean trust store."
+    fi
+
+    NOTAFTER=$(printf '%s' "$CHAIN" | openssl x509 -noout -enddate 2>/dev/null | cut -d= -f2 || true)
+    if [ -n "$NOTAFTER" ]; then
+      END_EPOCH=$(date -j -f '%b %d %T %Y %Z' "$NOTAFTER" '+%s' 2>/dev/null \
+                  || date -d "$NOTAFTER" '+%s' 2>/dev/null || echo "")
+      if [ -n "$END_EPOCH" ]; then
+        NOW_EPOCH=$(date '+%s')
+        LEFT_DAYS=$(( (END_EPOCH - NOW_EPOCH) / 86400 ))
+        if [ "$LEFT_DAYS" -lt 0 ]; then
+          fail "certificate EXPIRED ($NOTAFTER)."
+          FAILURES=$((FAILURES + 1))
+        elif [ "$LEFT_DAYS" -lt "$DAYS" ]; then
+          fail "certificate expires in ${LEFT_DAYS}d ($NOTAFTER) — under the ${DAYS}d window; auto-renew must run."
+          FAILURES=$((FAILURES + 1))
+        else
+          ok "certificate valid for ${LEFT_DAYS} more days (notAfter $NOTAFTER)."
+        fi
+      fi
+    fi
+  fi
+else
+  warn "openssl not found — skipping TLS chain/expiry checks."
+fi
+
+# --- 4. HTTPS reachability + www canonical ---------------------------------------
+if command -v curl >/dev/null 2>&1; then
+  CODE=$(curl -s -o /dev/null -w '%{http_code}' -m 12 "https://$DOMAIN" 2>/dev/null || echo "000")
+  case "$CODE" in
+    2*|3*) ok "HTTPS reachable (HTTP $CODE)." ;;
+    000)   fail "HTTPS request to $DOMAIN failed (no response / TLS error)." ; FAILURES=$((FAILURES + 1)) ;;
+    *)     warn "HTTPS returned HTTP $CODE." ;;
+  esac
+else
+  warn "curl not found — skipping HTTPS reachability check."
+fi
+
+WWW_TARGET=$(dig +short "$RESOLVER" "www.$DOMAIN" 2>/dev/null | tail -1 || true)
+if [ -z "$WWW_TARGET" ]; then
+  warn "www.$DOMAIN does not resolve — pick a canonical host and 301 the other to it."
+else
+  ok "www.$DOMAIN resolves ($WWW_TARGET) — confirm one canonical host 301s to the other."
+fi
+
+printf '\n'
+if [ "$FAILURES" -eq 0 ]; then
+  ok "no failures."
+  exit 0
+fi
+fail "$FAILURES check(s) failed."
+exit 1

package/skills/shared/drizzle-orm/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: drizzle-orm
+description: "Use when modeling data or querying with Drizzle ORM in TypeScript — `pgTable` schema in `.ts`, type-safe select/insert/relational queries, `drizzle-kit` migrations. NOT Prisma Client or `schema.prisma` (that is `prisma-orm`), NOT ORM-agnostic migration strategy (that is `db-migrations`), NOT Postgres engine tuning or EXPLAIN (that is `postgresdb`)."
+tags: [drizzle, drizzle-orm, typescript-orm, drizzle-kit, sql, migrations, database, schema]
+recommends: [prisma-orm, postgresdb, db-migrations, neon, sqlite-turso, planetscale, supabase, typescript, sql]
+origin: ai-hub
+---
+
+# Drizzle ORM — schema as code, type-safe queries, drizzle-kit migrations
+
+Drizzle is the SQL-transparent TypeScript ORM: you declare tables in plain `.ts`, the query
+builder emits SQL you can read, and there is no codegen client to regenerate. It runs in
+edge/serverless runtimes. You own the schema, the queries, and the `drizzle-kit` workflow here —
+the database engine, the ORM-agnostic migration *strategy*, and Prisma live in sibling skills.
+
+## Decide first
+
+Three decisions before you write a line. Each branches, so use the table.
+
+| Decision | Pick | Why |
+|---|---|---|
+| Drizzle vs Prisma | Drizzle when you want SQL you can read, no codegen step, edge runtime | Prisma's generated client + `schema.prisma` DSL is the opposite trade — use `../prisma-orm/SKILL.md` if that is the ask |
+| Version | `0.45.x` + `drizzle-kit@0.31.x` for production | npm `latest` is `drizzle-orm@0.45.2`; the 0.45 line has been `latest` since 2025-12-04 (checked 2026-06-02) |
+| Version | `1.0.0-rc.x` (npm `rc` tag = `1.0.0-rc.3`, 2026-05-18) for a NEW edge-first project | v1 has moved past beta into release candidates with Relations v2 — close to stable, but still pin an exact rc and expect late API churn |
+| Driver entrypoint | match it to your DB/host (see below) | Each driver has its own `drizzle-orm/<driver>` import and its own client |
+
+Driver entrypoints (pick one; full matrix + edge caveats in `references/relations-and-drivers.md`):
+`drizzle-orm/node-postgres`, `/postgres-js`, `/neon-http`, `/libsql` (Turso), `/planetscale-serverless`,
+`/mysql2`, `/better-sqlite3`, `/bun-sqlite`.
+
+## Install & config
+
+```bash
+npm i drizzle-orm
+npm i -D drizzle-kit
+npm i postgres            # the driver client — here postgres-js; swap per your DB
+```
+
+`drizzle.config.ts` — the four keys `drizzle-kit` reads. The `dialect` here MUST match your table
+helper (`pgTable` ⇒ `'postgresql'`), or migrations target the wrong SQL.
+
+```ts
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',          // 'postgresql' | 'mysql' | 'sqlite' | 'turso'
+  schema: './src/db/schema.ts',   // where your tables live
+  out: './drizzle',               // emitted migration SQL
+  dbCredentials: { url: process.env.DATABASE_URL! },
+});
+```
+
+`package.json` scripts — name them once so you never re-type the CLI:
+
+```json
+{
+  "scripts": {
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio"
+  }
+}
+```
+
+## Schema as code
+
+A table is plain TypeScript. Declare columns with the helpers, then derive your row types from the
+table — never hand-write a parallel `interface`, it will drift.
+
+```ts
+import { pgTable, integer, text, timestamp, pgEnum, index } from 'drizzle-orm/pg-core';
+
+export const roleEnum = pgEnum('role', ['admin', 'member']);
+
+export const users = pgTable('users', {
+  id: integer().primaryKey().generatedAlwaysAsIdentity(),
+  email: text().notNull().unique(),
+  role: roleEnum().notNull().default('member'),
+  createdAt: timestamp().notNull().defaultNow(),
+}, (t) => [index('users_email_idx').on(t.email)]);
+
+export const posts = pgTable('posts', {
+  id: integer().primaryKey().generatedAlwaysAsIdentity(),
+  authorId: integer().notNull().references(() => users.id),  // FK
+  title: text().notNull(),
+});
+
+export type User = typeof users.$inferSelect;       // row as read
+export type NewUser = typeof users.$inferInsert;    // row as inserted
+```
+
+- **One schema file per domain, and export every table.** `drizzle-kit` and the relational query
+  builder only see what you pass them — an unexported table is invisible to migrations.
+- **Derive types with `$inferSelect` / `$inferInsert`.** They stay in sync with the column defs for
+  free; a separate interface is one more thing to forget to update.
+
+## Connect
+
+`drizzle()` takes your driver client. Pass `{ schema }` (0.45 / v1-compat) or `{ relations }`
+(v2, the 1.0 rc line) — without one of them, `db.query.*` is `undefined` and relational reads
+silently break.
+
+```ts
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+import * as schema from './schema';
+
+const client = postgres(process.env.DATABASE_URL!);
+export const db = drizzle(client, { schema });   // schema enables db.query.*
+```
+
+## Query
+
+Filter, join, and shape in SQL — not in JavaScript after the fact.
+
+```ts
+import { eq, and, inArray, desc } from 'drizzle-orm';
+
+// select a column subset, not the whole row
+const admins = await db.select({ id: users.id, email: users.email })
+  .from(users)
+  .where(and(eq(users.role, 'admin'), inArray(users.id, [1, 2, 3])))
+  .orderBy(desc(users.createdAt));
+
+// insert + get the row back
+const [created] = await db.insert(users)
+  .values({ email: 'a@b.com', role: 'member' })
+  .returning();
+
+// update / delete take the same operators
+await db.update(users).set({ role: 'admin' }).where(eq(users.id, created.id));
+await db.delete(posts).where(eq(posts.authorId, created.id));
+
+// transaction — all or nothing
+await db.transaction(async (tx) => {
+  const [u] = await tx.insert(users).values({ email: 'c@d.com' }).returning();
+  await tx.insert(posts).values({ authorId: u.id, title: 'hello' });
+});
+```
+
+Relational read (nested objects) needs `{ schema }`/`{ relations }` on the connection AND a `with`:
+
+```ts
+const withPosts = await db.query.users.findMany({
+  where: (u, { eq }) => eq(u.role, 'admin'),
+  with: { posts: true },          // <- the relation; omit it and you get no posts
+});
+```
+
+For conditional builders use `$dynamic()`; for hot paths `prepare()` once and reuse.
+
+```ts
+const q = db.select().from(users).$dynamic();
+const rows = await (role ? q.where(eq(users.role, role)) : q);
+```
+
+**Bad → Good — the classic foot-gun:**
+
+```ts
+// Bad: pull every row, filter in JS — full table scan, no index, ships rows you discard
+const all = await db.query.users.findMany();
+const admins = all.filter((u) => u.role === 'admin');
+
+// Good: filter in the query — the DB uses the index and returns only what you need
+const admins = await db.query.users.findMany({ where: (u, { eq }) => eq(u.role, 'admin') });
+```
+
+## Relations
+
+Relations let `with` hydrate nested objects. Two flavors — do not mix them in one project.
+
+| Line | Define | Connect | Read |
+|---|---|---|---|
+| 0.45 / v1-compat | `relations(users, ({ many }) => ({ posts: many(posts) }))` | `drizzle(client, { schema })` | `db.query.users.findMany({ with: { posts: true } })` |
+| v2 (1.0 rc) | `defineRelations(schema, (r) => ({ users: { posts: r.many.posts() } }))` | `drizzle(client, { relations })` | `db.query.…` (RQBv2); `db._query.…` keeps v1 syntax for back-compat |
+
+**Decision line:** use the relational query (`db.query` + `with`) for nested reads of related
+records; drop to a manual `.leftJoin()` for flat projections, aggregates, or `GROUP BY` — relational
+queries return trees, joins return rows. Full v1↔v2 migration walkthrough in
+`references/relations-and-drivers.md`.
+
+## Migrations
+
+```bash
+npm run db:generate   # diff schema.ts vs ./drizzle, emit a new .sql migration
+# READ the emitted SQL in ./drizzle — confirm it does what you intended
+npm run db:migrate    # apply pending migrations
+```
+
+- **`generate` → review the SQL → `migrate` is the production path.** The emitted SQL is the
+  contract; eyeball it before applying so a rename does not silently become a drop+add.
+- **`push` is for throwaway prototyping only.** It applies `schema.ts` straight to the DB with no
+  migration file — fine for a scratch branch, never for an environment you cannot recreate.
+- **Never hand-edit an applied migration; write a new one.** The migration journal tracks what ran;
+  editing history desyncs every other environment.
+- Recent `drizzle-kit` adds migration-conflict / commutativity detection (it checks whether open
+  migration branches merge safely, with refined index/table footprint checks); `--ignore-conflicts`
+  preserves open leaf parents when you intend to keep branches. `node:sqlite` is auto-detected for
+  `migrate` and Studio.
+
+Inspect data with `npm run db:studio` (Drizzle Studio GUI); pull an existing DB into a schema with
+`drizzle-kit pull`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `push` against a real/shared DB | no migration record; irreproducible, unreviewable | `generate` → review → `migrate` |
+| Hand-editing an applied migration | desyncs the journal across environments | write a new migration |
+| `findMany()` then `.filter()` in JS | full scan, no index, ships discarded rows | filter in `where` |
+| `db.query.*` with no `{ schema }`/`{ relations }` on `drizzle()` | `db.query` is `undefined`; relations never load | pass `{ schema }` (v1) or `{ relations }` (v2) |
+| `with` omitted but relation expected | returns parent only, no nested rows | add `with: { posts: true }` |
+| `dialect` in config ≠ table helper | migrations target the wrong SQL dialect | `pgTable`⇒`'postgresql'`, `mysqlTable`⇒`'mysql'`, etc. |
+| Mixing `relations()` and `defineRelations` | the two relation systems conflict | pick one line per project |
+| `select()` returning every column | over-fetches, fragile to schema growth | `select({ id, email })` subset |
+| Not awaiting a query builder | a builder is a thenable, not a promise — un-awaited it never runs | `await db.select()…` |
+| Hand-written `interface` mirroring a table | drifts from the column defs | `typeof t.$inferSelect`/`$inferInsert` |
+
+## Verify
+
+Run the static lint on any generated Drizzle file (no DB connection):
+
+```bash
+scripts/verify.sh src/db/schema.ts drizzle.config.ts
+```
+
+It checks a `drizzle()` call exists, the table helper matches the configured `dialect`, the config
+carries `dialect`/`schema`/`out`, that any `db.query` usage has `{ schema }`/`{ relations }` passed
+to `drizzle()`, and bans Prisma-isms (`schema.prisma`, `PrismaClient`, `prisma generate`) that mean
+the wrong ORM leaked in.

package/skills/shared/drizzle-orm/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — drizzle-orm
+
+`cases.yaml` is a human/LLM-graded trigger and capability set, not an automated runner. To use it:
+read each `should_trigger` prompt and confirm this skill is the right home (especially the
+non-obvious "no author relation" and "push vs generate" cases and the Spanish/Catalan ones); read
+each `should_not_trigger` prompt and confirm a reasonable router would send it to the named sibling
+(`prisma-orm`, `db-migrations`, `postgresdb`, `neon`, `sql`) rather than here. For the `capability`
+case, have a model answer the scenario and check it hits every item in `must_include` — relation
+defined, `{ schema }`/`{ relations }` passed to `drizzle()`, `with` in the relational query,
+`generate`+`migrate` (not `push`), and `$inferSelect`/`$inferInsert` types. The `scripts/verify.sh`
+static lint can be run against any code the model produces to catch dialect mismatches, a missing
+`{ schema }`/`{ relations }`, and Prisma-ism contamination.

package/skills/shared/drizzle-orm/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: drizzle-orm
+
+should_trigger:
+  - prompt: "Set up Drizzle ORM with Postgres and write the users schema"
+    why: Core setup — install, drizzle.config.ts, pgTable schema; the skill's primary job.
+  - prompt: "drizzle-kit generate is producing a conflicting migration, how do I resolve it?"
+    why: Migration-conflict / commutativity detection is drizzle-kit-specific; squarely this skill.
+  - prompt: "My db.query.posts.findMany returns posts without the author relation"
+    why: Non-obvious — the fix is relations + `with` + passing { schema }/{ relations } to drizzle().
+  - prompt: "Should I use drizzle push or generate+migrate for production?"
+    why: Non-obvious workflow decision the skill resolves (push=prototyping only).
+  - prompt: "Vull definir l'esquema amb Drizzle i tipus type-safe a TypeScript"
+    why: Catalan trigger for schema-as-code + $inferSelect/$inferInsert types.
+  - prompt: "Migrar de Prisma a Drizzle porque quiero algo más ligero para edge"
+    why: Spanish; boundary-adjacent but still Drizzle (target ORM is Drizzle, edge driver choice).
+  - prompt: "How do I wire Drizzle to Neon over HTTP from a Cloudflare Worker?"
+    why: Driver entrypoint selection (neon-http, edge caveats) is in this skill's scope.
+
+should_not_trigger:
+  - prompt: "Generate a Prisma client from schema.prisma"
+    route_to: prisma-orm
+    why: Prisma DSL + codegen client is the rival ORM, not Drizzle.
+  - prompt: "Plan a zero-downtime expand/contract migration strategy"
+    route_to: db-migrations
+    why: ORM-agnostic migration strategy, not Drizzle's drizzle-kit workflow.
+  - prompt: "Tune Postgres indexes and read an EXPLAIN ANALYZE plan"
+    route_to: postgresdb
+    why: Engine-level indexing/plan reading; Drizzle only expresses these from TS.
+  - prompt: "Set up my Neon project and configure connection pooling"
+    route_to: neon
+    why: Platform/account setup, not the Drizzle ORM layer.
+  - prompt: "Write a raw SQL window-function query for a report"
+    route_to: sql
+    why: Raw SQL authoring unattached to Drizzle's query builder.
+
+capability:
+  - scenario: >
+      Add a `posts` table related to `users`, write a type-safe query loading each user with their
+      posts, and produce the migration to apply it.
+    must_include:
+      - "pgTable for posts with a foreign key (.references(() => users.id))"
+      - "relations defined via relations() OR defineRelations()"
+      - "{ schema } (v1) or { relations } (v2) passed to drizzle()"
+      - "db.query.users.findMany({ with: { posts: true } })"
+      - "drizzle-kit generate then migrate (NOT push) for the migration"
+      - "row types derived with $inferSelect / $inferInsert"
+      - "matching dialect 'postgresql' in drizzle.config.ts and pgTable helper"