better-supabase 0.5.0 → 0.6.0

package/schemas/doctor-report-v1.json

@@ -67,6 +67,7 @@
               "BS219",
               "BS220",
               "BS221",
+              "BS222",
               "BS301",
               "BS302",
               "BS303",
@@ -81,6 +82,19 @@
               "BS312",
               "BS313",
               "BS314",
+              "BS315",
+              "BS316",
+              "BS317",
+              "BS318",
+              "BS319",
+              "BS320",
+              "BS321",
+              "BS322",
+              "BS323",
+              "BS324",
+              "BS325",
+              "BS326",
+              "BS327",
               "BS401",
               "BS402",
               "BS403",
@@ -91,6 +105,8 @@
               "BS408",
               "BS409",
               "BS410",
+              "BS411",
+              "BS412",
               "BS501",
               "BS502"
             ]
@@ -121,7 +137,11 @@
             "properties": {
               "kind": { "enum": ["table", "function", "policy"] },
               "schema": { "type": "string" },
-              "name": { "type": "string" }
+              "name": { "type": "string" },
+              "table": {
+                "description": "The table a policy is on.",
+                "type": "string"
+              }
             }
           },
           "help": { "type": "string", "format": "uri" }

package/schemas/snapshot-v2.json

@@ -633,6 +633,14 @@
                 "items": {
                   "type": "string"
                 }
+              },
+              "versioning": {
+                "description": "storage.buckets.versioning_status; absent when Storage has no versioning.",
+                "enum": ["DISABLED", "ENABLED", "SUSPENDED", null]
+              },
+              "lifecycle": {
+                "description": "storage.buckets.lifecycle_configuration; absent when Storage has no lifecycles.",
+                "type": ["object", "null"]
               }
             }
           }

package/skills/better-supabase/SKILL.md

@@ -16,15 +16,15 @@ is no separate CLI package to add.
 ## Workflow: change the schema
 
 1. Write the migration: edit `supabase/schemas/*.sql`, then run
-   `supabase db schema declarative sync -f <name>` (pg-delta;
-   `supabase db diff -f <name>` when `config.toml` has no
-   `[experimental.pgdelta] enabled = true`), or `supabase migration new` for
-   data and role settings.
+   `supabase db schema declarative sync -f <name>`, or `supabase migration
+new` for data and role settings. The sync needs
+   `[experimental.pgdelta] enabled = true` in `supabase/config.toml`;
+   doctor reports BS316 when a project is still on the legacy migra engine.
 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. 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)`,
+   `organization_id in (select better_supabase.member_organization_ids())`, which
+   Postgres runs once per statement, not `has_organization_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.
@@ -56,7 +56,7 @@ stay hidden.
 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
+2. Run `pnpm better-supabase sql upgrade`, so the SQL 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
@@ -65,9 +65,11 @@ stay hidden.
    the config to keep an old relation name.
 4. Run `pnpm better-supabase skills install --check` and reinstall the skills
    when it reports them stale.
