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

package/skills/shared/structured-extraction/scripts/verify.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — structured-extraction skill check. Run from anywhere. Read-only, no network, no SDK calls.
+#
+# This skill ships code-shaped guidance, so its rigor is a checkable artifact: a STATIC lint of the
+# skill's OWN markdown examples. It asserts the guidance is internally consistent — it never runs any
+# model or SDK.
+#
+# Checks:
+#   1. SKILL.md exists and frontmatter has name/description/tags/recommends/origin; description is one line.
+#   2. references/providers.md exists and is non-empty.
+#   3. Every fenced code block in SKILL.md + references carries a language tag.
+#   4. At least one example sets additionalProperties: false.
+#   5. Optional fields are shown as a nullable union (["...","null"]) somewhere — not the omit-from-required trap.
+#   6. The deprecated Anthropic output_format / structured-outputs-2025-11-13 header is NOT used as a
+#      primary (Good) example — it may only appear flagged as deprecated.
+#   7. No raw json.loads(/JSON.parse( on model output presented as the recommended path (the Good fences
+#      must use native decoding; a raw-parse line is only allowed in a Bad/anti-pattern context).
+#
+# Exit: 0 when every present artifact passes (and 0 if SKILL.md is simply absent — empty target, no false
+# failure). Non-zero only on a real inconsistency in a file that exists.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+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" "$*"; }
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(dirname "$SCRIPT_DIR")"
+SKILL="$SKILL_DIR/SKILL.md"
+REF="$SKILL_DIR/references/providers.md"
+fail=0
+
+# ---- empty target: nothing to check, do not fake a failure ----
+if [ ! -f "$SKILL" ]; then
+  skip "no SKILL.md at $SKILL — nothing to lint"; exit 0
+fi
+ok "SKILL.md present"
+
+# ---- frontmatter keys ----
+for key in "name:" "description:" "tags:" "recommends:" "origin:"; do
+  if grep -q "^${key}" "$SKILL"; then
+    ok "frontmatter has ${key%:}"
+  else
+    err "frontmatter missing ${key%:}"; fail=1
+  fi
+done
+
+desc_lines="$(grep -c '^description:' "$SKILL" || true)"
+if [ "$desc_lines" = "1" ]; then
+  ok "description is a single key line"
+else
+  err "expected exactly one 'description:' line, found $desc_lines"; fail=1
+fi
+
+# ---- references present ----
+if [ -s "$REF" ]; then
+  ok "references/providers.md present and non-empty"
+else
+  err "references/providers.md missing or empty"; fail=1
+fi
+
+# Files to lint (only those that exist).
+FILES=("$SKILL")
+[ -f "$REF" ] && FILES+=("$REF")
+
+# ---- every code fence is language-tagged ----
+# A fence opener is a line starting with ``` ; count those with no language word after the backticks.
+# Closers are paired, so we look at odd-indexed openers only via awk toggling.
+for f in "${FILES[@]}"; do
+  bad_fence="$(awk '
+    /^```/ {
+      infence = !infence
+      if (infence) {            # this is an opener
+        lang = substr($0, 4)
+        gsub(/[ \t\r]/, "", lang)
+        if (lang == "") c++
+      }
+      next
+    }
+    END { print c+0 }
+  ' "$f")"
+  if [ "$bad_fence" = "0" ]; then
+    ok "$(basename "$f"): all code fences language-tagged"
+  else
+    err "$(basename "$f"): $bad_fence untagged code fence(s)"; fail=1
+  fi
+done
+
+# ---- at least one additionalProperties: false example ----
+if grep -Eq '"additionalProperties":[[:space:]]*[fF]alse|additionalProperties.*[fF]alse' "$SKILL" "$REF" 2>/dev/null; then
+  ok "additionalProperties:false shown in an example"
+else
+  err "no example sets additionalProperties:false"; fail=1
+fi
+
+# ---- nullable union shown (optional-as-null, not omit-from-required) ----
+if grep -Eq '"null"' "$SKILL" "$REF" 2>/dev/null; then
+  ok "nullable union (\"...\",\"null\") shown for optional fields"
+else
+  err "no nullable-union example for optional fields"; fail=1
+fi
+
+# ---- deprecated Anthropic surface must not be a primary example ----
+# Allowed ONLY on a line that also flags it as deprecated.
+dep_bad=0
+while IFS= read -r line; do
+  case "$line" in
+    *output_format*|*structured-outputs-2025-11-13*)
+      case "$line" in
+        *[Dd]eprecat*) : ;;                 # fine: flagged as deprecated
+        *output_config*) : ;;               # fine: contrasting against the current param name
+        *) dep_bad=1 ;;
+      esac ;;
+  esac
+done < "$SKILL"
+if [ "$dep_bad" = "0" ]; then
+  ok "deprecated Anthropic output_format/header not used as a primary example"
+else
+  err "deprecated output_format / structured-outputs-2025-11-13 used without a deprecation flag"; fail=1
+fi
+
+# ---- raw parse on model output only allowed inside an explicitly-Bad context ----
+# Walk SKILL.md tracking the nearest preceding 'Bad' marker per fenced block.
+raw_bad=0
+ctx_bad=0
+infence=0
+while IFS= read -r line; do
+  case "$line" in
+    '**Bad'*|'# Bad'*|'## Bad'*|*'Bad —'*|*'Bad -'*) ctx_bad=1 ;;
+    '**Good'*|*'Good —'*|*'Good -'*) ctx_bad=0 ;;
+  esac
+  case "$line" in
+    '```'*) infence=$((1-infence)); continue ;;
+  esac
+  if [ "$infence" = "1" ]; then
+    case "$line" in
+      *json.loads\(*|*JSON.parse\(*)
+        # guaranteed-valid string is fine (parsing a decoder output is OK if it's the Good native path);
+        # we only flag a raw parse that is NOT in a Bad block AND has no 'guaranteed'/'now' reassurance.
+        case "$line" in
+          *guaranteed*|*now\ guaranteed*) : ;;
+          *)
+            if [ "$ctx_bad" = "0" ]; then raw_bad=1; fi ;;
+        esac ;;
+    esac
+  fi
+done < "$SKILL"
+if [ "$raw_bad" = "0" ]; then
+  ok "no raw json.loads/JSON.parse on model output outside a Bad/anti-pattern context"
+else
+  err "raw json.loads(/JSON.parse( on model output presented as a recommended path"; fail=1
+fi
+
+if [ "$fail" -ne 0 ]; then
+  err "static lint failed"; exit 1
+fi
+ok "all static checks passed"
+exit 0

