better-supabase 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-supabase",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Strongly typed Supabase: generated schema, typed repositories, plugins, auth glue, framework integrations and the better-supabase CLI.",
   "keywords": [
     "cli",
@@ -106,6 +106,14 @@
       "types": "./dist/jobs/index.d.ts",
       "default": "./dist/jobs/index.js"
     },
+    "./orgs": {
+      "types": "./dist/orgs/index.d.ts",
+      "default": "./dist/orgs/index.js"
+    },
+    "./notifications": {
+      "types": "./dist/notifications/index.d.ts",
+      "default": "./dist/notifications/index.js"
+    },
     "./env": {
       "types": "./dist/env/index.d.ts",
       "default": "./dist/env/index.js"
@@ -182,12 +190,12 @@
     "provenance": true
   },
   "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"
+    "@standard-schema/spec": "^1.1.0",
+    "@supabase/middleware": "^1.0.0",
+    "@supabase/postgrest-js": "^2.116.0",
+    "@supabase/postgrest-typegen": "0.4.0",
+    "@supabase/server": "^1.9.0",
+    "@supabase/ssr": "^0.12.7"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
@@ -196,13 +204,13 @@
     "@clack/prompts": "1.8.1",
     "@effect/platform-node": "4.0.0",
     "@opentelemetry/api": "1.9.1",
-    "@orpc/server": "2.0.0-beta.40",
+    "@orpc/server": "2.0.0-beta.41",
     "@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": "26.6.3",
+    "@tanstack/query-core": "5.104.1",
+    "@tanstack/react-query": "5.104.1",
+    "@types/node": "26.6.4",
     "@types/pg": "8.23.1",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
@@ -220,7 +228,7 @@
     "oxfmt": "0.71.0",
     "oxlint": "1.86.0",
     "pg": "8.23.1",
-    "publint": "0.3.24",
+    "publint": "0.3.25",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "smol-toml": "1.9.0",
@@ -233,15 +241,15 @@
     "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@opentelemetry/api": ">=1.9",
-    "@orpc/server": ">=2.0.0-0",
+    "@opentelemetry/api": ">=1.9 <2",
+    "@orpc/server": ">=2.0.0-beta.40 <3",
     "@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",
+    "@tanstack/query-core": "^5.62.0",
+    "hono": ">=4 <5",
+    "next": ">=16 <17",
+    "oxfmt": ">=0.66.0 <1",
+    "pg": ">=8.15 <9",
     "react": "^19",
     "temporal-polyfill": ">=1"
   },

package/schemas/config-v1.json

@@ -292,7 +292,10 @@
               "type": "object",
               "additionalProperties": false,
               "properties": {
-                "scope": { "type": "string", "default": "organization" }
+                "scope": {
+                  "type": "string",
+                  "description": "The PermDock scope tenants are. Defaults to the manifest's root scope, the rls.scopes entry without within."
+                }
               }
             }
           ]
@@ -346,6 +349,11 @@
           "description": "Tables that broadcast change signals (`table` or `schema.table`). Install with `better-supabase sql add realtime-tables`.",
           "type": "array",
           "items": { "type": "string" }
+        },
+        "global": {
+          "description": "Tables in `tables` without a tenant column, which broadcast on one topic for every signed-in user.",
+          "type": "array",
+          "items": { "type": "string" }
         }
       }
     },
@@ -359,6 +367,14 @@
         "kit": { "type": "array", "items": { "type": "string" } }
       }
     },
