rsc-universal 0.1.1

package/skills/suggest/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — rsc-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` |
+| "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 rsc add <id>`. It must never auto-install without confirmation and
+must not recommend a skill already in `npx rsc list`.

package/skills/suggest/evals/cases.yaml

@@ -0,0 +1,51 @@
+skill: suggest
+
+# The always-on detector. It fires when the current task would clearly benefit
+# from an rsc skill that is NOT yet installed, names it, and (with confirmation)
+# runs `npx rsc add <id>`. It should stay silent for trivial work and defer to a
+# skill that already owns the task.
+
+should_trigger:
+  - 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 `npx rsc add 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 rsc-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 `npx rsc add postgresdb` via Bash, then continues the original task"
+      - "Checks what is already installed (npx rsc list) and never proposes a skill the user already has"
+      - "Makes at most one suggestion and does not interrupt the flow for nice-to-haves"

package/skills/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 @supabase/ssr client, writing or debugging Row Level Security, cookie-based Auth, Storage buckets, Realtime, or Edge Functions. Triggers: 'my RLS policy returns no rows', 'cookie auth in Next.js with Supabase', 'getClaims vs getUser', 'should I verify the JWT locally or hit the Auth server', 'asymmetric signing keys', 'Broadcast vs Postgres Changes', 'service_role key', 'data API not exposing my table', 'configura Supabase con Next.js', 'mis políticas RLS no devuelven filas'. 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: risco
+---
+
+# 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
+RSC/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/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`.

