better-supabase 0.7.1 → 0.9.0

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

@@ -19,14 +19,14 @@ skill.
 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`.
+   routes, and regenerate `openapi.json` with `better-supabase spec emit openapi`.
 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` 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.
+`spec emit openapi --check` passes if the project has an OpenAPI file.
 
 ## Who gets in
 
@@ -82,7 +82,7 @@ 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(betterSupabase, { resources })` describes the same routes, and
-`better-supabase openapi emit --check` keeps `openapi.json` in sync.
+`better-supabase spec emit openapi --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
@@ -97,7 +97,7 @@ for lists that clients read page by page: the list takes `after` instead of
 - 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.
 - On the official MCP SDK, keep its `McpServer`: `createMcpAuth(betterSupabase, { resource })` from `better-supabase/mcp/sdk` verifies the token and serves the metadata (`auth.serve(createMcpHandler(factory))`), and `withBetterSupabaseMcp(server, auth)` gives every `registerTool` callback `db`, `auth` and `bs`. With a permission library that wraps `McpServer`, wrap with it first, then `withBetterSupabaseMcp`.
 
-## AI chat (`sql add ai-chat`; `ai`, `@ai-sdk/react`, `@ai-sdk/workflow` and `workflow` as optional peers)
+## AI chat (`add ai-chat`; `ai`, `@ai-sdk/react`, `@ai-sdk/workflow` and `workflow` as optional peers)
 
 - Store chats with `createAiChat({ transport, service })` from `better-supabase/blocks/ai-chat`: `transport` calls as the user, `service` as the service role for assistant messages, runs and the model catalog. Never write assistant messages from the client.
 - Serve the chat with `createAssistant({ streams, run, defaultModel, quota })` from `better-supabase/ai-sdk/chat`: `respond` on `POST /api/chat`, `resume` on `GET /api/chat/[id]/stream`, `stop` on `POST /api/chat/[id]/stop`. Return `streamText(...)` from `run` with the `messages`, `abortSignal` and `providerOptions` it receives, and pass `waitUntil` (`after` in Next.js) so the answer is stored after the response.
@@ -130,27 +130,27 @@ server loaders for the web, `better-supabase/client/native` on the device.
 To read and write offline, run the same repositories on a PowerSync database
 and upload through `bs.db`, as in [references/powersync.md](references/powersync.md).
 
-## Background work (`better-supabase/blocks/jobs`, needs `sql add jobs idempotency webhook-inbox`)
+## Background work (`better-supabase/blocks/jobs`, needs `add jobs idempotency webhook-inbox`)
 
-- `createJobs(postgres.admin, { queue_name: zodSchema })` runs on Supabase Queues (pgmq): `enqueue(queue, payload, { context: db.$context })` in the request, then `work` or `drain` in a worker, where `const db = await bs.forContext(job.context).orThrow()` runs the work as the enqueuing user with RLS (it fails with `forbidden` for a job without a user; use `bs.admin(job.context)` only for work no user owns). The handler throws to retry. `schedule(name, cron, queue, payload, { timeZone })` uses pg_cron, or with `sql.modules.jobs.options.scheduler: "drain"` a `jobs.drainRoute({ secret: process.env.CRON_SECRET, handlers })` route that Vercel Cron calls; `sql.modules.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.
-- `createWebhookInbox(postgres.admin, { source, secrets }).receive(request)` for webhooks; `process(handler)` later. `createInbox` is the conversation inbox (`blocks/inbox`), not this.
+- `createJobs({ sql: postgres.admin, queues: { queue_name: zodSchema } })` runs on Supabase Queues (pgmq): `enqueue(queue, payload, { context: db.$context })` in the request, then `work` or `drain` in a worker, where `const db = await bs.forContext(job.context).orThrow()` runs the work as the enqueuing user with RLS (it fails with `forbidden` for a job without a user; use `bs.admin(job.context)` only for work no user owns). The handler throws to retry. `schedule(name, cron, queue, payload, { timeZone })` uses pg_cron, or with `blocks.jobs.options.scheduler: "drain"` a `jobs.drainRoute({ secret: process.env.CRON_SECRET, handlers })` route that Vercel Cron calls; `blocks.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({ sql: postgres.admin }).handle(request, handler)` for POST endpoints that clients retry.
+- `createWebhookInbox({ transport: sqlTransport(postgres.admin), source, secrets }).receive(request)` for webhooks; `process(handler)` later. `createInbox` is the conversation inbox (`blocks/inbox`), not this.
 - Times are `Temporal.Instant`: `EnqueueOptions.runAt`, `Job.enqueuedAt`, `Job.visibleUntil`, `WebhookInboxMessage.receivedAt` and webhook timestamps.
 - 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/blocks/audit`, which also has `auditListQuery` and `exportAuditLog` (NDJSON or OCSF). `sql sync` writes a pgTAP file per audited table, and doctor BS315 lists tables without the trigger; exempt the rest with `sql.modules.audit.options.exempt` globs.