package/skills/shared/suggest/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: suggest
+description: "Always-on. Use whenever the current user turn would clearly benefit from an ai-hub skill that is not yet installed — detect the gap during normal agent use, name the skill, and (with a one-word confirm) install it via `npx ai-hub add <id>`. Triggers on capability intent in any language: building technology, creating content/assets, automating workflows, analyzing data, connecting tools, shipping/deploying, security, business ops, marketing, education, research, or company/documentation harness work."
+tags: [suggest, detect, install, meta, always-on]
+recommends: []
+profiles: [minimal, core, full]
+origin: ai-hub
+---
+
+# ai-hub-suggest — the always-on layer
+
+Your body is injected at the start of **every** session and again after every compaction, so you
+are the one piece guaranteed to be present before any other skill is matched. Two jobs, in order:
+
+1. **Classify every turn into one of three lanes** before anything is written.
+2. **Keep the session equipped** — spot the skill the task needs but the user does not have.
+
+---
+
+## 1. The decisor: classify the turn before acting
+
+Every turn takes one of three lanes, and you name the one you took in a line, in the person's
+language (the lane names are labels to translate).
+
+**Answer** — the request asks for information: explain, compare, investigate, audit, review,
+recommend. Read-only: write nothing, create no artifact, delegate no writer. Asking you to *think
+about* building something is still this lane; only asking to build authorises it. When change
+intent is ambiguous, ask one question and stay here — ambiguity slows the lane, never raises it.
+
+**You choose the lane; never hand that choice to the person.** Simple → **FTD**: one feature document
+in `02-DOCS` (intent, scope, checklist, evidence, next step), tasks checked off against observed proof.
+Big, or decisions that affect each other → **SDD**: enter the chain; the person approves the spec and
+clarify, then picks manual or autopilot. Say which and why in one line; switch if asked.
+→ `../ftd/SKILL.md` · `../sdd/SKILL.md`.
+
+**Where.** Default branch open (chosen at install, or nothing complex) → work on it, no branch
+question. Closed («ramas y PR», CI, team) → before each code change ask: this branch, a new one, or
+`ai-hub main unlock`? Never branch alone. Another session here → `.worktrees/<branch>`.
+
+Judge the **meaning**, not the wording: the trigger is semantic in any language. A bug fix restoring
+intended behaviour is `debug`. Autopilot consent covers a whole run — advance without re-asking.
+
+Lane's skill missing? Offer it (§2) first. SDD recorded as deferred in `.ai-hubrc.json`? Run
+`npx ai-hub@latest reassess`; silent on `AI_HUB_REASSESSMENT_NO_CHANGE`, and on new evidence
+show the plan command — SDD still needs a newly accepted plan id, never added silently.
+
+---
+
+## 2. Keeping the session equipped
+
+When the task needs a capability the user has **not installed** — building, creating, automating,
+analyzing, connecting, shipping, securing, selling, teaching, governing or documenting something —
+name it and offer it. This runs mid-conversation, not only at project start.
+
+1. `npx ai-hub catalog --available` lists every not-installed skill as
+   `id  available  short description`.
+2. Pick the single best fit **by meaning**, the way you would match a request to a teammate's
+   expertise — "mandar emails de bienvenida" → an email/outreach skill, though not one keyword
+   overlaps. If nothing genuinely fits, say so
+   and move on: a tangential suggestion is worse than none.
+3. Ask once, plainly: "Para esto instalaría `<id>`, que aún no tienes. ¿La instalo? (sí/no)".
+4. On yes, run `npx ai-hub add <id>`, then continue the original task.
+
+Installing changes the user's environment, so it is always their call. One suggestion at a time,
+and never to interrupt a flow with a nice-to-have. Never recommend something already installed
+(`npx ai-hub list`).
+
+`npx ai-hub consult "<task>"` is a **lexical** hint only: it misses natural-language and
+non-English intent. Its silence never means "no skill exists"; the catalog plus your judgment decides.
+
+### Automation gap — after the work
+
+Delivered work a repeatable **procedure**? Before proposing to *build* anything, run
+`npx ai-hub capabilities`: covered by a skill or agent → use it, say nothing.
+Not covered → one line, skill or agent. Rules: `skill-scout`.
+
+---
+
+## 3. A harness that is broken fixes itself
+
+You are injected into every session, so you are the only thing that can notice a broken
+harness before its owner does — and its owner usually cannot, because the symptoms name
+nothing they recognise. When any of these is true, act on it **once** in the session:
+
+- `.ai-hubrc.json` exists and what it declares is not what is installed;
+- the same hook seems to run several times;
+- the harness is wired for an assistant that is not the one running.
+
+Run `npx ai-hub doctor`, and say in one line what is wrong **as a symptom**, not as
+a cause. Then:
+
+- **Nothing built** — `.ai-hubrc.json` without `.ai-hub/`: a clone. Name
+  `npx ai-hub@<catalogVersion in .ai-hubrc.json> sync`, that exact version, **never** `@latest`
+  — a release nobody here adopted is drift. Ask in one line, **keep working either way**; silence
+  is not a no, `.ai-hub/.no-harness` is.
+- Anything that only puts the harness back to what was already declared — dangling links, a
+  repeated hook, a layout no version uses — say you are fixing it and run
+  `npx ai-hub repair`. Restoring is not deciding, and a recoverable copy is kept.
+- Anything that would change a decision — moving to another assistant, adopting a skill a
+  teammate added, disarming a gate — **ask first**. A `git pull` never rewrites someone's
+  machine.
+
+Offer once per session. Never mention any of it when the harness is healthy.
+
+## 4. First contact
+
+Before handling the first request of a session, check the workspace:
+
+- No `02-DOCS/wiki/harness/user-profile.md` **and** no `.ai-hub/.no-harness` → invoke `init` first
+  (one question: technical terms or analogies) before the task.
+- A clone (`.ai-hubrc.json` committed) is not first contact: ask that once, in one line, then continue
+  with their task; with `.ai-hub/.profile-offered`, never again.
+- The user declines a harness here ("sin harness", "solo código") → create an empty
+  `.ai-hub/.no-harness`, confirm in one line, and never auto-start `init` in this repo again.
+- With a profile, this gate is inert. Never re-onboard.
+
+## Explain without assuming
+
+Define a term at first use; never give a command, flag or path without saying what it does.
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, al grano, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a §2 el "¿instalo la skill que falta?".)

