better-supabase 0.3.0 → 0.4.0

package/dist/{webhooks-CAIFQSTM.js → webhooks-Bh_Jf_-l.js}

@@ -1,11 +1,11 @@
-import { n as dbError } from "./errors-Bl3rkOzo.js";
+import { n as dbError } from "./errors-L0xK41y_.js";
 import { n as nowInstant, r as optionalTemporal } from "./temporal-BwshQk0W.js";
-import { n as temporalMissing } from "./temporal-required-CMxeSVPo.js";
-import { i as ok, n as err } from "./result-DWXatkd6.js";
-import { i as toBase64, r as fromBase64 } from "./base64-CQeB1eSf.js";
-import { s as toApp } from "./shared-_6-uPL7E.js";
+import { n as temporalMissing } from "./temporal-required-CBNHT6ni.js";
+import { i as ok, n as err } from "./result-Bj6yt33D.js";
+import { i as toBase64, r as fromBase64 } from "./base64-D2gsioCY.js";
+import { s as toApp } from "./shared-DnoCdMDr.js";
 //#region src/webhooks/verify.ts
-const encoder = new TextEncoder();
+const encoder = /* @__PURE__ */ new TextEncoder();
 /** Accepts `whsec_…`, `v1,whsec_…` (Supabase Auth hooks) or raw base64. */
 function secretBytes(secret) {
 	const raw = secret.replace(/^v1,/, "").replace(/^whsec_/, "");
@@ -15,12 +15,31 @@ function secretBytes(secret) {
 		throw new TypeError("Webhook secret is not valid base64");
 	}
 }