package/skills/supabase/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: supabase
+
+should_trigger:
+  - prompt: "My Supabase RLS policy returns no rows even though the data is there."
+    why: Core empty-result debugging — RLS, role scope, or data-API exposure; the central confusion this skill exists to resolve.
+  - prompt: "Set up cookie-based auth with Supabase in my Next.js app router."
+    why: SSR auth wiring with @supabase/ssr — browser/server clients plus mandatory middleware token refresh.
+  - prompt: "configura Supabase con Next.js y protege las rutas del servidor"
+    why: Spanish phrasing of the SSR auth + route-protection task; must still route to supabase.
+  - prompt: "Should I use Realtime Broadcast or Postgres Changes for a presence feature?"
+    why: Non-obvious architecture choice — the right answer (default to Broadcast, Postgres Changes doesn't fan out) is Supabase-specific knowledge.
+  - prompt: "Write an Edge Function that inserts a row using the service role key."
+    why: Edge Functions plus the key trust boundary — when bypassing RLS with service_role is and isn't appropriate.
+  - prompt: "Is it safe to put the Supabase anon key in my client bundle?"
+    why: Non-obvious trust-boundary question — yes, but only because RLS gates rows; tests the core mental model.
+  - prompt: "Should I verify the Supabase JWT locally with getClaims or hit the Auth server with getUser to protect my server routes?"
+    why: Non-obvious 2026 decision — getClaims() is the documented default (local JWK verify, asymmetric keys); getUser() is the higher-cost fallback for live ban/delete detection.
+
+should_not_trigger:
+  - prompt: "Add a composite index and tune this slow Postgres query with EXPLAIN."
+    route_to: postgresdb
+    why: Engine-level query tuning with no Supabase layer.
+  - prompt: "Define my schema in TypeScript with Drizzle and run typed queries."
+    route_to: drizzle-orm
+    why: ORM-first data access; Drizzle can sit on top of Supabase Postgres but the question is about the ORM.
+  - prompt: "Write Firestore security rules for my Firebase app."
+    route_to: firebase
+    why: Different BaaS (Google) — Firestore rules, not Postgres RLS.
+  - prompt: "Why is my Next.js page not revalidating with the App Router cache?"
+    route_to: nextjs
+    why: Framework caching mechanics, not Supabase client/auth wiring.
+
+capability:
+  - scenario: "Design the data layer for a multi-tenant SaaS on Supabase: orgs, members, per-org rows, file uploads, and a Next.js frontend."
+    must_include:
+      - anon/publishable (browser, RLS-gated) vs service_role/secret (server-only, bypasses RLS) boundary
+      - "enable row level security on tables, policies scoped to authenticated"
+      - "wrapping auth.uid() as (select auth.uid()) and indexing policy columns"
+      - membership/team_id authorization via a security-definer helper or join (not a per-row correlated subquery)
+      - "@supabase/ssr browser + server clients, middleware token refresh, getClaims() not getSession() for server-side gating (getUser() only when live ban/delete detection is needed)"
+      - storage bucket RLS on storage.objects (private bucket + signed URLs)
+      - note that a table must be exposed to the data API or PostgREST returns empty results

package/skills/supabase/references/auth-ssr.md

@@ -0,0 +1,173 @@
+# Cookie-based Auth with @supabase/ssr (Next.js App Router)
+
+Full wiring for server-side auth. The package is `@supabase/ssr` (it replaced `@supabase/auth-helpers`).
+Three clients plus middleware; the rule everywhere is **`getClaims()` for authorization, never
+`getSession()`**. `getClaims()` verifies the JWT signature locally against your project's published
+public keys — the documented default since new projects sign with asymmetric keys (2025-10-01 onward).
+Keep `getUser()` as the strict, higher-cost fallback for when you need to catch a banned or deleted
+user mid-session (it round-trips to the Auth server on every call). On a legacy project still using a
+symmetric JWT secret, `getClaims()` transparently falls back to that same round-trip.
+
+## lib/supabase/client.ts (browser)
+
+```ts
+import { createBrowserClient } from "@supabase/ssr";
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+  );
+}
+```
+
+## lib/supabase/server.ts (Server Components / Route Handlers / Server Actions)
+
+```ts
+import { createServerClient } from "@supabase/ssr";
+import { cookies } from "next/headers";
+
+export async function createClient() {
+  const cookieStore = await cookies();
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll: () => cookieStore.getAll(),
+        setAll: (toSet) => {
+          try {
+            toSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options),
+            );
+          } catch {
+            // Called from a Server Component — cookies are read-only here.
+            // Safe to ignore: middleware refreshes the session.
+          }
+        },
+      },
+    },
+  );
+}
+```
+
+## middleware.ts (mandatory — refreshes expired tokens)
+
+Server Components can't write cookies, so the *only* place an expired access token gets refreshed is
+middleware. Without this, sessions silently expire mid-session.
+
+```ts
+import { createServerClient } from "@supabase/ssr";
+import { NextResponse, type NextRequest } from "next/server";
+
+export async function middleware(request: NextRequest) {
+  let response = NextResponse.next({ request });
+
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll: () => request.cookies.getAll(),
+        setAll: (toSet) => {
+          toSet.forEach(({ name, value }) => request.cookies.set(name, value));
+          response = NextResponse.next({ request });
+          toSet.forEach(({ name, value, options }) =>
+            response.cookies.set(name, value, options),
+          );
+        },
+      },
+    },
+  );
+
+  // IMPORTANT: getClaims() verifies the JWT signature locally (asymmetric keys,
+  // default for new projects) — the lower-latency default. Swap to getUser() only
+  // if you need strict per-request revalidation against the Auth server (live
+  // ban/delete detection). Do not put logic between createServerClient and this call.
+  const { data } = await supabase.auth.getClaims();
+  const user = data?.claims;
+
+  if (!user && !request.nextUrl.pathname.startsWith("/login")) {
+    const url = request.nextUrl.clone();
+    url.pathname = "/login";
+    return NextResponse.redirect(url);
+  }
+  return response;
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+## Server-action sign-in / sign-out
+
+```ts
+"use server";
+import { createClient } from "@/lib/supabase/server";
+import { redirect } from "next/navigation";
+
+export async function signIn(formData: FormData) {
+  const supabase = await createClient();
+  const { error } = await supabase.auth.signInWithPassword({
+    email: String(formData.get("email")),
+    password: String(formData.get("password")),
+  });
+  if (error) return { error: error.message };
+  redirect("/dashboard");
+}
+
+export async function signOut() {
+  const supabase = await createClient();
+  await supabase.auth.signOut();
+  redirect("/login");
+}
+```
+
+## OAuth + PKCE callback route
+
+OAuth (and magic-link) flows use PKCE: the provider redirects back with a `code` you exchange for a
+session. Add a route handler at `/auth/callback`.
+
+```ts
+import { createClient } from "@/lib/supabase/server";
+import { NextResponse } from "next/server";
+
+export async function GET(request: Request) {
+  const { searchParams, origin } = new URL(request.url);
+  const code = searchParams.get("code");
+  const next = searchParams.get("next") ?? "/";
+
+  if (code) {
+    const supabase = await createClient();
+    const { error } = await supabase.auth.exchangeCodeForSession(code);
+    if (!error) return NextResponse.redirect(`${origin}${next}`);
+  }
+  return NextResponse.redirect(`${origin}/auth/auth-code-error`);
+}
+```
+
+## Protecting a Server Component
+
+```ts
+const supabase = await createClient();
+const { data } = await supabase.auth.getClaims(); // local JWK verify; never getSession() here
+if (!data?.claims) redirect("/login");
+// Need to catch a just-banned/deleted user this request? Use getUser() instead (Auth round-trip).
+```
+
+## auth-helpers → @supabase/ssr migration checklist
+
+- Remove `@supabase/auth-helpers-nextjs`; install `@supabase/ssr`.
+- Replace `createClientComponentClient` → `createBrowserClient` (lib/supabase/client.ts).
+- Replace `createServerComponentClient` / `createRouteHandlerClient` → `createServerClient` with the
+  `getAll`/`setAll` cookie adapter (lib/supabase/server.ts).
+- Add `middleware.ts` for token refresh — this was implicit before and is now explicit.
+- Audit every server-side `getSession()` and switch authorization checks to `getClaims()` (keep
+  `getUser()` only where live ban/delete detection is required).
+
+## SvelteKit / Remix
+
+Same `@supabase/ssr` package and the same `getClaims()` rule. SvelteKit: create the server client in
+`hooks.server.ts`, refresh in the handle hook, expose via `event.locals`. Remix: create the client per
+request in the loader/action with the `getAll`/`setAll` adapter backed by Remix's cookie session.