+    "kits": {
+      "type": "object",
+      "description": "How each SQL kit module maps onto the database, keyed by module name.",
+      "properties": {
+        "access": { "$ref": "#/$defs/accessKit" }
+      },
+      "additionalProperties": { "$ref": "#/$defs/kitModule" }
+    },
     "seed": {
       "type": "object",
       "additionalProperties": false,
@@ -394,6 +410,120 @@
     }
   },
   "$defs": {
+    "stringRecord": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "kitModuleProperties": {
+      "mode": { "enum": ["managed", "adopt", "custom"], "default": "managed" },
+      "schema": { "type": "string", "default": "better_supabase" },
+      "tables": {
+        "type": "object",
+        "additionalProperties": { "type": ["string", "null"] }
+      },
+      "columns": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": { "type": ["string", "null"] }
+        }
+      },
+      "idType": { "type": "string" },
+      "triggerPrefix": { "type": "string", "default": "bs_" },
+      "permissions": { "$ref": "#/$defs/stringRecord" },
+      "options": { "type": "object" }
+    },
+    "kitModule": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "$ref": "#/$defs/kitModuleProperties/mode" },
+        "schema": { "$ref": "#/$defs/kitModuleProperties/schema" },
+        "tables": { "$ref": "#/$defs/kitModuleProperties/tables" },
+        "columns": { "$ref": "#/$defs/kitModuleProperties/columns" },
+        "idType": { "$ref": "#/$defs/kitModuleProperties/idType" },
+        "triggerPrefix": {
+          "$ref": "#/$defs/kitModuleProperties/triggerPrefix"
+        },
+        "permissions": { "$ref": "#/$defs/kitModuleProperties/permissions" },
+        "options": { "$ref": "#/$defs/kitModuleProperties/options" }
+      }
+    },
+    "accessKit": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "$ref": "#/$defs/kitModuleProperties/mode" },
+        "schema": { "$ref": "#/$defs/kitModuleProperties/schema" },
+        "tables": { "$ref": "#/$defs/kitModuleProperties/tables" },
+        "columns": { "$ref": "#/$defs/kitModuleProperties/columns" },
+        "idType": { "$ref": "#/$defs/kitModuleProperties/idType" },
+        "triggerPrefix": {
+          "$ref": "#/$defs/kitModuleProperties/triggerPrefix"
+        },
+        "permissions": { "$ref": "#/$defs/kitModuleProperties/permissions" },
+        "options": { "$ref": "#/$defs/kitModuleProperties/options" },
+        "model": {
+          "enum": ["roles", "catalog", "permdock", "custom"],
+          "default": "roles"
+        },
+        "roles": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "functions": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "can": { "type": "string" },
+            "tenantIdsWith": { "type": "string" },
+            "isPlatform": { "type": "string" },
+            "canUser": { "type": "string" },
+            "canAssign": { "type": "string" },
+            "permissionClaims": { "type": "string" }
+          }
+        },
+        "platformClaim": {
+          "type": "string",
+          "default": "platform_permissions"
+        },
+        "disabled": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tenant": { "type": "string" },
+            "tenantKey": { "type": "string" },
+            "user": { "type": "string" },
+            "userKey": { "type": "string" }
+          }
+        },
+        "activeTenant": {
+          "oneOf": [
+            { "enum": ["claim", "resolver"] },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["profileColumn"],
+              "properties": {
+                "profileColumn": { "type": "string" },
+                "key": { "type": "string" }
+              }
+            }
+          ]
+        },
+        "permdock": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "schema": { "type": "string" },
+            "scope": { "type": "string" }
+          }
+        }
+      }
+    },
     "casing": { "enum": ["snake", "camel"] },
     "privileges": {
       "type": "array",

package/schemas/doctor-report-v1.json

@@ -73,6 +73,14 @@
               "BS304",
               "BS305",
               "BS306",
+              "BS307",
+              "BS308",
+              "BS309",
+              "BS310",
+              "BS311",
+              "BS312",
+              "BS313",
+              "BS314",
               "BS401",
               "BS402",
               "BS403",
@@ -81,6 +89,9 @@
               "BS406",
               "BS407",
               "BS408",
+              "BS409",
+              "BS410",
+              "BS411",
               "BS501",
               "BS502"
             ]

package/skills/better-supabase/SKILL.md

@@ -53,16 +53,19 @@ 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
+1. Run `pnpm better-supabase codemod <version> --dry-run` for each minor
+   version you crossed (`codemod` without a name lists them), then without
+   `--dry-run`, and fix the lines it lists for review.
+2. Run `pnpm better-supabase sql upgrade`, so the kit modules get the
+   release's SQL and any forward steps land in a migration, then write a
+   migration from the changed files.
+3. 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
+4. Run `pnpm better-supabase skills install --check` and reinstall the skills
    when it reports them stale.
-4. Read the release's breaking changes in
+5. 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

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

@@ -53,9 +53,12 @@ filled it.
 RLS still decides what a user can read and write. `tenant()` makes queries
 explicit and fills the column; it doesn't replace the policy.
 