+- Audit a table with `better_supabase.audit('public.t', redact => '{secret}', event_prefix => 't')`. Each call replaces all of the table's settings, so a second call without `ignore` and `redact` clears them; read `audit_settings('public.t')` first when another package also registers the table; 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/blocks/audit`, which also has `auditListQuery` and `exportAuditLog` (NDJSON or OCSF). `sql sync` writes a pgTAP file per audited table, and doctor BS315 lists tables without the trigger; exempt the rest with `blocks.audit.options.exempt` globs.
 - 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 `createOrganizations({ transport: sqlTransport(postgres.asUser(claims)), events: betterSupabase.events, onInvite })` from `better-supabase/blocks/organizations`. Send the invitation email in `onInvite`, show `previewInvitation(token)` on the accept page, and switch with `organizations.switch(id)`, refreshing the session when it returns `refresh: true`. Errors carry codes such as `ORGANIZATION_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 `organizationLogoBucket()` 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 SQL modules emit theirs automatically). Relay them with `createOutbox(postgres.admin, { source }).relayRoute({ secret, consumers: { name: httpSink(url) } })` from `better-supabase/blocks/outbox` after `outbox.register(name, { types })`. Delivery is at least once; receivers deduplicate on the CloudEvent `id`.
+- 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 SQL modules emit theirs automatically). Relay them with `createOutbox({ transport: sqlTransport(postgres.admin), source }).relayRoute({ secret, consumers: { name: httpSink(url) } })` from `better-supabase/blocks/outbox` 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/blocks/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/blocks/notifications/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 a support inbox, add the `inbox` SQL module (with `jobs` for bot and delivery jobs) and call `createInbox({ transport: sqlTransport(postgres.asUser(claims)) })` from `better-supabase/blocks/inbox`; staff need `inbox.read`, `inbox.reply`, `inbox.assign` or `inbox.manage`. Keep lists and threads live with `useInbox`, `useConversation` and `useInboxWidget` from `better-supabase/blocks/inbox/react`, each loading through a server action. For bots and channels, add `chat-sdk-state` and use `better-supabase/chat-sdk`: `createSupabaseState` as the Chat SDK state, `inboxAdapter` for the in-app widget, `webhook`, `inboundHandler` and `deliver` for Slack, WhatsApp or SMS, and `maintain` from a cron route. Platform tokens stay behind a `credential_ref`. Docs: `https://bettersupabase.com/docs/blocks/inbox.md` and `https://bettersupabase.com/docs/chat-sdk.md`.
 - 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/blocks/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.
 - Each SaaS block below is an SQL module of the same name plus `better-supabase/blocks/<name>`, called through `sqlTransport(postgres.asUser(claims))` for user actions and `postgres.admin` for service work; errors carry a code in `hint`. Its docs page is `https://bettersupabase.com/docs/blocks/<name>.md`.
   - `api-keys`: `createApiKeys`, and `auth: { resolvers: [apiKeyResolver({ keys })] }` in the adapter so key callers get `auth.kind === "apiKey"`. Show a new key once; only its hash is stored.
