better-supabase 0.14.0 → 0.15.0

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

@@ -18,7 +18,7 @@ skill.
    needs with `scopes` (see below).
 3. Use `db` from the handler context and return its `Result`, a plain value
    or a `Response`.
-4. For a table exposed as REST, prefer `bs.resource(...)` over hand-written
+4. For a table exposed as REST, prefer `bsb.resource(...)` over hand-written
    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
@@ -36,13 +36,13 @@ and `['service']` for machine callers. Rejected callers get a 401 with a
 
 `scopes` limits what a delegated token may do: a token from the Supabase
 OAuth server (`client_id` and `scope`) or one exchanged for an agent (an
-RFC 8693 `act` chain). The guard options of `bs.route`, `bs.action`,
-`bs.handler` (edge) and `bs.middleware` (Hono, oRPC) take it, next to
+RFC 8693 `act` chain). The guard options of `bsb.route`, `bsb.action`,
+`bsb.handler` (edge) and `bsb.middleware` (Hono, oRPC) take it, next to
 `allow`:
 
 ```ts
-export const GET = bs.route(
-  (request, { db }) => db.customers.findMany({ limit: 20 }),
+export const GET = bsb.route(
+  (request, { db }) => db.customers.list({ limit: 20 }),
   { scopes: ["customers:read"] },
 );
 ```