-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
+5. Read the release's guide: https://bettersupabase.com/docs/migration/0.5-to-0.6
+   for 0.6 (kits are blocks, feature modules import from
+   `better-supabase/blocks/<name>`), and the other versions at
+   https://bettersupabase.com/docs/migration. Every breaking change is in
+   https://github.com/ScaleDockHQ/better-supabase/blob/main/CHANGELOG.md. 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.
@@ -80,14 +82,40 @@ Name the definition `betterSupabase` (in `lib/supabase/index.ts`) and every runt
 
 - 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()`
+- Next.js with the tenant in the route (`/[organizationId]/...`): `bs.context({ tenant: organizationId })`, `bs.cached({ tenant })` inside a `'use cache: private'` function that takes the tenant as an argument, and `bs.action({ input, tenant: (input) => input.organizationId }, fn)`. The tenant gets the resolver's membership checks. Client Components get the id as a prop and pass it to actions and to `useLiveQuery(spec, { tenant })`; the browser client only knows the claim's tenant
 - Hono: `c.var.db` after `bs.middleware()`
 - oRPC: `context.db` after `bs.middleware()`
 - Edge Functions: `bs.handler((request, { db }) => ...)`
+- Express: `res.locals.db`; Fastify: `request.locals.db`; Koa: `ctx.state.db`; NestJS: `@Ctx("db")`
+- SvelteKit: `event.locals.db`; H3, Nitro and Nuxt: `event.context.db`; TanStack Start: the middleware `context.db`
+- Astro: `bs.locals(Astro).db`; SolidStart: `(await bs.require()).db`
 - Browser: `bs.db`, or the hooks from `createHooks<typeof bs>()`
+- Vue, Solid and Svelte, TanStack DB collections and a local expo-sqlite database: [references/frontend.md](references/frontend.md)
 
 For who the caller is (sessions, claims, OAuth clients, agents, scopes), use
 the `better-supabase-auth` skill.
 
+## Forms and actions (Next.js)
+
+- Put the permission check in the action's options, not its body:
+  `bs.action({ input, requireTenant: true, authorize: (session, input) => can(session, "members.invite") }, (input, { db, tenant, session }) => ...)`.
+  `requireTenant` types `tenant` as a string; a refusal is a `forbidden`
+  `ActionResult`. `bs.route(handler, { requireTenant, authorize })` takes the same.
+- A form: `const form = useActionForm(action, { onSuccess })` from
+  `better-supabase/react`, then `<form {...form.formProps}>`, `form.pending`
+  and `form.fieldErrors.<field>`. Fields survive a failed submit. Pass
+  `resetOnSuccess: false` for edit forms.
+- A button or row action: `const remove = useAction(action, { onError })`,
+  `remove.run(input)`, and `remove.pendingInputs` to mark the row in flight.
+- Error copy: `createErrorMessages({ ...one entry per DbError kind })` from
+  `better-supabase`; a missing kind is a type error.
+- A page only some callers may see: `await bs.require({ authorize })` throws
+  `forbidden()` or `unauthorized()` (needs `experimental.authInterrupts`).
+  Under Cache Components, check the privately cached session and call
+  `forbidden()` instead, so the page stays prefetchable.
+- The active tenant of a session: `tenantOf(session)`, on the server and in
+  the browser.
+
 ## Querying
 
 ```ts