-  - `settings`: `defineSettings` with a Standard Schema per key; `usage`: `createUsage` with a `key` per increment, `within_quota` in policies; `billing`: `createBilling` with `stripe` as an optional peer; `flags`: `createFlagsProvider` for OpenFeature, `flag_enabled(key)` in policies.
-  - `comments`, `attachments` (signed URLs, served only after a scan), `data-lifecycle` (exports, organization deletion with a grace period), `sso` (verified domains, SAML, SCIM), `onboarding` (`defineChecklist`, `useOnboarding`), `waitlist` (`createWaitlist`, `waitlistHook` for invite-only sign-up) and `announcements` (`createAnnouncements`, `useAnnouncements`).
-  - `workflows`: `createWorkflows` for the run registry of any engine (`runs.list`, `runs.requestCancel`), schedules and admission whose `tick` hands each start to an engine, and `useWorkflowRuns` from `better-supabase/blocks/workflows/react`. With the Workflow SDK, add the `workflow-sdk-world` module, set `WORKFLOW_TARGET_WORLD=better-supabase/workflow-sdk/world`, start runs with `startFor(ctx, workflow, args)` from `better-supabase/workflow-sdk` so members see them under RLS, pass `workflowStarter({ name: workflow })` to `tick`, and check `authorizeHook(token, ctx)` before `resumeHook`. The World is Node-only (`https://bettersupabase.com/docs/blocks/workflow-sdk.md`).
-  - `workflow-builder`: `createBuilder` with `compile: compileGraph` and `start: graphStarter({ steps, executor })` from `better-supabase/workflow-sdk/builder`, and a service-role `service` transport for webhooks, events, `credentials.resolve` and `nodeRuns.record`. Call `steps.sync()` at deploy time so publishing accepts the steps. Wrap each step in `nodeRunReporter` for the canvas status, and read it with `useWorkflowCanvasRun` (`https://bettersupabase.com/docs/blocks/workflow-builder.md`).
+  - `settings`: `defineSettings` with a Standard Schema per key, read and written through `createSettings({ settings, transport })`; `usage`: `createUsage` with a `key` per increment, `within_quota` in policies; `billing`: `createBilling` with `stripe` as an optional peer; `flags`: `createFlagsProvider` for OpenFeature, `flag_enabled(key)` in policies.
+  - `comments`, `attachments` (signed URLs, served only after a scan), `data-lifecycle` (exports, organization deletion with a grace period), `sso` (verified domains, SAML, SCIM), `onboarding` (`defineChecklist`, `createOnboarding`, `useOnboarding`), `waitlist` (`createWaitlist`, `waitlistHook` for invite-only sign-up) and `announcements` (`createAnnouncements`, `useAnnouncements`).
+  - `workflows`: `createWorkflows` for the run registry of any engine (`runs.list`, `runs.requestCancel`), schedules and admission whose `tick` hands each start to an engine, and `useWorkflowRuns` from `better-supabase/blocks/workflows/react`. With the Workflow SDK, add the `workflow-sdk-world` module, set `WORKFLOW_TARGET_WORLD=better-supabase/workflow-sdk/world`, start runs with `startFor(ctx, workflow, args)` from `better-supabase/workflow-sdk` so members see them under RLS, pass `workflowStarter({ name: workflow }, { runAs: { publisher, permissions } })` to `tick` (schedules and `startOnEvent` run as that publisher, capped to those keys), and check `authorizeHook(token, ctx)` before `resumeHook`. The World is Node-only (`https://bettersupabase.com/docs/blocks/workflow-sdk.md`).
+  - `workflow-builder`: `createWorkflowBuilder` with `compile: compileGraph` and `start: graphStarter({ steps, executor })` from `better-supabase/workflow-sdk/builder`, and a service-role `service` transport for webhooks, events, `credentials.resolve` and `nodeRuns.record`. Call `steps.sync()` at deploy time so publishing accepts the steps. Wrap each step in `nodeRunReporter` for the canvas status, and read it with `useWorkflowCanvasRun` (`https://bettersupabase.com/docs/blocks/workflow-builder.md`).
 
 Done when a failing job is retried and then archived after `maxAttempts`,
 a replayed webhook or POST doesn't run twice, and each block table has a purge

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