package/skills/shared/suggest/evals/README.md

@@ -0,0 +1,17 @@
+# Evals — ai-hub-suggest
+
+The always-on detector. These cases check that it proposes the right missing
+skill (and stays quiet when the task needs nothing new).
+
+| Prompt | Expected |
+|---|---|
+| "crear la tabla de pedidos en la base de datos" | suggests `postgresdb` |
+| "publicar mi web online con docker" | suggests `deployment` |
+| "quiero montar una pagina web para vender cursos online" | during agent use, consults the catalog and suggests the first missing startup/web skill, usually `nextjs` after base install |
+| "Automatiza el flujo de leads desde el formulario hasta mi CRM" | during agent use, consults the catalog and suggests the first missing automation/connector skill |
+| "Write a cold email sequence to sell my SaaS to agencies" | during agent use, consults the catalog and suggests the first missing email/marketing skill |
+| "renombra esta variable" | no suggestion (trivial, nothing to install) |
+
+A pass = the detector names the expected skill, asks a one-word confirm, and on
+"sí" runs `npx ai-hub add <id>`. It must never auto-install without confirmation and
+must not recommend a skill already in `npx ai-hub list`.

package/skills/shared/suggest/evals/cases.yaml

@@ -0,0 +1,78 @@
+skill: suggest
+
+# The always-on detector. It fires when the current task would clearly benefit
+# from a catalog skill that is NOT yet installed, names it, and (with confirmation)
+# runs `ai-hub add skill <id>`. It should stay silent for trivial work and defer to a
+# skill that already owns the task.
+
+should_trigger:
+  - prompt: "Quiero montar una pagina web para vender cursos online."
+    why: "Mid-conversation project-start intent — the detector should consult the catalog and propose the first missing skill from the startup queue (usually `nextjs` after the base install, or `init` in a bare install) before building."
+
+  - prompt: "Automatiza el flujo de leads desde el formulario hasta mi CRM."
+    why: "Mid-conversation automation/integration intent — the detector should consult the catalog and propose the first missing automation or connector skill before designing the workflow."
+
+  - prompt: "Write a cold email sequence to sell my SaaS to agencies."
+    why: "Mid-conversation creation/marketing intent — the detector should consult the catalog and propose the first missing email or marketing skill before writing generic copy."
+
+  - prompt: "Ayúdame a montar la tabla de pedidos en la base de datos."
+    why: "A database task with no DB skill present — the detector should propose `ai-hub add skill postgresdb` before diving in."
+
+  - prompt: "Quiero publicar mi web online, creo que con Docker."
+    why: "A deployment task with no deploy skill present — propose installing `deployment`."
+
+  - prompt: "Necesito una API en Python para esta app."
+    why: "Backend Python work with no stack skill present — propose installing `fastapi`."
+
+  - prompt: "Vamos a hacer la landing y que convierta bien."
+    why: "A design/conversion task with no design skill present — propose installing `design`."
+
+  - prompt: "Quiero un agente de IA que conteste sobre mis documentos."
+    why: "Agent/RAG work with no agents skill present — propose installing `building-agents`."
+
+  - prompt: "Documenta cómo funciona mi empresa y conéctalo todo."
+    why: "Company harness work with no harness skill present — propose installing `harness`. A deliberately non-code, non-obvious trigger."
+
+should_not_trigger:
+  - prompt: "Renombra esta variable a `userCount`."
+    route_to: "none"
+    why: "Trivial mechanical edit — nothing to install; the detector must stay silent and not interrupt the flow."
+
+  - prompt: "Revisa este código de login por inyección y control de acceso."
+    route_to: "secure-coding"
+    why: "A security review is squarely owned by the secure-coding skill; if it is installed the detector defers to it rather than proposing anything."
+
+  - prompt: "Optimiza esta query de Postgres que va lenta."
+    route_to: "postgresdb"
+    why: "A concrete database task owned by the postgresdb skill — the detector does not fire over a skill that already owns the work."
+
+  - prompt: "Arregla este bug del test que falla."
+    route_to: "debug"
+    why: "Root-cause debugging is the debug skill's job; no new install is implied, so the detector stays quiet."
+
+capability:
+  - scenario: "Mid-conversation, the user says 'ayúdame a guardar los pedidos en una base de datos' and no database skill is installed. Show how suggest behaves."
+    must_include:
+      - "Names the missing skill in plain language ('para esto va bien `postgresdb`, que aún no tienes')"
+      - "Asks a single short confirmation (sí/no) before doing anything — never auto-installs"
+      - "On confirmation, runs `ai-hub add skill postgresdb` via Bash, then continues the original task"
+      - "Checks what is already declared (`ai-hub list` and `manifest.yaml`) and never proposes a skill the user already has"
+      - "Makes at most one suggestion and does not interrupt the flow for nice-to-haves"
+
+  - scenario: "Mid-conversation, after base install, the user says 'quiero montar una pagina web para vender cursos online'. `init`, `harness`, `orient`, `suggest`, and `unslop` are already installed; `nextjs` is not. Show how suggest behaves."
+    must_include:
+      - "Treats the message as in-agent capability intent, not as a CLI-only consult task"
+      - "Compares `core/manifest.json` with `manifest.yaml` (`skills.publish`) to see which catalog skills are not declared"
+      - "Picks the best-fit skill by MEANING from the catalog descriptions"
+      - "Names `nextjs` as the missing useful skill for the website work"
+      - "Asks one short confirmation before installing and does not auto-install"
+      - "On confirmation, runs `ai-hub add skill nextjs`, then resumes the original website task"
+
+  - scenario: "Mid-conversation, the user says 'Automatiza el flujo de leads desde el formulario hasta mi CRM'. The base skills are installed, but `automation-flows` and CRM/connector skills are not. Show how suggest behaves."
+    must_include:
+      - "Treats the message as in-agent capability intent for automation/integration, not only as a coding task"
+      - "Compares `core/manifest.json` with `manifest.yaml` to see the not-declared skills"
+      - "Picks the best-fit missing automation/connector skill by MEANING from the catalog descriptions"
+      - "Names that one missing automation/connector skill"
+      - "Asks one short confirmation before installing and does not auto-install"
+      - "On confirmation, runs `ai-hub add skill <id>` for that one missing skill, then resumes the automation task"