@@ -103,11 +131,12 @@ const customers = result.data;
 ```
 
 - Methods return a `Result`, and database errors never throw. Use `.orThrow()` only where an exception is really wanted.
+- Apps on better-result: `toBetterResult(result, Result, mapError)` converts at the boundary, and `defineBetterResultErrors(Result, { not_found: NotFound }, DbFailure)` maps `DbError` kinds to `TaggedError` classes once. Annotate the expected `Result<T, E>` type instead of casting.
 - 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.
+- 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, and `paginate({ offset, limit, count: 'exact' })` when the caller already has an offset; both return the rows and the total in one request.
 - Handlers may return a `Result` directly. Adapters turn errors into RFC 9457 Problem Details with the right status.
-- Server-only admin access: `bs.admin()`. Only use it for trusted jobs, never for a user's request.
+- Jobs and webhooks run as a user so RLS applies: `bs.forContext(job.context)` for a job enqueued with `{ context: db.$context }`, `bs.actingAs(userId, { tenant_id })` for a webhook or script. `bs.admin()` bypasses RLS: use it only for work no user owns, 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

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

@@ -0,0 +1,96 @@
+# Vue, Solid, Svelte, TanStack DB and expo-sqlite
+
+Each framework binding wraps the browser client `bs` from
+`lib/supabase/client.ts` and the TanStack Query client for that framework.
+Reads still go through PostgREST as the signed-in user, so RLS applies.
+
+## Vue
+
+```ts title="src/main.ts"
+import { betterSupabase } from "better-supabase/vue";
+
+createApp(App)
+  .use(VueQueryPlugin, { queryClient })
+  .use(betterSupabase(bs, { queryClient }))
+  .mount("#app");
+```
+
+```ts title="src/lib/composables.ts"
+import { createBindings } from "better-supabase/vue";
+import type { bs } from "./supabase/client";
+
+export const { useDb, useQueries, useAuth, useSession } =
+  createBindings<typeof bs>();
+```
+
+Use `useQuery(q.customers.findMany({ ... }))` from `@tanstack/vue-query`
+with `const q = useQueries()`. `useLiveQuery`, `useLiveCount`,
+`useBroadcast`, `usePresence` and `useAction` come from
+`better-supabase/vue` directly.
+
+## Solid
+
+Wrap the app in `<BetterSupabaseProvider client={bs} queryClient={queryClient}>`
+inside `QueryClientProvider`, and get typed primitives from
+`createBindings<typeof bs>()` in `better-supabase/solid`. Pass a function to
+the live primitives, so they track their inputs:
+`useLiveCount(() => betterSupabase.spec.messages.count({ where: { read: false } }))`.
+
+## Svelte 5
+
+In the root `+layout.svelte`, call `setBetterSupabase(bs, { queryClient })`
+and `setSession(() => data.session)` from `better-supabase/svelte`. In
+components, `useAuth()`, `useLiveQuery(() => spec)` and `useLiveCount(() => spec)`
+return objects whose fields are reactive (`auth.current.status`,
+`unread.count`). Return `null` from the spec function to pause a query.
+
+## TanStack DB
+
+```ts
+import { createCollection } from "@tanstack/react-db";
+import { queryCollectionOptions } from "@tanstack/query-db-collection";
+import { collectionOptions } from "better-supabase/tanstack-db";
+
+export const customers = createCollection(
+  queryCollectionOptions(
+    collectionOptions(betterSupabase, db, "customers", {
+      query: queries.customers.findMany({ where: { status: "active" } }),
+      queryClient,
+    }),
+  ),
+);
+```
+
+The collection loads through the query and writes through the
+repositories, so its inserts and updates run as the signed-in user.
+
+## expo-sqlite
+
+Run the same repositories over a local database on the device, without
+PowerSync:
+
+```ts
+import { addDatabaseChangeListener, openDatabaseAsync } from "expo-sqlite";
+import {
+  expoSqliteDatabase,
+  expoSqliteExecutor,
+} from "better-supabase/expo-sqlite";
+
+const sqlite = await openDatabaseAsync("app.db", {
+  enableChangeListener: true,
+});
+export const local = betterSupabase.connect(
+  expoSqliteExecutor(sqlite, { addDatabaseChangeListener }),
+);
+export const database = expoSqliteDatabase(sqlite, {
+  addDatabaseChangeListener,
+});
+```
+
+Keep a list live with `useWatch({ db: database, tables: ["notes"], query: () => local.notes.findMany(...) })`
+from `better-supabase/powersync/react`. The local database has no RLS: it
+holds only what this device's user synced or wrote.
+
+Docs: https://bettersupabase.com/docs/frontend/vue.md (and `solid`,
+`svelte`, `tanstack-db` under `/docs/frontend/`) and
+https://bettersupabase.com/docs/repository/expo-sqlite.md.

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

@@ -54,14 +54,18 @@ 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 `context.tenant`, which the server's `tenant` resolver
-sets per request (the default `kits.access.activeTenant: 'resolver'`), then
+sets per request (the default `sql.modules.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
-(https://bettersupabase.com/docs/auth/permdock.md).
+member of. In Next.js Server Components and actions there is no request URL:
+pass the route's tenant with `bs.context({ tenant })`, `bs.cached({ tenant })`
+or `bs.action({ tenant: (input) => input.organizationId })`, which take the
+resolver's path and get the same check. Never trust a tenant from
+`user_metadata`, and never use one from a request body outside those options. When the config
+has an `authorization` provider whose hook owns `memberships`, that hook
+writes the claim and the memberships: don't run `sql add tenant`, and follow
+the authorization providers reference of the `better-supabase-auth` skill
+(https://bettersupabase.com/docs/extending/authorization-providers.md).
 
 Docs: https://bettersupabase.com/docs/plugins.md

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

@@ -22,8 +22,9 @@ Branch on `result.error.kind`, not on the message.
 | `multiple_rows`                                       | `findUnique` or a single-row write matched more than one row                   | Filter by a unique key                                                        |
 | `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                                      |
+| `unsupported`                                         | The executor can't run the query, such as an include on SQLite (PowerSync)     | Read it on the server, or check list definitions with `checkSqlite` in a test |
 | `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  |
+| `unexpected` naming `temporal-polyfill/global`        | The runtime has no `Temporal` (Node 24, Safari)                                | Pass `temporal: Temporal` from `temporal-polyfill` to `defineSupabase`        |
 
 ## By error `code`
 

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

@@ -1,6 +1,6 @@
 ---
 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, OAuth or agent scopes, webhook, background job, cleanup cron 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, AI chat route, knowledge or memory, stored agent, MCP connector, eve agent, Chat SDK bot, resumable stream, third-party credential, OAuth or agent scopes, webhook, background job, cleanup cron or idempotent endpoint.
 ---
 
 # APIs with better-supabase
@@ -57,13 +57,23 @@ never limits it. RLS still decides the rows: the token's `sub` is the user.
 
 ## Adapters
 
-| 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 }) => ... })`                                     |
+| 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(...))`                                           |
+| Expo Router                                     | `createExpo(betterSupabase)`, `+middleware.ts` with `bs.middleware()`                                   | `export const loader = bs.loader(({ db }) => ...)`, `bs.handler(...)` in `+api.ts`        |
+| Edge Functions                                  | `createEdge(betterSupabase, { cors: true })`                                                            | `Deno.serve(bs.handler((req, { db }) => ...))`                                            |
+| MCP                                             | `createMcp(betterSupabase, { name, version, resources })`                                               | `.tool({ name, input, run: (args, { db }) => ... })`                                      |
+| Node, Express, Fastify, Koa                     | `toNodeHandler`, `toExpress`, `toFastify`, `toKoa` from `better-supabase/node`                          | `res.locals.db`, `request.locals.db`, `ctx.state.db`; `guard`, `fastifyGuard`, `koaGuard` |
+| NestJS                                          | `toNestMiddleware(entries)` from `better-supabase/nestjs`                                               | `@Ctx("db") db`, `@UseGuards(guard({ roles }))`, `@UseFilters(problemFilter())`           |
+| Astro                                           | `createAstro(betterSupabase)`, `export const onRequest = bs.onRequest`                                  | `bs.locals(Astro).db`, `bs.guard(Astro, options)`, `bs.action(...)`                       |
+| SolidStart                                      | `createSolidStart(betterSupabase, { getRequestEvent })`, `createMiddleware(bs.middleware)`              | `await bs.require()` in a `"use server"` query, `bs.action(...)`                          |
+| Nuxt, Nitro 2                                   | the `better-supabase/nuxt` module, or `toH3V1(entries)` from `better-supabase/h3/v1`                    | `event.context.db`, `guard(options)`                                                      |
+| H3 2, Nitro 3                                   | `toH3(entries)` from `better-supabase/h3`                                                               | `event.context.db`, `guard(options)`                                                      |
+| TanStack Start, SvelteKit, React Router, Elysia | `withBetterSupabase(server)` in a bridge: `toTanStackStart`, `toSvelteKit`, `toReactRouter`, `toElysia` | the framework's context (`context.db`, `locals.db`, `context.get(key).db`)                |
+
+Never use `@supabase/server/adapters/*` (deprecated, removed 2026-12-01).
 
 Don't build error JSON by hand; errors become Problem Details.
 