@@ -101,14 +101,24 @@ const handle = bs.fetchHandler(new OpenAPIHandler(router), { prefix: "/api" });
 const app = new Hono().all("/api/*", (c) => handle(c.req.raw));
 ```
 
+`bs.authed()` doesn't apply to a contract implementer. Guard one procedure
+with `os.customers.remove.use(bs.middleware({ permission: "customers.delete" }))`
+before `.handler(...)`. The `authorizer` passed to `createOrpc` decides the
+permission, so an authorization package plugs in as that authorizer, not as
+a second guard.
+
 ## Edge Functions
 
-```ts title="supabase/functions/api/index.ts"
+```ts title="supabase/functions/api/server.ts"
 import { createEdge } from "better-supabase/edge";
 
 import { betterSupabase } from "../_shared/supabase.ts";
 
-const bs = createEdge(betterSupabase, { cors: true });
+export const bs = createEdge(betterSupabase, { cors: true });
+```
+
+```ts title="supabase/functions/api/index.ts"
+import { bs } from "./server.ts";
 
 Deno.serve(
   bs.resources({ customers: { select: ["id", "name"] } }, { basePath: "/api" }),

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

@@ -11,7 +11,7 @@ over direct Postgres. Its docs page is
 ## Knowledge and memory
 
 ```bash
-pnpm better-supabase sql add knowledge memory   # adds tenant, access and vector-search
+pnpm better-supabase add knowledge memory   # adds tenant, access and vector-search
 ```
 
 ```ts