-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
+The tenant comes from `context.tenant`, which the server's `tenant` resolver
+sets per request (the default `kits.access.activeTenant: 'resolver'`), then
+the verified `tenant_id` claim (renamed with `claims.tenant` in
+`better-supabase.config.ts`), then `app_metadata.tenant_id`. A resolver may
+read the URL, but `current_tenant_id()` only returns a tenant the caller is a
+member of. Never trust a tenant from `user_metadata` 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`, and follow the PermDock reference of
 the `better-supabase-auth` skill

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

@@ -16,6 +16,7 @@ Branch on `result.error.kind`, not on the message.
 | `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                         |
 | `invalid_input`                                       | Postgres couldn't parse a value (bad uuid, enum)                               | Validate before the call                                                      |
+| `invalid_value`                                       | A stored value the app type can't hold (`infinity` in a Temporal timestamp)    | Store a real timestamp or `null`, or read the column without the codec        |
 | `validation`                                          | A Standard Schema rejected the input; see `issues`                             | Show the issues to the user                                                   |
 | `invalid_request`                                     | The query can't run over PostgREST (for example a relation filter on `update`) | Read the keys first, or use a database function or `better-supabase/postgres` |
 | `multiple_rows`                                       | `findUnique` or a single-row write matched more than one row                   | Filter by a unique key                                                        |

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

@@ -88,11 +88,18 @@ for lists that clients read page by page: the list takes `after` instead of
 
 ## 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).
+- `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, { timeZone })` uses pg_cron, or with `kits.jobs.options.scheduler: "drain"` a `jobs.drainRoute({ secret: process.env.CRON_SECRET, handlers })` route that Vercel Cron calls; `kits.jobs.options.backend: "table"` runs without pgmq. 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.
+- Schedule cleanup with pg_cron at a quiet hour: `better_supabase.purge_job_archive('<queue>')`, `purge_webhooks()`, `purge_audit_log()`, `purge_idempotency_keys()`, `purge_rate_limits()`, `purge_outbox()`, `purge_notifications()` and `purge_webhook_deliveries()`, for the modules you installed. Only `service_role` can execute them.
+- Audit a table with `better_supabase.audit('public.t', redact => '{secret}', event_prefix => 't')`; record non-row events with `better_supabase.audit_event(event_type, ...)` and an `idempotency_key`. For per-tenant retention, write an `audit_retention(tenant)` SQL function or call `purgeAuditLog(sql, { retention })` from `better-supabase/jobs`.
+- For a "view as user" support mode, add the `support-sessions` SQL module, pass `support: supportSessions({ store: sqlSupportStore(postgres) })` to `createServer`, call `bs.startSupport({ targetUserId, reason })` and `bs.stopSupport()` from server actions, and show a banner with `useSupportSession()`. Sessions are read-only by default; grant admins the `support.start` platform permission.
+- For teams, add the `organizations` and `invitations` SQL modules and call them through `createOrgs({ transport: sqlTransport(postgres.asUser(claims)), events: betterSupabase.events, onInvite })` from `better-supabase/orgs`. Send the invitation email in `onInvite`, show `previewInvitation(token)` on the accept page, and switch with `orgs.switch(id)`, refreshing the session when it returns `refresh: true`. Errors carry codes such as `ORG_SLUG_TAKEN` in `hint`. Existing tables work with `mode: 'adopt'`.
+- For user profiles, add the `profiles` SQL module: sign-up creates the row from auth metadata with a unique username and mirrors the email; users update only the `updatable` columns. Adopt an existing table with `mode: 'adopt'` and `syncTrigger: false` when your own trigger creates profiles. Use `avatarBucket()` and `orgLogoBucket()` from `better-supabase/storage` for uploads; `policy: { access: { read, write } }` checks any bucket through the access contract.
+- For events other systems must see, add the `outbox` SQL module and write events with `emit_event(type, payload, subject, tenant, key)` inside the same transaction as the change (the kit modules emit theirs automatically). Relay them with `createOutbox(postgres.admin, { source }).relayRoute({ secret, consumers: { name: httpSink(url) } })` from `better-supabase/jobs` after `outbox.register(name, { types })`. Delivery is at least once; receivers deduplicate on the CloudEvent `id`.
+- For in-app notifications, add the `notifications` SQL module and send with `createNotifications({ transport: sqlTransport(postgres.asUser(claims)), types })` from `better-supabase/notifications`, where `types` maps each notification type to a Standard Schema for its data. Pass a `key` so retries don't notify twice. Show them with `useNotifications({ topic, load })` from `better-supabase/react`; the topic defaults to `notifications:{userId}`. For email or push, pass `channels` and call `notifications.deliver()` from a cron route with a service connection.
+- For webhooks to customers' endpoints, add the `webhooks-out` SQL module and publish with `createWebhooks({ transport: sqlTransport(postgres.admin) }).publish({ type, data, tenant, id })` from `better-supabase/webhooks`. Pass an `id` so retries don't send twice. Send with `webhooks.deliverRoute({ secret: process.env.CRON_SECRET })` from a cron route; deliveries are signed with Standard Webhooks and only go to public HTTPS URLs by default.
 
 Done when a failing job is retried and then archived after `maxAttempts`,
 a replayed webhook or POST doesn't run twice, and each kit table has a purge