@@ -85,24 +95,65 @@ for lists that clients read page by page: the list takes `after` instead of
 - `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.
+- 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`.
 
-## Background work (`better-supabase/jobs`, needs `sql add jobs idempotency webhook-inbox`)
+## AI chat (`sql add ai-chat`; `ai`, `@ai-sdk/react`, `@ai-sdk/workflow` and `workflow` as optional peers)
 
-- `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).
+- 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.
+- On the client use `useAssistant({ id, messages })` from `better-supabase/ai-sdk/react`; load `messages` on the server with `toUIMessages(await aiChat.messages.path(id, { native: true }).orThrow())`.
+- Models are AI Gateway `provider/model` strings checked against `ai_model_catalog`; refresh it with the `modelCatalogRefresh` job and backfill costs with `costBackfill` from `better-supabase/ai-sdk`.
+- For answers that must outlive the request (long agents, approvals that wait hours), use `durableChat({ assistant, workflow, streams })` from `better-supabase/ai-sdk/workflow` with a `"use workflow"` function that calls `durableTurn(input, { runId: getWorkflowMetadata().workflowRunId, createHook, getWritable, step, agent })`. `step` is one `"use step"` function that calls `runDurableStep(serviceAiChat, name, input)`, and the agent's model is a gateway string. The route context is the assistant context; its `chats.runs` (from `createAiChat`) serves the runs. On the client use `useDurableAssistant({ id, messages, resume: chat.activeStreamId !== undefined })` from `better-supabase/ai-sdk/workflow/react`. Record a long run's progress with `chats.runs.steps.record(runId, { key, label, status })` and list undecided approvals with `chats.runs.pendingApprovals()`.
+- For tenant keys, add the `ai-providers` SQL module: store the key with the credential provider first, save its `credential_ref` with `createAiProviders({ transport, service, credentials }).keys.save(organizationId, key)` from `better-supabase/blocks/ai-providers`, and merge `byokOptions(await providers.keys.resolve(organizationId).orThrow())` into `providerOptions.gateway`. Call `keys.removeAll(organizationId)` when a tenant is deleted. The same module tracks batches (`aiBatches({ providers })` from `better-supabase/ai-sdk/batches`, with its `pollJob`) and sandboxes (`trackedSandbox`, `sandboxes.idleStopJob`).
+- For repeated model calls, add the `ai-cache` SQL module and wrap the model with `wrapLanguageModel({ model, middleware: cacheMiddleware({ cache, ttl, organizationId }) })` from `better-supabase/ai-sdk/cache`; the cache is service-role only, so create it with a service transport. Meter spend with `meterTelemetry` through `registerTelemetry` and reconcile it nightly with the `spendReconciliation` job.
+- Blocks never import an AI SDK. Put SDK code in the app or an adapter subpath, and store third-party tokens as a `credential_ref`, never in a column.
+
+## AI blocks, agents and bots
+
+Knowledge, memory, stored agents, MCP connectors, scheduled AI tasks, the AI
+SDK helpers (`better-supabase/ai-sdk/agents`, `/mcp`, `/embeddings`,
+`/memory`, `/files`, `/batches`), eve and Chat SDK bots are in
+[references/ai.md](references/ai.md).
+
+## Streams, credentials and the Workflow World
+
+Resumable output (`better-supabase/streams`, `/streams/redis`), third-party
+tokens behind a `credential_ref` (`better-supabase/credentials`,
+`/vercel-connect`) and the Node-only Workflow World
+(`better-supabase/workflow-sdk/world`) are in
+[references/streams-credentials.md](references/streams-credentials.md).
+
+## Native and offline apps
+
+For Expo and React Native, follow [references/expo.md](references/expo.md):
+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`)
+
+- `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.
-- `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.
+- `createWebhookInbox(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/jobs`.
+- 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.
 - 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.
+- 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 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`).
 
 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
+a replayed webhook or POST doesn't run twice, and each block table has a purge
 schedule.
 
 ## Direct Postgres on the server
@@ -116,7 +167,10 @@ schedule.
 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/`),
-https://bettersupabase.com/docs/kits/jobs.md and
+Docs: https://bettersupabase.com/docs/frameworks.md lists every adapter;
+each has a page such as https://bettersupabase.com/docs/frameworks/hono.md,
+https://bettersupabase.com/docs/repository/powersync.md,
+https://bettersupabase.com/docs/blocks/jobs.md,
+https://bettersupabase.com/docs/ai-sdk/chat.md,
+https://bettersupabase.com/docs/ai-sdk/workflow.md and
 https://bettersupabase.com/docs/auth/postgres.md.