@@ -57,21 +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(...))`                                           |
-| 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`)                |
+| Where                                           | Setup                                                                                                   | Handler                                                                                    |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Next.js                                         | `createNext(betterSupabase)` in `lib/supabase/server.ts`                                                | `bsb.route((req, { db }) => ...)`, `bsb.action({ input: schema }, (input, { db }) => ...)` |
+| Hono                                            | `createHono(betterSupabase)`, `.use('/api/*', bsb.middleware())`                                        | `c.var.db`; `bsb.resource('customers', {...})` for REST                                    |
+| oRPC                                            | `createOrpc(betterSupabase)`, `base.use(bsb.middleware())`                                              | `bsb.unwrap(context.db.customers.list(...))`                                               |
+| Expo Router                                     | `createExpo(betterSupabase)`, `+middleware.ts` with `bsb.middleware()`                                  | `export const loader = bsb.loader(({ db }) => ...)`, `bsb.handler(...)` in `+api.ts`       |
+| Edge Functions                                  | `createEdge(betterSupabase, { cors: true })`                                                            | `Deno.serve(bsb.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 = bsb.onRequest`                                 | `bsb.locals(Astro).db`, `bsb.guard(Astro, options)`, `bsb.action(...)`                     |
+| SolidStart                                      | `createSolidStart(betterSupabase, { getRequestEvent })`, `createMiddleware(bsb.middleware)`             | `await bsb.require()` in a `"use server"` query, `bsb.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`)                 |
+
+Next.js, Hono, Expo Router, SvelteKit, TanStack Start and React Router are supported adapters; Edge Functions, Node, NestJS, Astro, SolidStart, Nuxt, H3 and Elysia are community adapters with a smoke test, so prefer a supported one for a new app ([adapter tiers](https://bettersupabase.com/docs/frameworks#adapter-tiers)).
 
 Never use `@supabase/server/adapters/*` (deprecated, removed 2026-12-01).
 
@@ -79,10 +81,18 @@ Don't build error JSON by hand; errors become Problem Details.
 
 ## REST resources
 
-`defineResource` / `bs.resource(table, { operations, list, input })` gives you
+`defineResource` / `bsb.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 spec emit openapi --check` keeps `openapi.json` in sync.
+Each resource also serves `POST /<table>/page`, `/count`, `/aggregate` and
+`/upsert` with the repository method's arguments as the body.
+
+For one API over every table and block instance, use
+`defineApi(betterSupabase, { info, basePath })` from `better-supabase/spec`
+and serve it with `bsb.router(api, { meta: openapi })` from `createOrpc`.
+Without `resources` and `blocks` it publishes everything; a map publishes
+only the keys it names. Block methods are `POST /<instance>/<method>`.
 
 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
@@ -95,7 +105,7 @@ 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`.
+- 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 `bsb`. With a permission library that wraps `McpServer`, wrap with it first, then `withBetterSupabaseMcp`.
 
 ## AI chat (`add ai-chat`; `ai`, `@ai-sdk/react`, `@ai-sdk/workflow` and `workflow` as optional peers)
 
@@ -104,7 +114,7 @@ for lists that clients read page by page: the list takes `after` instead of
 - 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 tenant keys, add the `ai-keys` SQL module: store the key with the credential provider first, save its `credential_ref` with `createAiKeys({ transport, service, credentials }).keys.upsert(organizationId, key)` from `better-supabase/blocks/ai-keys`, 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.
 
@@ -128,29 +138,30 @@ tokens behind a `credential_ref` (`better-supabase/credentials`,
 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).
+and upload through `bsb.db`, as in [references/powersync.md](references/powersync.md).
 
-## Background work (`better-supabase/blocks/jobs`, needs `add jobs idempotency webhook-inbox`)
+## Background work (`better-supabase/blocks/queue`, needs `add jobs idempotency webhook-inbox`)
 
-- `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).
+- `createQueue({ 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 bsb.forContext(job.context).orThrow()` runs the work as the enqueuing user with RLS (it fails with `forbidden` for a job without a user; use `bsb.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.queue.options.scheduler: "drain"` a `jobs.drainRoute({ secret: process.env.CRON_SECRET, handlers })` route that Vercel Cron calls; `blocks.queue.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')`. 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.
+- 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). `upgrade` 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 `impersonation` SQL module, pass `support: supportSessions({ store: sqlSupportStore(postgres) })` to `createServer`, call `bsb.startSupport({ targetUserId, reason })` and `bsb.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`. Tables your schema already has are detected and kept; map other names with `tables` and `columns`.
+- 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. An existing `profiles` table is detected and kept: the block adds only the columns it lacks, `tables` and `columns` map other names, and `syncTrigger: false` leaves profile creation to your own trigger. 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({ 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 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 the `@better-supabase/use-notifications` registry item (`npx shadcn add @better-supabase/use-notifications`); 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 the `@better-supabase/use-inbox` registry item, 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, 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` (a record's messaging conversation; needs `tenant`, `subjects` and `messaging`, keys `messages.read`, `messages.send`, `messages.moderate`, events `message.*`), `activity` (`activitySink` as an outbox consumer, `createActivity().list(subject?)` for the feed and a record's timeline), `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`).
+  - `comments` (a record's messaging conversation; needs `tenant`, `subjects` and `messaging`, keys `messages.read`, `messages.send`, `messages.moderate`, events `message.*`), `activity` (`activitySink` as an outbox consumer, `createTimeline().list(subject?)` for the feed and a record's timeline), `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 the `@better-supabase/use-workflows` registry item. With the Workflow SDK, add the `workflow-sdk` 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`).
+  - `automations`: register every action once with `createActionRegistry([...])` (`notifyAction`, `workflowAction`, the target blocks' conversion actions such as `taskFromConversationAction`, your own `defineAction`), pass it to `createRuleDispatcher({ actions })`, and consume the outbox with `createRuleSink`. Blocks ship default automations (inbox to tasks, hiring to employees, quotes to orders) that organizations turn off, edit or `resetDefault`, and `blocks.automations.options.enable` or `disable` (keys such as `quotes.quote_to_order`) sets whether a default ships on; there is no `createFlows`. Block timers (SLA, sequences, AI schedules, workflow schedules, content publishing) run from `blockSchedules` and `blockTickHandler` on the queue (`https://bettersupabase.com/docs/blocks/automations.md`).
+  - `workflow-editor`: `createWorkflowEditor` with `compile: compileGraph` and `start: graphStarter({ steps, executor })` from `better-supabase/workflow-sdk/builder`, and a service-role `service` transport for webhooks, `credentials.resolve` and `nodeRuns.record`. A definition has no event trigger: an automation's `workflow` action starts it on an outbox event. 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-editor.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
@@ -159,7 +170,7 @@ schedule.
 ## Direct Postgres on the server
 
 - `createPostgres()` opens a pool; `createPostgres({ pool })` runs on an existing `pg.Pool`. `asUser` and `anon` transactions get Supabase's role timeouts (8 s and 3 s); `statementTimeout` takes a number or `{ admin, authenticated, anon }`.
-- `createMany` and `upsertMany` split inserts past 65,535 bind parameters into several statements in one transaction, so large batches don't need manual chunking.
+- `create` and `upsert` with an array split inserts past 65,535 bind parameters into several statements in one transaction, so large batches don't need manual chunking.
 - In serverless functions, connect through the transaction pooler (port 6543), not a direct connection.
 
 ## Testing
@@ -169,8 +180,8 @@ the adapter verifies them against the local JWKS. See the `better-supabase-testi
 
 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/frontend/powersync.md,
+https://bettersupabase.com/docs/blocks/queue.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.

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

@@ -20,24 +20,24 @@ import { createNext } from "better-supabase/next";
 
 import { betterSupabase } from "./index";
 
-export const bs = createNext(betterSupabase);
+export const bsb = createNext(betterSupabase);
 ```
 
 ```ts title="src/proxy.ts"
 import type { NextRequest } from "next/server";
 
-import { bs } from "./lib/supabase/server";
+import { bsb } from "./lib/supabase/server";
 
-export const proxy = (request: NextRequest) => bs.proxy(request);
+export const proxy = (request: NextRequest) => bsb.proxy(request);
 ```
 
 The proxy is the only place that refreshes sessions. Server Components,
 route handlers and actions read the verified token:
 
 ```ts
-const { db } = await bs.context();
-export const GET = bs.route(
-  (request, { db }) => db.customers.findMany({ limit: 20 }),
+const { db } = await bsb.context();
+export const GET = bsb.route(
+  (request, { db }) => db.customers.list({ limit: 20 }),
   { scopes: ["customers:read"] }, // only limits OAuth clients and agents
 );
 ```
@@ -49,16 +49,16 @@ import { createHono } from "better-supabase/hono";
 
 import { betterSupabase } from "./lib/supabase";
 
-const bs = createHono(betterSupabase);
+const bsb = createHono(betterSupabase);
 
-// bs.app() is new Hono<typeof bs.Env>() with bs.onError installed.
-const app = bs
+// bsb.app() is new Hono<typeof bsb.Env>() with bsb.onError installed.
+const app = bsb
   .app()
-  .use("/api/*", bs.middleware())
+  .use("/api/*", bsb.middleware())
   .get("/api/me", (c) => c.json({ kind: c.var.auth.kind }))
   .route(
     "/api/customers",
-    bs.resource("customers", { select: ["id", "name"] }),
+    bsb.resource("customers", { select: ["id", "name"] }),
   );
 
 export default app;
@@ -72,12 +72,12 @@ import { createOrpc, type OrpcRequestContext } from "better-supabase/orpc";
 
 import { betterSupabase } from "./lib/supabase";
 
-export const bs = createOrpc(betterSupabase);
-const authed = os.$context<OrpcRequestContext>().use(bs.middleware());
+export const bsb = createOrpc(betterSupabase);
+const authed = os.$context<OrpcRequestContext>().use(bsb.middleware());
 
 export const router = {
   customers: authed.handler(({ context }) =>
-    bs.unwrap(context.db.customers.findMany({ limit: 20 })),
+    bsb.unwrap(context.db.customers.list({ limit: 20 })),
   ),
 };
 ```
@@ -89,20 +89,20 @@ status (RLS denials answer 403):
 ```ts title="src/server.ts"
 const os = implement(contract)
   .$context<OrpcRequestContext>()
-  .use(bs.middleware());
+  .use(bsb.middleware());
 const router = os.router({
   customers: {
     get: os.customers.get.handler(({ context, input }) =>
-      bs.unwrap(context.db.customers.findById(input.id)),
+      bsb.unwrap(context.db.customers.get(input.id)),
     ),
   },
 });
-const handle = bs.fetchHandler(new OpenAPIHandler(router), { prefix: "/api" });
+const handle = bsb.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" }))`
+`bsb.authed()` doesn't apply to a contract implementer. Guard one procedure
+with `os.customers.remove.use(bsb.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.
@@ -114,14 +114,17 @@ import { createEdge } from "better-supabase/edge";
 
 import { betterSupabase } from "../_shared/supabase.ts";
 
-export const bs = createEdge(betterSupabase, { cors: true });
+export const bsb = createEdge(betterSupabase, { cors: true });
 ```
 
 ```ts title="supabase/functions/api/index.ts"
-import { bs } from "./server.ts";
+import { bsb } from "./server.ts";
 
 Deno.serve(
-  bs.resources({ customers: { select: ["id", "name"] } }, { basePath: "/api" }),
+  bsb.resources(
+    { customers: { select: ["id", "name"] } },
+    { basePath: "/api" },
+  ),
 );
 ```
 
@@ -129,7 +132,7 @@ Deno.serve(
 
 `withBetterSupabase(server, { allow })` from `better-supabase/server` is one
 `@supabase/middleware` entry: it resolves the caller, guards, and contributes
-`bs`, `db`, `sql`, `jwtClaims`, `userClaims` and `authMode`. Put
+`bsb`, `db`, `sql`, `jwtClaims`, `userClaims` and `authMode`. Put
 `withPostgresClient` or `withCors` next to it, then run the array with the
 bridge for the framework:
 
@@ -181,16 +184,16 @@ import { guard, problemErrorHandler, toExpress } from "better-supabase/node";
 import { withBetterSupabase } from "better-supabase/server";
 import express from "express";
 
-import { bs } from "./lib/server";
+import { bsb } from "./lib/server";
 
 const app = express();
 app.use(
   toExpress([
-    withBetterSupabase(bs, { refresh: true, allow: ["user", "anon"] }),
+    withBetterSupabase(bsb, { refresh: true, allow: ["user", "anon"] }),
   ]),
 );
 app.get("/admin/members", guard({ roles: ["admin"] }), async (req, res) => {
-  res.json(await res.locals.db.members.findMany().orThrow());
+  res.json(await res.locals.db.members.list().orThrow());
 });
 app.use(problemErrorHandler());
 ```
@@ -211,7 +214,7 @@ Express's `res.locals` by extending `Express.Locals` with
 
 ```ts title="src/app.module.ts"
 consumer
-  .apply(toNestMiddleware([withBetterSupabase(bs, { allow: ["user"] })]))
+  .apply(toNestMiddleware([withBetterSupabase(bsb, { allow: ["user"] })]))
   .forRoutes("*");
 ```
 
@@ -225,7 +228,7 @@ export class NotesController {
   @Get()
   @UseGuards(guard({ roles: ["admin"] }))
   list(@Ctx("db") db: Db) {
-    return db.notes.findMany({ select: ["id", "title"] }).orThrow();
+    return db.notes.list({ select: ["id", "title"] }).orThrow();
   }
 }
 ```
@@ -235,13 +238,13 @@ export class NotesController {
 ```ts title="src/lib/server.ts"
 import { createAstro } from "better-supabase/astro";
 
-export const bs = createAstro(betterSupabase, { signIn: "/sign-in" });
-// src/middleware.ts: export const onRequest = bs.onRequest;
+export const bsb = createAstro(betterSupabase, { signIn: "/sign-in" });
+// src/middleware.ts: export const onRequest = bsb.onRequest;
 ```
 
-In a page, `const refused = await bs.guard(Astro, { roles: ["admin"] })`
-returns the refusal to send, and `bs.locals(Astro).db` is the caller's
-`db`. Wrap an Action's handler with `bs.action({ input, requireTenant }, fn)`.
+In a page, `const refused = await bsb.guard(Astro, { roles: ["admin"] })`
+returns the refusal to send, and `bsb.locals(Astro).db` is the caller's
+`db`. Wrap an Action's handler with `bsb.action({ input, requireOrganization }, fn)`.
 `createImageService({ url })` serves Storage images through Astro's image
 service.
 
@@ -249,15 +252,15 @@ service.
 import { createSolidStart } from "better-supabase/solid-start";
 import { getRequestEvent } from "solid-js/web";
 
-export const bs = createSolidStart(betterSupabase, {
+export const bsb = createSolidStart(betterSupabase, {
   getRequestEvent,
   signIn: "/sign-in",
 });
-// src/middleware.ts: export default createMiddleware(bs.middleware);
+// src/middleware.ts: export default createMiddleware(bsb.middleware);
 ```
 
-In a `"use server"` query, `const { db } = await bs.require()`; for forms,
-`bs.action({ input }, (input, { db }) => ...)`.
+In a `"use server"` query, `const { db } = await bsb.require()`; for forms,
+`bsb.action({ input }, (input, { db }) => ...)`.
 
 ## Nuxt and Nitro 2
 
@@ -278,7 +281,7 @@ import { toSession } from "better-supabase/server";
 
 import { betterSupabase } from "../_shared/supabase.ts";
 
-const bs = createMcp(betterSupabase, {
+const bsb = createMcp(betterSupabase, {
   name: "crm",
   version: "0.1.0",
   advertisedScopes: ["openid", "crm.read"],
@@ -296,7 +299,7 @@ const bs = createMcp(betterSupabase, {
   },
 });
 
-Deno.serve(bs.fetch);
+Deno.serve(bsb.fetch);
 ```
 
 Tools run as the calling user, so RLS applies to every tool call.

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

@@ -53,7 +53,7 @@ const memory = createMemory({
 ## Agents, connectors and scheduled tasks
 
 ```bash
-pnpm better-supabase add agents connectors ai-tasks
+pnpm better-supabase add agents connectors ai-schedules
 ```
 
 - `createAgents({ transport })` stores assistants: `agents.create(organizationId, { slug, name, instructions, tools, knowledgeScopes })`,
@@ -70,9 +70,9 @@ pnpm better-supabase add agents connectors ai-tasks
   returns `{ tools, skipped, close }`. Call `close()` in a `finally`.
   Review changed tool lists with `connectors.fingerprints.check`, `.approve`
   and `.reject`.
-- `createAiTasks({ transport, service, run })` stores scheduled prompts with
+- `createAiSchedules({ transport, service, run })` stores scheduled prompts with
   a `cron` and a `timezone`. `tick()` queues the due runs (handle them with
-  `runJob()` on the `ai_task_run` queue when the `jobs` module is
+  `runJob()` on the `ai_task_run` queue when the `queue` module is
   installed); without jobs, call `drain()` from a cron route.
 
 ## Files, cache and batches
@@ -89,7 +89,7 @@ pnpm better-supabase add agents connectors ai-tasks
 
 ```bash
 pnpm add eve @workflow/world @workflow/world-postgres pg
-pnpm better-supabase add workflow-sdk-world ai-chat memory knowledge credentials inbox
+pnpm better-supabase add workflow-sdk ai-chat memory knowledge credentials inbox
 ```
 
 Set `experimental.workflow.world` to `"better-supabase/workflow-sdk/world"`

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

@@ -13,26 +13,26 @@ import { createExpo } from "better-supabase/expo";
 
 import { betterSupabase } from "./index";
 
-export const bs = createExpo(betterSupabase);
+export const bsb = createExpo(betterSupabase);
 ```
 
 ```tsx title="src/app/customers/index.tsx"
-export const loader = bs.loader(
-  ({ db }) => db.customers.findMany({ select: ["id", "name"] }).orThrow(),
+export const loader = bsb.loader(
+  ({ db }) => db.customers.list({ select: ["id", "name"] }).orThrow(),
   { allow: ["user"] },
 );
 ```
 
 ```ts title="src/app/+middleware.ts"
-export default bs.middleware();
+export default bsb.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.
+- `bsb.loader` returns an `expo-server` `LoaderFunction`. Inside an existing `createServerLoader(async (request, params) => ...)`, call `const { db } = await bsb.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`.
+- API routes: `export const GET = bsb.handler((request, { db }) => db.customers.list())` in `+api.ts`.
 
 ## Device: `better-supabase/client/native`
 
@@ -54,7 +54,7 @@ const supabase = createClient(url, key, {
   },
 });
 autoRefreshOnForeground(supabase, AppState);
-export const bs = createNativeClient(betterSupabase, supabase);
+export const bsb = createNativeClient(betterSupabase, supabase);
 ```
 
 - `autoRefreshOnForeground(supabase, AppState)` refreshes the session only while the app is active; supabase-js can't detect the background on React Native.
@@ -63,7 +63,7 @@ export const bs = createNativeClient(betterSupabase, supabase);
 - Put device-only code (SecureStore, PowerSync) in `.native.ts` files or modules only they import.
 
 Done when the web export has no `expo-secure-store` or PowerSync code, a loader
-answers 401 for a signed-out request, and a native screen reads with `bs.db`.
+answers 401 for a signed-out request, and a native screen reads with `bsb.db`.
 
 Docs: https://bettersupabase.com/docs/frameworks/expo.md and
 https://bettersupabase.com/docs/frontend/react-native.md.

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

@@ -1,22 +1,29 @@
 # PowerSync (offline reads and writes)
 
-```ts title="src/lib/powersync/database.ts"
-import { powersyncExecutor } from "better-supabase/powersync";
+```ts title="src/lib/supabase/client.native.ts"
+import { createNativeClient } from "better-supabase/client/native";
+import { powersyncEngine } from "better-supabase/powersync";
 
-export const local = betterSupabase.connect(powersyncExecutor(powersync));
+export const bsb = createNativeClient(betterSupabase, supabase, {
+  engine: powersyncEngine(powersync, { connector, local: ["customers"] }),
+});
 ```
 
-- `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 (nested, filtered, ordered, limited, `required`), related counts and related aggregates run on SQLite as one statement, so sync the included tables too. Full-text search, `db.$rpc`, function sources 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, and pass a `betterSupabase.spec.<table>.<method>(...)` spec to check a single read.
-- `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.
+- `bsb.db.customers.list(...)`, `list.run(bsb.db, query)` and the generated hooks (`useCustomers(...)`) run on the device's SQLite database and return the same rows (casing, Temporal values) as PostgREST. Tables missing from `local` run on PostgREST; leave `local` out when every table syncs.
+- Hooks read again when PowerSync reports a change to their table. A hook named after something else (`defineDataHooks("customer-pages", ...)`) names its tables: `tables: { "customer-pages": ["customers"] }`.
+- `useSyncStatus()` and `useConflicts()` from `better-supabase/react` read the engine's sync state and the connector's rejected changes.
+- Includes (nested, filtered, ordered, limited, `required`), related counts and related aggregates run on SQLite as one statement, so sync the included tables too. Full-text search, function sources and writes to tables without a primary key compile to `unsupported`. Assert `checkSqlite(betterSupabase, list, { all: true })` is `[]` in a test for every list a native screen runs, and pass a `betterSupabase.spec.<table>.<method>(...)` spec to check a single read.
+- Unsupported reads and `db.$rpc` fall back to PostgREST (online only); writes never fall back. Every hook reads again when PowerSync reconnects. Pass `fallback: false` to keep every call on the device. Prefer syncing a summary table through sync rules when the screen must work offline.
+- To run the repositories without the client: `betterSupabase.connect(powersyncExecutor(powersync))`.
 - `ilike` is SQLite `like` (case-insensitive for ASCII only).
 
 ## Uploading local writes
 
-In the connector's `uploadData`, replay each `CrudEntry` through the online
-client's repositories (`bs.db` from `better-supabase/client/native`), so RLS
-and validation run:
+In the connector's `uploadData`, replay each `CrudEntry` through repositories
+on PostgREST, so RLS and validation run. `bsb.db` runs on the device with the
+engine, so build a second client without it:
+`const server = bindClient(betterSupabase, supabase)` from
+`better-supabase/client`, in its own module to avoid an import cycle.
 
 | `entry.op` | Call                                        |
 | ---------- | ------------------------------------------- |
@@ -35,9 +42,9 @@ Never throw for a kind that can't succeed: it blocks the upload queue.
 `createUploadConnector({ endpoint, supabase, tables })` from
 `better-supabase/powersync` does this replay and the outcome mapping for you:
 
-- `tables: { customers: bs.db.customers }` takes a repository; every generated repository fits `UploadRepository<Insert, Key>` without a cast.
-- `uploadRoute(bs.db.attachments, { put: "create" })` for write-once tables: a `PUT` calls `create` and a `conflict` counts as applied (the row is already on the server); a `PATCH` is discarded as `unsupported`.
+- `tables: { customers: server.db.customers }` takes a repository; every generated repository fits `UploadRepository<Insert, Key>` without a cast.
+- `uploadRoute(server.db.attachments, { put: "create" })` for write-once tables: a `PUT` calls `create` and a `conflict` counts as applied (the row is already on the server); a `PATCH` is discarded as `unsupported`.
 - `onError: (error, { phase }) => ...` logs a failed `getSession` (`phase: "credentials"`, kind `unauthorized` or `network`; `fetchCredentials` returns `null`) and uploads that stay queued for a retry (`phase: "upload"`).
 
-Docs: https://bettersupabase.com/docs/repository/powersync.md and
+Docs: https://bettersupabase.com/docs/frontend/powersync.md and
 https://bettersupabase.com/docs/guides/offline-first.md.

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

@@ -55,7 +55,7 @@ import {
   vaultCredentials,
 } from "better-supabase/credentials";
 
-export const bs = createServer(betterSupabase, {
+export const bsb = createServer(betterSupabase, {
   credentials: vaultCredentials({
     transport: sqlTransport(postgres.asService()),
   }),
@@ -79,7 +79,7 @@ await fetch(url, { headers: token.headers });
 ## The Workflow World on Supabase (Node only)
 
 ```bash
-pnpm better-supabase add workflow-sdk-world   # adds workflows and jobs
+pnpm better-supabase add workflow-sdk   # adds workflows and jobs
 pnpm add workflow @workflow/world @workflow/world-postgres pg
 ```
 
@@ -101,7 +101,7 @@ caller before `resumeHook`, `protectWebHandler(handler, key, { can })` refuses c
 `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`.
+`bsb.trigger`.
 
 Docs: https://bettersupabase.com/docs/blocks/streams.md,
 https://bettersupabase.com/docs/extending/credentials.md and