+/** Secrets come from configuration, so a handful of keys suffice. */
+const keys = /* @__PURE__ */ new Map();
+function keyFor(secret) {
+	let key = keys.get(secret);
+	if (!key) {
+		key = crypto.subtle.importKey("raw", secretBytes(secret), {
+			name: "HMAC",
+			hash: "SHA-256"
+		}, false, ["sign", "verify"]);
+		if (keys.size < 16) {
+			keys.set(secret, key);
+			key.catch(() => keys.delete(secret));
+		}
+	}
+	return key;
+}
 async function signature(secret, content) {
-	const key = await crypto.subtle.importKey("raw", secretBytes(secret), {
-		name: "HMAC",
-		hash: "SHA-256"
-	}, false, ["sign"]);
-	return toBase64(new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(content))));
+	return toBase64(new Uint8Array(await crypto.subtle.sign("HMAC", await keyFor(secret), encoder.encode(content))));
+}
+function decodeSignature(value) {
+	try {
+		return fromBase64(value);
+	} catch {
+		return;
+	}
 }
 /** Constant-time string comparison. */
 function timingSafeEqual(a, b) {
@@ -51,7 +70,6 @@ async function signWebhook(secret, message) {
 */
 async function verifyWebhook(input, secrets, options = {}) {
 	const headers = input.headers;
-	const body = input instanceof Request ? await input.text() : input.body;
 	const id = header(headers, "webhook-id");
 	const timestamp = header(headers, "webhook-timestamp");
 	const signatures = header(headers, "webhook-signature");
@@ -64,12 +82,13 @@ async function verifyWebhook(input, secrets, options = {}) {
 	const tolerance = options.tolerance ?? 300;
 	if (seconds < now - tolerance) return err(unauthorized("WEBHOOK_TIMESTAMP_TOO_OLD", "Webhook timestamp is too old"));
 	if (seconds > now + tolerance) return err(unauthorized("WEBHOOK_TIMESTAMP_TOO_NEW", "Webhook timestamp is in the future"));
-	const content = `${id}.${timestamp}.${body}`;
-	const offered = signatures.split(" ").map((entry) => entry.split(",")).filter(([version, value]) => version === "v1" && value).map(([, value]) => value);
+	const body = input instanceof Request ? await input.text() : input.body;
+	const content = encoder.encode(`${id}.${timestamp}.${body}`);
+	const offered = signatures.split(" ").map((entry) => entry.split(",")).filter(([version, value]) => version === "v1" && value).flatMap(([, value]) => decodeSignature(value) ?? []);
 	let valid = false;
 	for (const secret of typeof secrets === "string" ? [secrets] : secrets) {
-		const expected = await signature(secret, content);
-		for (const candidate of offered) if (timingSafeEqual(candidate, expected)) valid = true;
+		const key = await keyFor(secret);
+		for (const candidate of offered) if (await crypto.subtle.verify("HMAC", key, candidate, content)) valid = true;
 	}
 	if (!valid) return err(unauthorized("WEBHOOK_INVALID_SIGNATURE", "Invalid webhook signature"));
 	try {
@@ -127,8 +146,8 @@ function isDatabaseWebhook(value) {
 * Reads a database webhook payload for `table` as an app-cased change.
 * Returns `null` for other tables or payloads that aren't database webhooks.
 */
-function databaseChange(sb, table, payload) {
-	const meta = sb.meta.tables[table];
+function databaseChange(betterSupabase, table, payload) {
+	const meta = betterSupabase.meta.tables[table];
 	if (!meta || !isDatabaseWebhook(payload) || payload.table !== meta.name || payload.schema !== meta.schema) return null;
 	return {
 		type: payload.type,

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "better-supabase",
-  "version": "0.3.0",
-  "description": "Strongly typed Supabase: generated schema, typed repositories, plugins, auth glue and framework integrations. The CLI ships as @better-supabase/cli.",
+  "version": "0.4.0",
+  "description": "Strongly typed Supabase: generated schema, typed repositories, plugins, auth glue, framework integrations and the better-supabase CLI.",
   "keywords": [
+    "cli",
+    "codegen",
     "hono",
     "mcp",
     "nextjs",
@@ -25,7 +27,11 @@
     "url": "git+https://github.com/ScaleDockHQ/better-supabase.git",
     "directory": "packages/better-supabase"
   },
+  "bin": {
+    "better-supabase": "./bin/better-supabase.js"
+  },
   "files": [
+    "bin",
     "dist",
     "schemas",
     "skills",
@@ -43,6 +49,10 @@
       "types": "./dist/config/index.d.ts",
       "default": "./dist/config/index.js"
     },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "default": "./dist/client/index.js"
@@ -174,6 +184,7 @@
   "dependencies": {
     "@standard-schema/spec": "1.1.0",
     "@supabase/middleware": "1.0.0",
+    "@supabase/postgrest-js": "2.117.2",
     "@supabase/postgrest-typegen": "0.3.1",
     "@supabase/server": "1.9.0",
     "@supabase/ssr": "0.12.7"
@@ -182,12 +193,16 @@
     "@arethetypeswrong/cli": "0.18.5",
     "@better-supabase/ox-config": "0.0.0",
     "@better-supabase/typescript-config": "0.0.0",
+    "@clack/prompts": "1.8.1",
+    "@effect/platform-node": "4.0.0",
     "@opentelemetry/api": "1.9.1",
     "@orpc/server": "2.0.0-beta.40",
+    "@supabase/config": "0.11.1",
     "@supabase/supabase-js": "2.117.2",
+    "@t3-oss/env-core": "0.13.11",
     "@tanstack/query-core": "5.104.0",
     "@tanstack/react-query": "5.104.0",
-    "@types/node": "24.19.0",
+    "@types/node": "26.6.3",
     "@types/pg": "8.23.1",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
@@ -195,14 +210,22 @@
     "@vitest/coverage-v8": "5.0.3",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
+    "c12": "4.0.0-rc.2",
+    "citty": "0.2.2",
+    "diff": "9.0.0",
+    "effect": "4.0.0",
+    "fastest-levenshtein": "1.0.16",
     "hono": "4.13.12",
     "next": "16.3.8",
+    "oxfmt": "0.71.0",
     "oxlint": "1.86.0",
     "pg": "8.23.1",
     "publint": "0.3.24",
     "react": "19.3.0",
     "react-dom": "19.3.0",
+    "smol-toml": "1.9.0",
     "temporal-polyfill": "1.0.5",
+    "tinyexec": "1.3.1",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",
     "valibot": "1.5.0",
@@ -212,10 +235,12 @@
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9",
     "@orpc/server": ">=2.0.0-0",
+    "@supabase/config": ">=0.9.0 <0.12",
     "@supabase/supabase-js": "^2.116.0",
     "@tanstack/query-core": "^5",
     "hono": ">=4",
     "next": ">=16",
+    "oxfmt": ">=0.66",
     "pg": ">=8",
     "react": "^19",
     "temporal-polyfill": ">=1"
@@ -227,6 +252,9 @@
     "@orpc/server": {
       "optional": true
     },
+    "@supabase/config": {
+      "optional": true
+    },
     "@tanstack/query-core": {
       "optional": true
     },
@@ -236,6 +264,9 @@
     "next": {
       "optional": true
     },
+    "oxfmt": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     },
@@ -253,8 +284,9 @@
     "bench": "node tests/next/next.bench.ts",
     "build": "tsdown",
     "check:publish": "publint && pnpm pack --out pack.tgz && attw --profile esm-only pack.tgz && rm -f pack.tgz",
+    "gen:fixtures": "node scripts/gen-fixtures.ts",
     "lint": "oxlint",
-    "test": "vitest run --coverage",
+    "test": "vitest run --project unit --coverage",
     "transit": "true",
     "typecheck": "tsc --noEmit"
   }

package/skills/better-supabase/SKILL.md

@@ -1,14 +1,18 @@
 ---
 name: better-supabase
-description: Query and write Supabase data with better-supabase's typed repositories, Results and codegen. Use when code imports better-supabase, when adding a table, query or mutation, or when a Supabase type is out of date.
+description: Query and write Supabase data with better-supabase's typed repositories, Results and codegen. Use when code imports better-supabase, when adding a table, query or mutation, when a Supabase type is out of date, or after upgrading better-supabase.
 ---
 
 # better-supabase
 
-The data layer is `sb = defineSupabase(schema)` in `src/lib/supabase.ts`.
+The data layer is `betterSupabase = defineSupabase(schema)` in `src/lib/supabase/index.ts`.
 `schema` comes from the generated module (`config.output`, usually
 `src/lib/supabase/generated.ts`). Never edit generated files.
 
+The `better-supabase` command ships in the `better-supabase` package, so
+`pnpm better-supabase <command>` works once the package is installed. There
+is no separate CLI package to add.
+
 ## Workflow: change the schema
 
 1. Write the migration: edit `supabase/schemas/*.sql`, then run
@@ -18,15 +22,18 @@ The data layer is `sb = defineSupabase(schema)` in `src/lib/supabase.ts`.
    data and role settings.
 2. For a new table in an exposed schema, in the same file: `enable row level
 security`, a policy per role and command the app uses, and an index on
-   every column a policy filters by. List the table in `expose` in
+   every column a policy filters by. Write tenant checks as
+   `organization_id in (select better_supabase.member_org_ids())`, which
+   Postgres runs once per statement, not `has_org_role(organization_id)`,
+   which runs once per row. List the table in `expose` in
    `better-supabase.config.ts` and run `pnpm better-supabase sql add grants`:
    new tables get no Data API grants on their own.
 3. Apply it with `supabase db reset` (or `supabase migration up`).
 4. Run `pnpm better-supabase gen`, then fix the type errors it surfaces.
-   The command comes from the `@better-supabase/cli` dev dependency.
 5. Run `pnpm better-supabase doctor` and fix every error it reports (RLS off,
    missing policies, missing grants, unindexed foreign keys, drift).
-6. Commit the generated files. CI runs `better-supabase gen --check`.
+6. Commit the generated files. CI runs `better-supabase gen --check`, which
+   prints a diff of each stale file.
 
 Done when `gen --check` and `doctor` exit 0 and the project typechecks.
 
@@ -44,14 +51,39 @@ Done when the call typechecks without casts, the error path returns the
 `DbError` (not a thrown exception), and a test shows another tenant's rows
 stay hidden.
 
+## Workflow: after upgrading better-supabase
+
+1. Rerun `pnpm better-supabase sql add` with the kit modules the project
+   installed, so their SQL gets the release's fixes, then write a migration
+   from the changed files.
+2. Run `pnpm better-supabase gen` and commit the result. Since 0.3, a
+   composite foreign key such as `(customer_id, organization_id)` is named
+   after the remaining column (`customer`); set `tables.<name>.relations` in
+   the config to keep an old relation name.
+3. Run `pnpm better-supabase skills install --check` and reinstall the skills
+   when it reports them stale.
+4. Read the release's breaking changes in
+   https://github.com/ScaleDockHQ/better-supabase/blob/main/CHANGELOG.md
+   (guides live under https://bettersupabase.com/docs/migration). For 0.3: time values are
+   `Temporal` (see below), `--db-url` is gone, `doctor --format json` is
+   `doctor --json`, `BetterResultShape` is `BetterResultValue`, and an
+   exhaustive `switch` over the `invalid` auth reason needs an `'actor'` case.
+
+Done when `gen --check`, `doctor` and the typecheck pass.
+
 ## Where `db` comes from
 
-- Next.js: `const { db } = await next.server()`, `next.route(...)`, `next.action(...)`
-- Next.js Cache Components: keep layouts synchronous; read `next.session()` in a `'use cache: private'` function inside `<Suspense>`, pass the promise to `<SessionProvider>` and read it with `useSession()`
+Name the definition `betterSupabase` (in `lib/supabase/index.ts`) and every runtime instance `bs` (`lib/supabase/server.ts`, `lib/supabase/client.ts`, or the Hono, oRPC or Edge Function entry).
+
+- Next.js: `const { db } = await bs.context()`, `bs.route(...)`, `bs.action(...)`
+- Next.js Cache Components: keep layouts synchronous; read `bs.session()` in a `'use cache: private'` function inside `<Suspense>`, pass the promise to `<SessionProvider>` and read it with `useSession()`
 - Hono: `c.var.db` after `bs.middleware()`
 - oRPC: `context.db` after `bs.middleware()`
 - Edge Functions: `bs.handler((request, { db }) => ...)`
-- Browser: `browser.db`, or the hooks from `createHooks<typeof browser>()`
+- Browser: `bs.db`, or the hooks from `createHooks<typeof bs>()`
+
+For who the caller is (sessions, claims, OAuth clients, agents, scopes), use
+the `better-supabase-auth` skill.
 
 ## Querying
 
@@ -68,18 +100,33 @@ const customers = result.data;
 ```
 
 - Methods return a `Result`, and database errors never throw. Use `.orThrow()` only where an exception is really wanted.
-- Column names use the configured casing (`casing: 'camel'` means `organizationId`). Raw escape hatches (`$client`, `$sql`) use database names.
+- Column names use the configured casing (`casing: 'camel'` means `organizationId`). Raw escape hatches (`$client`, and `queryRaw` on the `better-supabase/postgres` clients) use database names.
 - Writes: `create`, `createMany`, `update(id, patch)`, `updateMany`, `upsert`, `delete`.
+- Page lists with a cursor: `paginate({ after: null, size: 25, orderBy })`, then pass `nextCursor` back as `after` with the same `orderBy` and `where`. Use `page` numbers only when users jump to a page and need a total.
 - Handlers may return a `Result` directly. Adapters turn errors into RFC 9457 Problem Details with the right status.
-- Server-only admin access: `server.admin()`. Only use it for trusted jobs, never for a user's request.
+- Server-only admin access: `bs.admin()`. Only use it for trusted jobs, never for a user's request.
 - PostgREST has no multi-request transactions. Put multi-step writes in a database function (`db.$rpc()`) or use `postgres.transaction()` on the server.
 
+## Time values
+
+- With `codecs: { timestamptz: 'instant' }` in the config, `timestamptz` columns decode to `Temporal.Instant` and `timestamp` columns to `Temporal.PlainDateTime`, with microseconds. Without the codec they stay ISO strings.
+- `now` options, job and webhook timestamps and `bucket.sweep({ olderThan })` take `Temporal` values. Auth's `now` stays in epoch milliseconds.
+- On Node 24, Safari and other runtimes without `Temporal`, add `temporal-polyfill` and `import "temporal-polyfill/global"` once at startup. Without it, calls that need `Temporal` return an `unexpected` `DbError` that names the import.
+- Use TypeScript 6 or 7; 5.9 has no Temporal lib.
+
+## CLI in scripts and CI
+
+- No command takes a connection string as an argument. Set `$DATABASE_URL` or `source.dbUrl`, or pipe it in with `--db-url-stdin`.
+- `--json` prints one JSON document on stdout: the result, or Problem Details with a `code` on failure. `--yes` and `CI` turn prompts off.
+- Exit codes: 0 success, 1 a failure or finding (`--check` drift, doctor errors), 2 a usage, config or environment problem. Each error code is listed at https://bettersupabase.com/docs/cli/errors.
+
 ## Don't
 
 - Don't create supabase-js clients by hand, and don't read cookies yourself. Use the adapters.
 - Don't add `declare module` augmentation for types; everything comes from `schema`.
 - Don't catch and swallow `DbError`; return it, or map it with `mapDbError`.
 - Don't cast rows (`as Customer`). If a type is wrong, the schema or the generated file is out of date: rerun `gen`.
+- Don't convert `Temporal` values to `Date` to compare them; use `.equals()` or `Temporal.Instant.compare`.
 
 ## When something fails
 

package/skills/better-supabase/references/plugins.md

@@ -1,6 +1,6 @@
 # Plugins
 
-```ts title="src/lib/supabase.ts"
+```ts title="src/lib/supabase/index.ts"
 import { defineSupabase } from "better-supabase";
 import { actor } from "better-supabase/plugins/actor";
 import { softDelete } from "better-supabase/plugins/soft-delete";
@@ -8,10 +8,10 @@ import { tenant } from "better-supabase/plugins/tenant";
 import { timestamps } from "better-supabase/plugins/timestamps";
 import { validation } from "better-supabase/plugins/validation";
 
-import { schema } from "./supabase/generated.ts";
-import { validators } from "./supabase/generated.zod.ts";
+import { schema } from "./generated.ts";
+import { validators } from "./generated.zod.ts";
 
-export const sb = defineSupabase(schema)
+export const betterSupabase = defineSupabase(schema)
   .use(timestamps())
   .use(softDelete())
   .use(tenant())
@@ -57,12 +57,8 @@ The tenant comes from the verified `tenant_id` claim (renamed with
 `claims.tenant` in `better-supabase.config.ts`), then `app_metadata.tenant_id`.
 Never read it from `user_metadata`, a URL or a request body. When the project
 has a `permdock.config.ts`, PermDock's hook writes that claim and the
-memberships; don't run `sql add tenant` there or call `membership_claims()`
-from a hook. `sql add entitlements` is fine: `features` is not a PermDock
-claim. Add `claims: { features: 'better_supabase.feature_claims' }` to
-`supabase.hook` in `permdock.config.ts`, run `permdock supabase hook generate`,
-and `hasEntitlement(session, ...)` works. Run `permdock supabase inspect --out`
-first: with `permdock.manifest.json` present, the entitlements module reads
-PermDock's `member_<scope>_ids` helpers and doesn't add `tenant`.
+memberships: don't run `sql add tenant`, and follow the PermDock reference of
+the `better-supabase-auth` skill
+(https://bettersupabase.com/docs/auth/permdock.md).
 
 Docs: https://bettersupabase.com/docs/plugins.md

package/skills/better-supabase/references/troubleshooting.md

@@ -11,7 +11,7 @@ Branch on `result.error.kind`, not on the message.
 | ----------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
 | `not_found`                                           | The row doesn't exist, or RLS hides it from this user                          | Check the policy with an `asUser` test before assuming the row is gone        |
 | `unauthorized`                                        | No valid session or token                                                      | Get `db` from the adapter for this request                                    |
-| `forbidden`                                           | RLS or a grant rejected the write                                              | Fix the policy or the grant; don't switch to `server.admin()`                 |
+| `forbidden`                                           | RLS or a grant rejected the write                                              | Fix the policy or the grant; don't switch to `bs.admin()`                     |
 | `conflict`                                            | Unique violation                                                               | Use `upsert`, or return the error to the caller                               |
 | `foreign_key`                                         | Referenced row missing, or still referenced on delete                          | Create the parent first, or delete children                                   |
 | `not_null`, `check`, `exclusion`                      | A constraint rejected the row                                                  | Validate input earlier with the `validation()` plugin                         |
@@ -22,18 +22,38 @@ Branch on `result.error.kind`, not on the message.
 | `stale`                                               | `update(..., { expect })` found a newer row                                    | Reload the row and retry                                                      |
 | `serialization`, `timeout`, `network`, `rate_limited` | Transient                                                                      | Retry with backoff, or surface the error                                      |
 | `raised`                                              | A database function raised an exception                                        | Read `message` and `code` from the function                                   |
+| `unexpected` naming `temporal-polyfill/global`        | The runtime has no `Temporal` (Node 24, Safari)                                | Install `temporal-polyfill` and import `temporal-polyfill/global` at startup  |
+
+## By error `code`
+
+| Code                             | Meaning                                                                    | Fix                                                                                        |
+| -------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `CLAIMS_INVALID` (unauthorized)  | The token verified but failed the `betterSupabase.claims(schema)` schema   | Fix the access token hook or loosen the schema; the error names the failing paths          |
+| `SESSION_REVOKED` (unauthorized) | `checkSession` found the session gone (signed out, or ended by an admin)   | Expected for irreversible actions; ask the user to sign in again                           |
+| `INSUFFICIENT_SCOPE` (forbidden) | A delegated token (OAuth client or agent) lacks a scope the route requires | The 403 carries an `insufficient_scope` challenge; the client asks the user for that scope |
 
 ## Other symptoms
 
 - Types don't match the database: run `pnpm better-supabase gen`, then
   `gen --check` in CI.
 - A column name is `snake_case` in one place and `camelCase` in another:
-  repositories use the configured casing, `$client` and `$sql` use database
-  names.
+  repositories use the configured casing, `$client` and `queryRaw` use
+  database names.
 - Every request calls the Auth server: the token is being refreshed outside
-  the proxy. Refresh happens only in the Next.js proxy (`next.proxy`).
+  the proxy. Refresh happens only in the Next.js proxy (`bs.proxy`).
 - Tests pass with the service role but fail as a user: that's the RLS policy.
   Test as users, never with the service role.
+- A relation name changed after `gen`: a composite foreign key that repeats a
+  column on both sides is named after the remaining column. Set
+  `tables.<name>.relations` in the config to keep the old name.
+- The CLI exits with 2: the command line, the config or an environment
+  variable needs a change. Rerun with `--json` to get the error `code`, and
+  look it up at https://bettersupabase.com/docs/cli/errors.
+- `--db-url` is rejected: set `$DATABASE_URL` or pipe the URL in with
+  `--db-url-stdin`.
+- Two different `Temporal.Instant` values compare equal in `toEqual`: compare
+  with `.equals()` or register an equality tester (the
+  `better-supabase-testing` skill).
 
 Docs: https://bettersupabase.com/docs/cli/doctor.md and
 https://bettersupabase.com/docs/guides/limitations.md

package/skills/better-supabase-api/SKILL.md

@@ -1,28 +1,32 @@
 ---
 name: better-supabase-api
-description: Build HTTP APIs, Edge Functions and MCP servers on Supabase with better-supabase adapters. Use when adding a route, REST resource, oRPC procedure, Edge Function, MCP tool, webhook, background job or idempotent endpoint.
+description: Build HTTP APIs, Edge Functions and MCP servers on Supabase with better-supabase adapters. Use when adding a route, REST resource, oRPC procedure, Edge Function, MCP tool, OAuth or agent scopes, webhook, background job, cleanup cron or idempotent endpoint.
 ---
 
 # APIs with better-supabase
 
 Every adapter resolves the caller once and hands you `{ auth, db, supabase }`.
-`auth.kind` is `user`, `anon`, `service` or `invalid`.
+`auth.kind` is `user`, `anon`, `service` or `invalid`. For sessions, claims
+and the OAuth client or agent behind a token, see the `better-supabase-auth`
+skill.
 
 ## Workflow: add an endpoint
 
 1. Pick the adapter for the runtime (table below). Setup code for each is in
    [references/adapters.md](references/adapters.md).
-2. Decide who may call it with `allow` (see below).
+2. Decide who may call it with `allow`, and which scopes a delegated token
+   needs with `scopes` (see below).
 3. Use `db` from the handler context and return its `Result`, a plain value
    or a `Response`.
 4. For a table exposed as REST, prefer `bs.resource(...)` over hand-written
    routes, and regenerate `openapi.json` with `better-supabase openapi emit`.
-5. Add an API test that calls the endpoint as a user and as another tenant
-   (the `better-supabase-testing` skill).
+5. Add an API test that calls the endpoint as a user and as another tenant,
+   and with a delegated token that lacks the scope (the
+   `better-supabase-testing` skill).
 
-Done when the endpoint rejects callers outside `allow`, errors come back as
-Problem Details (no hand-built error JSON), and `openapi emit --check` passes
-if the project has an OpenAPI file.
+Done when the endpoint rejects callers outside `allow` and tokens without its
+`scopes`, errors come back as Problem Details (no hand-built error JSON), and
+`openapi emit --check` passes if the project has an OpenAPI file.
 
 ## Who gets in
 
@@ -30,15 +34,36 @@ if the project has an OpenAPI file.
 and `['service']` for machine callers. Rejected callers get a 401 with a
 `WWW-Authenticate` header, or a 403, as Problem Details.
 
+`scopes` limits what a delegated token may do: a token from the Supabase
+OAuth server (`client_id` and `scope`) or one exchanged for an agent (an
+RFC 8693 `act` chain). The guard options of `bs.route`, `bs.action`,
+`bs.handler` (edge) and `bs.middleware` (Hono, oRPC) take it, next to
+`allow`:
+
+```ts
+export const GET = bs.route(
+  (request, { db }) => db.customers.findMany({ limit: 20 }),
+  { scopes: ["customers:read"] },
+);
+```
+
+With `.claims(schema)` on the definition, `auth.claims` is typed in every
+adapter (`c.var.auth`, `context.auth`, the edge handler's `auth`, MCP's
+`ctx.auth`). Read roles from it; don't parse the claims again.
+
+A token without the scope gets a 403 with an `insufficient_scope`
+challenge. The user's own session holds no `client_id` or `act`, so `scopes`
+never limits it. RLS still decides the rows: the token's `sub` is the user.
+
 ## Adapters
 
-| Where          | Setup                                               | Handler                                                                                      |
-| -------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Next.js        | `createNext(sb)` in `lib/supabase.server.ts`        | `next.route((req, { db }) => ...)`, `next.action({ input: schema }, (input, { db }) => ...)` |
-| Hono           | `createHono(sb)`, `.use('/api/*', bs.middleware())` | `c.var.db`; `bs.resource('customers', {...})` for REST                                       |
-| oRPC           | `createOrpc(sb)`, `base.use(bs.middleware())`       | `bs.unwrap(context.db.customers.findMany(...))`                                              |
-| Edge Functions | `createEdge(sb, { cors: true })`                    | `Deno.serve(bs.handler((req, { db }) => ...))`                                               |
-| MCP            | `createMcp(sb, { name, version, resources })`       | `.tool({ name, input, run: (args, { db }) => ... })`                                         |
+| Where          | Setup                                                           | Handler                                                                                  |
+| -------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Next.js        | `createNext(betterSupabase)` in `lib/supabase/server.ts`        | `bs.route((req, { db }) => ...)`, `bs.action({ input: schema }, (input, { db }) => ...)` |
+| Hono           | `createHono(betterSupabase)`, `.use('/api/*', bs.middleware())` | `c.var.db`; `bs.resource('customers', {...})` for REST                                   |
+| oRPC           | `createOrpc(betterSupabase)`, `base.use(bs.middleware())`       | `bs.unwrap(context.db.customers.findMany(...))`                                          |
+| Edge Functions | `createEdge(betterSupabase, { cors: true })`                    | `Deno.serve(bs.handler((req, { db }) => ...))`                                           |
+| MCP            | `createMcp(betterSupabase, { name, version, resources })`       | `.tool({ name, input, run: (args, { db }) => ... })`                                     |
 
 Don't build error JSON by hand; errors become Problem Details.
 
@@ -46,17 +71,38 @@ Don't build error JSON by hand; errors become Problem Details.
 
 `defineResource` / `bs.resource(table, { operations, list, input })` gives you
 list, get, create, update and delete, with validation and paging (`{ items, page }`).
-`createOpenApi(sb, { resources })` describes the same routes, and
+`createOpenApi(betterSupabase, { resources })` describes the same routes, and
 `better-supabase openapi emit --check` keeps `openapi.json` in sync.
 
+Pass `pagination: "cursor"` to a resource, `defineListQuery` or an MCP table
+for lists that clients read page by page: the list takes `after` instead of
+`page`, returns `nextCursor` and `hasMore`, and `size` stays capped by
+`maxPageSize`. The OpenAPI document and the JSON Schema describe the cursor.
+
+## MCP servers
+
+- Tools run as the calling user, so RLS applies to every call.
+- `authorize(ctx, tool, args)` refuses a call (`{ allowed: false, reason, scopes }`; with `scopes` it is a 403 `insufficient_scope`). `visible(ctx, tool)` hides tools from `tools/list`. Put a permission or a label in a tool's `meta`; clients never see it.
+- `scopes` on `createMcp` only advertises scopes. Refuse calls in `authorize`, reading `toSession(ctx.auth).delegation?.scopes`.
+- Set `allowedOrigins` and `allowedHosts` (every host the server answers on, previews and local included) against DNS rebinding, and `resourceDocumentation` to a page that explains how to connect.
+
 ## Background work (`better-supabase/jobs`, needs `sql add jobs idempotency webhook-inbox`)
 
 - `createJobs(postgres.admin, { queue_name: zodSchema })` runs on Supabase Queues (pgmq): `enqueue` in the request, then `work` or `drain` in a worker. The handler throws to retry. `schedule(name, cron, queue, payload)` uses pg_cron. Queue names are lowercase letters, digits and underscores. With a service-role Supabase client instead of SQL, it uses the `pgmq_public` RPCs (no dedupe or schedules).
 - `createIdempotency(postgres.admin).handle(request, handler)` for POST endpoints that clients retry.
 - `createInbox(postgres.admin, { source, secrets }).receive(request)` for webhooks; `process(handler)` later.
+- Times are `Temporal.Instant`: `EnqueueOptions.runAt`, `Job.enqueuedAt`, `Job.visibleUntil`, `InboxMessage.receivedAt` and webhook timestamps.
+- Schedule cleanup with pg_cron at a quiet hour: `better_supabase.purge_job_archive('<queue>')`, `purge_webhooks()`, `purge_audit_log()` and `purge_idempotency_keys()`. Only `service_role` can execute them.
 
 Done when a failing job is retried and then archived after `maxAttempts`,
-and a replayed webhook or POST doesn't run twice.
+a replayed webhook or POST doesn't run twice, and each kit table has a purge
+schedule.
+
+## Direct Postgres on the server
+
+- `createPostgres()` opens a pool; `createPostgres({ pool })` runs on an existing `pg.Pool`. `asUser` and `anon` transactions get Supabase's role timeouts (8 s and 3 s); `statementTimeout` takes a number or `{ admin, authenticated, anon }`.
+- `createMany` and `upsertMany` split inserts past 65,535 bind parameters into several statements in one transaction, so large batches don't need manual chunking.
+- In serverless functions, connect through the transaction pooler (port 6543), not a direct connection.
 
 ## Testing
 
@@ -64,4 +110,6 @@ Sign tokens with `signLocalJwt` or `asUser` from `better-supabase/testing`;
 the adapter verifies them against the local JWKS. See the `better-supabase-testing` skill.
 
 Docs: https://bettersupabase.com/docs/frameworks/hono.md (and `next`,
-`orpc`, `edge`, `mcp` under `/docs/frameworks/`).
+`orpc`, `edge`, `mcp` under `/docs/frameworks/`),
+https://bettersupabase.com/docs/kits/jobs.md and
+https://bettersupabase.com/docs/auth/postgres.md.