package/skills/shared/supabase/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: supabase
+description: "Use when building on Supabase as a backend over managed Postgres — wiring the supabase-js or SSR client, writing or debugging Row Level Security, cookie-based Auth, Storage buckets, Realtime, and Edge Functions, including local versus server JWT verification and the service-role key. NOT raw Postgres tuning (that is `postgresdb`)."
+tags: [supabase, postgres, rls, auth, edge-functions, realtime, storage, baas]
+recommends: [postgresdb, nextjs, db-migrations, secure-coding, drizzle-orm]
+origin: ai-hub
+---
+
+# Supabase — Postgres with RLS as the auth layer
+
+Supabase is a managed Postgres database wrapped in thin SDKs, a PostgREST data API, Auth, Storage,
+Realtime, and Deno Edge Functions. The one sentence that explains every footgun below:
+
+> **Your authorization lives in the database (Row Level Security), not in your app code.**
+
+The browser holds a key that can hit your database directly. That is safe *only* because RLS gates
+every row. Get that wrong and you either leak everything or see nothing. Everything in this skill is
+downstream of that fact. You can write SQL already — what you need is Supabase's specific abstractions
+and where the trust boundary sits.
+
+Use the current packages: **`@supabase/supabase-js` v2** (v1 is security-fixes only) and
+**`@supabase/ssr`** for server frameworks (it replaced the deprecated `auth-helpers`).
+
+---
+
+## The two keys (the trust boundary)
+
+Every Supabase project ships two classes of key. Confusing them is the one unrecoverable mistake.
+
+| Key | Where it lives | RLS | If it leaks |
+|-----|----------------|-----|-------------|
+| **anon** / **publishable** (`sb_publishable_...`) | Browser, public env (`NEXT_PUBLIC_*`) | **Enforced** — safe in client only because RLS gates rows | Low: attacker still bound by your policies |
+| **service_role** / **secret** (`sb_secret_...`) | Server only — Edge Functions, server env, never bundled | **Bypassed entirely** | Catastrophic: full read/write of all data |
+
+The new `sb_publishable_` / `sb_secret_` format is rolling out alongside the legacy anon/service_role
+JWTs; treat them by the same rules. **Why this matters:** the service_role key is a master key with
+RLS turned off. One import into a client component is a full data breach.
+
+```ts
+// Bad — service_role key reachable from the browser bundle
+"use client";
+const supabase = createClient(URL, process.env.NEXT_PUBLIC_SERVICE_ROLE_KEY!); // leaked
+
+// Good — service_role only in server-side env, never NEXT_PUBLIC_*
+// server-only module / Edge Function:
+const admin = createClient(URL, process.env.SUPABASE_SERVICE_ROLE_KEY!);
+```
+
+---
+
+## Pick your client
+
+| Context | Package | Where it lives |
+|---------|---------|----------------|
+| Browser-only SPA | `@supabase/supabase-js` (`createClient`) | Client bundle, anon key |
+| Next.js / SvelteKit / Remix (SSR) | `@supabase/ssr` (`createBrowserClient` + `createServerClient`) | One client per context + middleware |
+| Server job / Edge Function | `@supabase/supabase-js` with service_role from env | Server only |
+
+Wrong client = broken sessions (no cookie refresh) or leaked keys. For SSR frameworks you need
+**both** an `@supabase/ssr` browser client and a server client, plus middleware — see below.
+
+---
+
+## Auth that actually protects
+
+Cookie-based auth in an SSR framework has one hard constraint: **Server Components cannot write
+cookies**, so an expired access token can only be refreshed in **middleware**. Skip the middleware and
+sessions silently die mid-request.
+
+The non-negotiable rule for server-side gating: **never trust `getSession()`** — it only reads the
+cookie, which a client can forge. What you reach for *instead* changed in late 2025.
+
+> **Default: `supabase.auth.getClaims()`.** It verifies the JWT signature locally against your
+> project's published public keys (`/.well-known/jwks.json`, cached on the edge and in memory) — no
+> network round-trip. The current SSR docs say to *"always use `supabase.auth.getClaims()` to protect
+> pages and user data."* This works because new projects sign tokens with **asymmetric keys by default
+> since 2025-10-01** (RSA or Elliptic-Curve / ECC); the private key never leaves Auth, the public key is
+> safe to verify with.
+
+### getClaims vs getUser — pick by signing key + freshness need
+
+| Situation | Use | Why |
+|-----------|-----|-----|
+| New project (asymmetric keys), gating a page or route | **`getClaims()`** | Local JWK signature check, zero latency per call — the documented default |
+| Legacy project still on a **symmetric** JWT secret | `getClaims()` (auto-fallback) | With no public key to verify, `getClaims()` *itself* calls the Auth server — same cost as `getUser()`, so still the right default |
+| You must detect a **just-banned / just-deleted** user mid-session | `getUser()` | Local verification trusts a still-valid signature; only a server round-trip sees a revoked user. Higher cost, stricter guarantee |
+
+```ts
+// Bad — getSession reads an unverified cookie; trivially spoofed
+const { data: { session } } = await supabase.auth.getSession();
+if (!session) redirect("/login"); // NOT a real check on the server
+
+// Good (default) — getClaims verifies the JWT signature locally, no round-trip
+const { data } = await supabase.auth.getClaims();
+if (!data?.claims) redirect("/login");
+
+// Good (strict fallback) — getUser revalidates against the Auth server every call;
+// use only when you need live ban/delete detection
+const { data: { user } } = await supabase.auth.getUser();
+if (!user) redirect("/login");
+```
+
+Middleware token refresh is mandatory; full app-router code (browser client, server client,
+`middleware.ts`, server-action sign-in/out, OAuth/PKCE callback, and the `auth-helpers`→`@supabase/ssr`
+migration checklist) lives in [references/auth-ssr.md](references/auth-ssr.md). For the framework's own
+React Server Components/caching/server-action mechanics see [../nextjs/SKILL.md](../nextjs/SKILL.md) — this skill only covers
+the Supabase wiring inside it.
+
+---
+
+## RLS recipes + the performance cliff
+
+Enable RLS on **every** table the data API can reach, then write policies. Four rules that cover most
+real cases:
+
+1. **`enable row level security`** on the table — without it, an exposed table is wide open to the anon key.
+2. **Scope with `to authenticated`** — don't rely on `auth.uid()` alone to exclude the `anon` role; an
+   anon request has a null uid and may slip through a sloppy predicate.
+3. **Wrap `(select auth.uid())`** — Postgres caches a `select`-wrapped call once per statement instead of
+   re-evaluating per row. Bare `auth.uid()` turns a lookup into a per-row function call → table-scan latency.
+4. **Index the policy columns** — a policy filtering `user_id = (select auth.uid())` needs an index on
+   `user_id`, or every query scans the table.
+
+```sql
+-- Bad — bare auth.uid() re-evaluated per row, no role scope, no index
+create policy "owner reads" on documents
+  for select using ( user_id = auth.uid() );
+
+-- Good — cached subquery, role-scoped; pair with an index
+create policy "owner reads" on documents
+  for select to authenticated
+  using ( user_id = (select auth.uid()) );
+
+create index on documents (user_id);
+```
+
+For cross-table checks (is the user a member of this org?), use a `security definer` helper or a
+`team_id` filter rather than a correlated subquery inside the policy. Multi-tenant `team_id` patterns,
+public-read/private-write, storage policies, `realtime.messages` policies, and how to test policies with
+`set role authenticated` live in [references/rls-cookbook.md](references/rls-cookbook.md). For
+engine-level index choice and EXPLAIN reading, see [../postgresdb/SKILL.md](../postgresdb/SKILL.md).
+
+---
+
+## "My query returns nothing" — checklist
+
+Silent empty results are the #1 confusion. Walk it in order:
+
+1. **Is RLS enabled but you have no policy?** No policy = deny all. Add a `select` policy.
+2. **Is the policy too strict / role-scoped wrong?** Test it: `set role authenticated;` with a faked
+   `request.jwt.claims` (see the cookbook).
+3. **Is the table even exposed to the data API?** This is the new trap. Supabase is flipping the
+   "automatically expose new tables" default **off**: default for new projects since **2026-05-30**, and
+   enforced on **all existing projects 2026-10-30**. An unexposed table is unreachable through PostgREST
+   *even with perfect RLS* — you get empty results, not an error. Expose it explicitly in the dashboard
+   (Data API settings) or grant access in the relevant schema.
+
+---
+
+## Storage
+
+Buckets hold objects; access is governed by RLS policies on the `storage.objects` table — the same
+engine as table RLS.
+
+- **Public bucket**: objects served via a stable public URL, no auth. Good for avatars, bad for anything private.
+- **Private bucket**: reads require a **signed URL** (`createSignedUrl`, time-limited) or an authed request that passes a policy.
+
+**Why this bites:** a "public" bucket with no upload policy is either world-writable or fully closed
+depending on your defaults. Always write explicit `insert`/`select` policies on `storage.objects`.
+
+```ts
+// Client upload (anon key) — RLS on storage.objects decides if it is allowed
+await supabase.storage.from("avatars").upload(`${user.id}/photo.png`, file);
+
+// Private read — short-lived signed URL, not a public link
+const { data } = await supabase.storage.from("docs").createSignedUrl(path, 60);
+```
+
+---
+
+## Realtime — default to Broadcast
+
+Three features, and the choice between them is a scaling decision teams get wrong.
+
+| Feature | Use for | Scaling |
+|---------|---------|---------|
+| **Broadcast** | Ephemeral messages (chat, cursors, custom events) | Scales for high fan-out; preferred default |
+| **Presence** | Who's online / shared cursor state | Backed by Broadcast machinery |
+| **Postgres Changes** | WAL-based row insert/update/delete events | Does **not** fan out well at scale |
+
+> Default to **Broadcast**. Reach for Postgres Changes only for low-volume row-event needs.
+
+For row changes that must reach many clients, use **"broadcast from the database"** — a trigger that
+calls `realtime.broadcast_changes`/`realtime.send` — instead of Postgres Changes. Private channels are
+authorized by RLS policies on the **`realtime.messages`** table (Broadcast and Presence support this).
+
+```ts
+const channel = supabase.channel("room:42", { config: { private: true } });
+channel
+  .on("broadcast", { event: "msg" }, ({ payload }) => render(payload))
+  .subscribe();
+channel.send({ type: "broadcast", event: "msg", payload: { text: "hi" } });
+```
+
+---
+
+## Edge Functions
+
+Edge Functions are Deno/TypeScript, deployed globally. The runtime injects `SUPABASE_URL`,
+`SUPABASE_ANON_KEY`, and `SUPABASE_SERVICE_ROLE_KEY`.
+
+- Scaffold: `supabase functions new my-fn`. Each function may carry its own `deno.json`/`deno.jsonc`
+  (requires CLI ≥ v1.215.0).
+- Secrets: `supabase secrets set MY_KEY=...` (don't commit them).
+- **Forward the caller's JWT** so RLS still applies: read the request's `Authorization` header and pass
+  it into a per-request client. A function that uses the service_role client silently bypasses *all* RLS
+  — only do that for genuinely trusted admin work.
+
+```ts
+// Good — per-request client carries the user's JWT; RLS enforced
+const supabase = createClient(
+  Deno.env.get("SUPABASE_URL")!,
+  Deno.env.get("SUPABASE_ANON_KEY")!,
+  { global: { headers: { Authorization: req.headers.get("Authorization")! } } },
+);
+```
+
+Handle CORS for browser invocations (return `Access-Control-Allow-*` and answer the `OPTIONS` preflight).
+
+---
+
+## Local dev & migrations
+
+- `supabase init` → `supabase start` (local stack) → `supabase link --project-ref <ref>`.
+- Generate migrations from local changes with **`supabase db diff`** rather than editing prod schema in
+  the dashboard (the dashboard drifts from source control).
+- **Declarative schema** (experimental): describe schema as SQL files and let `supabase db diff`
+  generate the migration via the pg-delta diff engine.
+- Seed local data via `supabase/seed.sql`.
+
+For migration discipline (expand-contract, concurrent indexes, batched backfills) the general practice
+lives in `../db-migrations/SKILL.md`; for ORM-managed schema on top of Supabase Postgres see
+[../drizzle-orm/SKILL.md](../drizzle-orm/SKILL.md).
+
+Note: `pg_graphql` is disabled by default on new projects (since Feb 2026) — enable it if you need it.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|--------------|----------------|------------|
+| `service_role`/`sb_secret_` in a client component or `NEXT_PUBLIC_*` | Bypasses RLS → full data breach | Keep it server-only; browser uses anon/publishable |
+| Authorizing with `getSession()` on the server | Reads an unverified cookie; spoofable | `getClaims()` — verifies the JWT signature locally (`getUser()` only when you need live ban/delete detection) |
+| "I'll disable RLS for now" | An exposed table with RLS off is world-readable via the anon key | Enable RLS + write a permissive policy instead |
+| Bare `auth.uid()` in a policy | Re-evaluated per row → table-scan latency | `(select auth.uid())` + index the column |
+| Postgres Changes for chat / high fan-out | Doesn't scale; backpressure and dropped events | Broadcast (incl. broadcast-from-database triggers) |
+| Empty results "must be RLS" | Often the table isn't exposed to the data API (2026 default flip) | Check Data API exposure first, then policies |
+| Using `@supabase/auth-helpers` | Deprecated | Migrate to `@supabase/ssr` |
+| service_role client inside an Edge Function for normal user work | Silently bypasses RLS for everyone | Forward the caller's `Authorization` header |
+
+---
+
+## Verify
+
+Run `bash scripts/verify.sh` from a Supabase-backed repo. It hard-fails on `service_role`/`sb_secret_`
+leaking into client-reachable files and warns on `getSession()` used for gating, bare `auth.uid()` in
+policies, and `create table` migrations missing `enable row level security`.

package/skills/shared/supabase/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — supabase
+
+These cases are run by the repository's skill eval runner, not by hand. `should_trigger` asserts the
+router selects `supabase` for each prompt (including the Spanish phrasing and the non-obvious
+trust-boundary / Broadcast-vs-Postgres-Changes cases). `should_not_trigger` asserts the router instead
+routes to the named sibling (`postgresdb`, `drizzle-orm`, `firebase`, `nextjs`) — these are the nearby
+skills most likely to be confused with this one. The `capability` case is graded against its
+`must_include` rubric: a passing answer for the multi-tenant SaaS scenario covers the key trust
+boundary, RLS enablement and performance (`(select auth.uid())`, indexes, `to authenticated`),
+team_id authorization via a security-definer helper, `@supabase/ssr` middleware + `getUser()`, storage
+RLS, and the data-API exposure gotcha. Run with the repo's standard eval command pointed at this
+`cases.yaml`.