package/skills/better-supabase-api/references/adapters.md

@@ -15,6 +15,7 @@ export const betterSupabase = defineSupabase(schema);
 ## Next.js
 
 ```ts title="src/lib/supabase/server.ts"
+import "server-only";
 import { createNext } from "better-supabase/next";
 
 import { betterSupabase } from "./index";
@@ -44,15 +45,15 @@ export const GET = bs.route(
 ## Hono
 
 ```ts title="src/server.ts"
-import { type HonoEnv, createHono } from "better-supabase/hono";
-import { Hono } from "hono";
+import { createHono } from "better-supabase/hono";
 
-import { type Functions, type Models, betterSupabase } from "./lib/supabase";
+import { betterSupabase } from "./lib/supabase";
 
 const bs = createHono(betterSupabase);
 
-const app = new Hono<HonoEnv<Models, Functions, unknown>>()
-  .onError(bs.onError)
+// bs.app() is new Hono<typeof bs.Env>() with bs.onError installed.
+const app = bs
+  .app()
   .use("/api/*", bs.middleware())
   .get("/api/me", (c) => c.json({ kind: c.var.auth.kind }))
   .route(
@@ -106,7 +107,7 @@ import { betterSupabase } from "../_shared/supabase.ts";
 const bs = createMcp(betterSupabase, {
   name: "crm",
   version: "0.1.0",
-  scopes: ["openid", "crm.read"],
+  advertisedScopes: ["openid", "crm.read"],
   allowedOrigins: ["https://claude.ai"],
   allowedHosts: ["crm.example.com", "localhost"],
   resourceDocumentation: "https://crm.example.com/docs/mcp",
@@ -126,6 +127,8 @@ const bs = createMcp(betterSupabase, {
 Deno.serve(bs.fetch);
 ```
 
-Tools run as the calling user, so RLS applies to every tool call. `scopes`
-on `createMcp` only advertises scopes; `authorize` refuses the call. A
+Tools run as the calling user, so RLS applies to every tool call.
+`advertisedScopes` only advertises scopes; `requiredScopes` refuses delegated
+tokens that lack one, and `authorize` refuses a single call. The session comes
+from the `Authorization` header only, never from a cookie. A
 `delegation` that is unset means the user's own token, which no scope limits.

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

@@ -61,16 +61,22 @@ A token from the Supabase OAuth server carries `client_id` and `scope`; a
 token exchanged for an agent carries an RFC 8693 `act` chain. The session
 names who acts for the user:
 
-| Token                                           | `session.actor`                      | `session.delegation` |
-| ----------------------------------------------- | ------------------------------------ | -------------------- |
-| The user's own                                  | not set                              | not set              |
-| `client_id: "c1"`, `scope: "openid crm.read"`   | `{ id: "c1", kind: "oauth-client" }` | `{ scopes: [...] }`  |
-| `act: { sub: "agent", act: { sub: "mcp-42" } }` | `{ id: "agent", chain, ... }`        | `{ scopes, chain }`  |
+| Token                                            | `session.actor`                                | `session.delegation` |
+| ------------------------------------------------ | ---------------------------------------------- | -------------------- |
+| The user's own                                   | not set                                        | not set              |
+| `client_id: "c1"`, `scope: "openid crm.read"`    | `{ id: "c1", kind: "oauth-client" }`           | `{ scopes: [...] }`  |
+| `act: { sub: "agent", act: { sub: "mcp-42" } }`  | `{ id: "agent", chain, ... }`                  | `{ scopes, chain }`  |
+| `act: { kind: "support", sub, session_id, ... }` | `{ kind: "support", id, sessionId, readOnly }` | not set              |
+| `act: { kind: "impersonation", sub, reason }`    | `{ kind: "impersonation", id, reason }`        | not set              |
 
 - Limit what delegated tokens may do with the `scopes` guard option on
   `bs.route`, `bs.action`, `bs.handler` and `bs.middleware`. A missing
-  scope answers 403 with an `insufficient_scope` challenge. The user's own
-  token is never limited by scopes.
+  scope answers 403 with an `insufficient_scope` challenge. Only an
+  `oauth-client` actor is limited: the user's own token, a support session
+  and an impersonated session are not.
+- Switch on `session.actor.kind` with a `never` default: it is
+  `oauth-client`, `support` or `impersonation`. An `act` with another `kind`
+  resolves to `invalid` with reason `actor`.
 - In MCP servers, refuse calls in `authorize` by reading
   `toSession(ctx.auth).delegation?.scopes` (the `better-supabase-api` skill).
 - RLS still decides the rows: `sub` is the user, so a client sees at most
@@ -106,6 +112,9 @@ membership lasts until the next refresh. When that window matters:
 - Write policies that read the source of truth, for example
   `organization_id in (select better_supabase.member_org_ids())`, instead of
   the claim.
+- For signed-out, banned or deleted users, add the `sessions` SQL module and a
+  restrictive policy with `using ((select better_supabase.session_active()))`
+  on the tables that guard sensitive data.
 - After a change the user made themselves (joining an organization), call
   `supabase.auth.refreshSession()` in the browser.
 - In Next.js, drop the user's cached views with
@@ -136,6 +145,8 @@ claims, tenant or entitlements.
 - Don't downgrade an `invalid` caller to `anon`.
 - Don't build 401 or 403 JSON by hand; return the `DbError` or use `allow`
   and `scopes`.
+- Don't use `allow: ['anon']` for users from `signInAnonymously()`: `'anon'`
+  means no session, and only `'anonymous'` admits anonymous sign-ins.
 
 ## Docs
 

package/skills/better-supabase-auth/references/permdock.md

@@ -26,30 +26,97 @@ the other.
   `hasEntitlement(session, ...)` works.
 - Run `permdock supabase inspect --out` before `sql add entitlements`. With
   `permdock.manifest.json` present, the module reads PermDock's
-  `member_<scope>_ids` helpers and doesn't add `tenant`. Set
-  `entitlements.permdock: { scope }` in `better-supabase.config.ts` for a
-  scope other than `organization`.
+  `member_<scope>_ids` helpers and doesn't add `tenant`. The scope is the
+  manifest's root scope (the `rls.scopes` entry without `within`); set
+  `entitlements.permdock: { scope }` in `better-supabase.config.ts` for
+  another one.
 - Name the same tenant claim on both sides. A non-default `claims.tenant` in
   `better-supabase.config.ts` must also be PermDock's `rls.tenantClaim` and
   go to `subjectFromSupabase` or `subjectFromSupabaseSession` as `{ tenant }`.
 - Validate claims with PermDock's schema: `betterSupabase.claims(supabaseClaims().extend(appClaims))`.
-- The helpers live in PermDock's `rls.schema`, which must equal the `schema`
-  option of buckets and topics in `permdock` mode.
+- The helpers live in PermDock's `rls.schema` (`permdock` by default). Buckets
+  and topics in `permdock` mode call them in `permdock` unless their `schema`
+  option names another schema; it must equal `rls.schema`.
+- Use the scope names the manifest declares (`organization`, not PermDock's
+  `tenant` alias): the helpers are named after them, and doctor reports a
+  key checked at another scope than its catalog entry.
+- The entitlements module needs PermDock's hook to fill `claims.features`
+  from `better_supabase.feature_claims`
+  (`supabase.hook.claims: { features: 'better_supabase.feature_claims' }`).
 - The `permdock` policy mode checks role and scope only. Use it only for
   permissions whose `rowConditions` is `false` in `permissions.catalog.json`.
+  A missing flag or a key the catalog doesn't list is unknown and refused;
+  regenerate the catalog with a current `permdock catalog`.
   Leave permissions with row conditions to the policies
   `permdock rls generate` writes; doctor reports BS214 and `permdock doctor`
   PD037 otherwise.
 - `permdock` mode compares ids as text, so a path or topic segment must be
   the id's lowercase form.
 - In MCP servers, narrow `tool.meta` with PermDock's `isPermission`, answer
-  `visible` with `mayUse` and `authorize` with `can`. `can` decides without
-  a row, so check row-conditioned permissions inside `run` or rely on RLS.
-- In Next.js, cache the permission snapshot with
-  `bs.cached({ tags: [snapshotTag(userId)], life: cacheLifeFor(snapshot) })`
-  and drop it with `bs.invalidateSession(userId, { tags: [snapshotTag(userId)] })`
-  when a role or plan changes.
+  `visible` with `mayUse` and `authorize` with `can`. A tool without a
+  PermDock permission in `meta` is denied: `visible` returns `false` and
+  `authorize` returns `{ allowed: false }`. Use `decide` instead of `can` to
+  put the denial reason in the refusal. `can` decides without a row, so check
+  row-conditioned permissions inside `run` or rely on RLS.
+- In oRPC and Hono, pass the adapter's auth state to PermDock:
+  `createPermDock(policy, { subject: ({ context }) => subjectFromSupabaseSession(context.auth) })`
+  from `permdock/orpc`, or `(c) => subjectFromSupabaseSession(c.get("auth"))`
+  from `permdock/hono`. Fail closed: export one builder that takes a
+  permission (`(permission) => authed.use(pd.protect(permission))`, or the
+  route helper `[bs.middleware(), pd.protect(permission)]` in Hono), and don't
+  install `bs.middleware()` app-wide, so a route without a permission has no
+  `db`.
+- In Next.js, cache the permission snapshot in a `'use cache: private'`
+  loader. The user id and the snapshot only exist after `bs.cached()`
+  returns, so pass it the static tags only, then tag and time the entry from
+  inside the loader with Next.js's `cacheTag` and `cacheLife`:
+
+  ```ts
+  import { cacheLife, cacheTag } from "next/cache";
+  import { snapshotFor } from "permdock";
+  import { cacheLifeFor, snapshotTag } from "permdock/next";
+  import { subjectFromSupabaseSession } from "permdock/supabase";
+
+  export async function loadSnapshot(orgId: string) {
+    "use cache: private";
+    const { session } = await bs.cached({ tags: [`org:${orgId}`] });
+    const snapshot = snapshotFor(policy, subjectFromSupabaseSession(session), {
+      tenant: orgId,
+    });
+    if (session.kind === "user") cacheTag(snapshotTag(session.user.id));
+    cacheLife(cacheLifeFor(snapshot));
+    return snapshot;
+  }
+  ```
+
+  `bs.cached()` already caps the stale time at the token's expiry, and Next.js
+  keeps the smaller `stale` of the two `cacheLife` calls. When a role or plan
+  changes, drop the user's entries and the snapshot with
+  `bs.invalidateSession(userId, { tags: [snapshotTag(userId)] })`.
+
 - Doctor BS405 measures `memberships` plus `attrs` against PermDock's 1 KB
   budget and the whole token against 2 KB; run `doctor --as <user id>`.
+- For the SQL kit, set `kits.access.model: 'permdock'` and
+  `kits.access.functions.canAssign: 'permdock.permdock_can_assign({role}, {tenant}::text)'`
+  (use the manifest's `rls.schema`), then run `permdock supabase inspect --out`
+  before `sql add`. The kit reads the schema, the root scope and its id type
+  from `permdock.manifest.json`, and `sql add` stops instead of guessing when
+  the manifest can't give them. Every permission key the kit modules check
+  (`kitPermissionKeys` from `better-supabase/sql`) must be
+  `rowConditions: false` in `permissions.catalog.json`; map others with
+  `kits.<module>.permissions`. Doctor reports BS411.
+- Under that model `can_user()` and `member_can()` answer for the caller only
+  and raise SQLSTATE `0A000` for another user. Invitations skip the inviter
+  re-check at accept time and notifications don't filter recipients by read
+  permission; check both in the app when they matter.
+- The `act` claim says who acts: `kind: "support"` (support sessions,
+  `session.actor.kind === 'support'` with `sessionId` and `readOnly`),
+  `kind: "impersonation"` (`actingAs`), or no `kind` for an OAuth client or
+  agent chain (`oauth-client`, limited by `scopes`). Another `kind` makes the
+  session invalid. `session.impersonator` is set for the first two only.
+  `supabaseClaimFixtures` in `better-supabase/testing` has one token of each.
+- Only `allow: ['anonymous']` admits `signInAnonymously()` users; `'anon'`
+  means no session. Pair the default `allow` with PermDock's
+  `rls: { anonymousSignIns: 'deny' }` in `permdock.config.ts`.
 
 Docs: https://bettersupabase.com/docs/auth/permdock.md

package/dist/cli/gen-D5cLCULx.js

@@ -1,2 +0,0 @@
-import { n as genCommand } from "./gen-Ccn_p90L.js";
-export { genCommand };