@@ -53,7 +53,7 @@ const memory = createMemory({
 ## Agents, connectors and scheduled tasks
 
 ```bash
-pnpm better-supabase sql add agents connectors ai-tasks
+pnpm better-supabase add agents connectors ai-tasks
 ```
 
 - `createAgents({ transport })` stores assistants: `agents.create(organizationId, { slug, name, instructions, tools, knowledgeScopes })`,
@@ -89,7 +89,7 @@ pnpm better-supabase sql add agents connectors ai-tasks
 
 ```bash
 pnpm add eve @workflow/world @workflow/world-postgres pg
-pnpm better-supabase sql add workflow-sdk-world ai-chat memory knowledge credentials inbox
+pnpm better-supabase add workflow-sdk-world ai-chat memory knowledge credentials inbox
 ```
 
 Set `experimental.workflow.world` to `"better-supabase/workflow-sdk/world"`
@@ -108,7 +108,7 @@ in `defineAgent`, then use the helpers from `better-supabase/eve`:
 
 ```bash
 pnpm add chat
-pnpm better-supabase sql add chat-sdk-state inbox
+pnpm better-supabase add chat-sdk-state inbox
 ```
 
 From `better-supabase/chat-sdk`: `createSupabaseState(...)` is the Chat SDK

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

@@ -2,9 +2,11 @@
 
 ## Server (web): `better-supabase/expo`
 
-Needs `expo-server` 55 or later and, in `app.json`, `web.output: "server"`
-plus the `expo-router` plugin options `unstable_useServerDataLoaders` and
-`unstable_useServerMiddleware`.
+Needs `expo-server` 55 or later and, in `app.json`, `web.output: "server"`.
+On Expo SDK 57 and earlier, also set the `expo-router` plugin options
+`unstable_useServerDataLoaders`, `unstable_useServerMiddleware` and
+`unstable_useServerRendering`. SDK 58 needs no opt-in; the three options are
+deprecated there and have no effect.
 
 ```ts title="src/lib/supabase/server.ts"
 import { createExpo } from "better-supabase/expo";
@@ -27,12 +29,13 @@ export default bs.middleware();
 - Loaders run as the caller (bearer token first, then the cookie), so RLS applies.
 - A refused caller and a `DbException` from `.orThrow()` become a `StatusError` with the right status.
 - Only `+middleware.ts` refreshes the session; loaders never do.
+- `bs.loader` returns an `expo-server` `LoaderFunction`. Inside an existing `createServerLoader(async (request, params) => ...)`, call `const { db } = await bs.request(request, { allow })`. Static rendering has no request: use `createStaticLoader` from `expo-server` for public data there.
 - Loader data is JSON: select the columns the screen needs and turn Temporal values into strings.
 - API routes: `export const GET = bs.handler((request, { db }) => db.customers.findMany())` in `+api.ts`.
 
 ## Device: `better-supabase/client/native`
 
-```ts title="src/lib/supabase/native.ts"
+```ts title="src/lib/supabase/client.native.ts"
 import { createClient } from "@supabase/supabase-js";
 import {
   autoRefreshOnForeground,

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

@@ -8,7 +8,8 @@ export const local = betterSupabase.connect(powersyncExecutor(powersync));
 
 - `local.customers.findMany(...)` and `list.run(local, query)` run on the device's SQLite database and return the same rows (casing, Temporal values) as PostgREST.
 - Live results: `watch(powersync, () => list.run(local, query), { tables: sqliteTables(betterSupabase, ["customers"]), onResult })`.
-- Includes, related counts, full-text search, `db.rpc` and writes to tables without a primary key return a `DbError` of kind `unsupported`. Assert `checkSqlite(betterSupabase, list)` in a test for every list a native screen runs.
+- Includes, related counts, full-text search, `db.$rpc` and writes to tables without a primary key return a `DbError` of kind `unsupported`. Assert `checkSqlite(betterSupabase, list, { all: true })` is `[]` in a test for every list a native screen runs.
+- `powersyncExecutor(powersync, { fallback: postgrestExecutor(supabase, betterSupabase.executorOptions()) })` sends unsupported reads and `$rpc` to PostgREST (online only); writes never fall back. In `watch`, a fallback read reruns on local changes to `tables`, not on server changes; pass `refresh: { everyMs: 30_000, onReconnect: true }` to `watch` or `useWatch` so it reruns on an interval (skipped offline) and on reconnect. Prefer syncing a summary table through sync rules when the screen must work offline.
 - `ilike` is SQLite `like` (case-insensitive for ASCII only).
 
 ## Uploading local writes

package/skills/better-supabase-api/references/streams-credentials.md

@@ -6,7 +6,7 @@ Store long output (a chat answer, a workflow's progress) so a client that
 reconnects reads the rest instead of starting over.
 
 ```bash
-pnpm better-supabase sql add streams
+pnpm better-supabase add streams
 ```
 
 ```ts
@@ -45,7 +45,7 @@ Third-party tokens never go in a column. A row holds a `credential_ref`
 (`{ provider, secret, scope }`) and a `CredentialProvider` resolves it.
 
 ```bash
-pnpm better-supabase sql add credentials
+pnpm better-supabase add credentials
 ```
 
 ```ts
@@ -79,7 +79,7 @@ await fetch(url, { headers: token.headers });
 ## The Workflow World on Supabase (Node only)
 
 ```bash
-pnpm better-supabase sql add workflow-sdk-world   # adds workflows and jobs
+pnpm better-supabase add workflow-sdk-world   # adds workflows and jobs
 pnpm add workflow @workflow/world @workflow/world-postgres pg
 ```
 
@@ -97,8 +97,11 @@ entry.
 From `better-supabase/workflow-sdk`, which runs anywhere: `startFor(ctx, workflow, args)`
 starts a run members see under RLS, `authorizeHook(token, ctx)` checks a
 caller before `resumeHook`, `protectWebHandler(handler, key, { can })` refuses callers before a workflow UI route or a run's stream and
-`workflowStarter({ name: workflow })` hands scheduled starts from the
-`workflows` block to the SDK.
+`workflowStarter({ name: workflow }, { runAs })` hands scheduled starts from the
+`workflows` block to the SDK. Schedules and `startOnEvent` need `runAs`
+(`{ publisher, permissions }`): the run starts as that user, capped to those
+permission keys, and the event actor or schedule creator only lands in
+`bs.trigger`.
 
 Docs: https://bettersupabase.com/docs/blocks/streams.md,
 https://bettersupabase.com/docs/extending/credentials.md and

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

@@ -62,22 +62,29 @@ 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 }`  |
-| `act: { kind: "support", sub, session_id, ... }` | `{ kind: "support", id, sessionId, readOnly }` | not set              |
-| `act: { kind: "impersonation", sub, reason }`    | `{ kind: "impersonation", id, reason }`        | not set              |
+| 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              |
+| `act: { kind: "agent", sub, tools, read_only }`  | `{ kind: "agent", id, tools, readOnly, chain }` | with a `scope` claim |
 
 - 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. Only an
-  `oauth-client` actor is limited: the user's own token, a support session
-  and an impersonated session are not.
+  `oauth-client` actor, and an `agent` on a token with a `scope`, are
+  limited: the user's own token, a support session and an impersonated
+  session are not. `delegation.scopes` leaves out OpenID identity scopes
+  (`openid`, `email`, `profile`, `phone`, `address`, `offline_access`).
 - 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`.
+  `oauth-client`, `support`, `impersonation` or `agent`. An invalid `act`
+  (another `kind`, a level without `sub`, a malformed agent or support
+  level, or a 0.5.0 support token with `session_id` but no `kind`) resolves
+  to `invalid` with reason `actor`, never to the user alone.
+- An agent's `tools` list is enforced by `createAgentRuntime` and
+  `assertToolDelegated` only, not by guards or RLS.
 - 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

package/skills/better-supabase-auth/references/authorization-providers.md

@@ -9,7 +9,7 @@ membership tables and the access token hook the provider generates.
 ```ts
 export default defineConfig({
   authorization: authorizationProvider(), // from the authorization package
-  sql: { modules: { access: { model: "provider" } } },
+  blocks: { access: { model: "provider" } },
 });
 ```
 
@@ -17,21 +17,21 @@ export default defineConfig({
 
 - When `authorization.tokenHook.ownedClaims` has `memberships`, the
   provider's hook owns the memberships and the tenant claim. Don't run
-  `better-supabase sql add tenant` (it stops without `--force`), don't call
+  `better-supabase add tenant` (it stops without `--force`), don't call
   `membership_claims()` from a hook, and don't write the claims in
   `ownedClaims` yourself. Doctor reports BS407 when a hook does.
-- `sql add entitlements` is fine. With a provider it reads memberships through
+- `add entitlements` is fine. With a provider it reads memberships through
   the provider's `memberIds` and `memberIdsFor` (`entitlements.memberships`
   defaults to `"provider"`). For `hasEntitlement(session, ...)`, the
   provider's hook must fill `features` from `better_supabase.feature_claims`;
   doctor reports BS408 otherwise.
 - Name the same tenant claim on both sides: `claims.tenant` must equal
   `authorization.tokenHook.tenantClaim` (BS409).
-- `sql.modules.access.model: "provider"` makes `can()`, `tenant_ids_with()`
+- `blocks.access.model: "provider"` makes `can()`, `tenant_ids_with()`
   and `platform_can()` call the provider's `idsWith` and `isPlatform`. Every
   permission key a SQL module checks must be `sqlComplete: true` in
   `authorization.permissions`; map an action to another key with
-  `sql.modules.<module>.permissions`. Doctor reports BS411.
+  `blocks.<module>.permissions`. Doctor reports BS411.
 - Bucket and topic `access` policies call the access contract by default.
   For another scope, copy the provider's `idsWith` and `isPlatform` into the
   policy's `sql`. Use only keys marked `sqlComplete: true`: the policies check

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

@@ -113,13 +113,13 @@ With the polyfill, `vi.useFakeTimers({ now })` drives `Temporal.Now` too.
 ## Doctor in CI
 
 Run `pnpm better-supabase doctor` against the reset stack and fail the job on
-a nonzero exit. `--json` prints the report with each finding's code,
+a nonzero exit. `--json` puts the report, with each finding's code, under `data`,
 `--format github` annotates the pull request, and
 `--format sarif --out doctor.sarif` feeds code scanning.
 
 ## pgTAP
 
-`better-supabase sql add pgtap` installs `tests.create_user`,
+`better-supabase add pgtap` installs `tests.create_user`,
 `tests.authenticate_as(user, claims)`, `tests.clear_authentication()` and
 `tests.rls_enabled('public')` for `supabase test db`. Put
 `select tests.rls_enabled('public');` in a test so tables without RLS fail CI.