@protobase/cli 0.66.6 → 0.66.8

package/skills/protobase/references/reference/live.md

@@ -43,6 +43,10 @@ It is live data, not multiplayer editing: two people editing the same record sti
 
 Connecting again with `?after=<cursor>` catches up on what was missed while disconnected. [`client.live({ onChanges, onResync })`](client.md) of `@protobase/client` follows the stream and connects again by itself, as the app does. However many callers of one client follow it, they share one stream, so a page with many live views holds one connection, which matters under HTTP/1.1, where a browser opens at most six to a host.
 
+## Polling, then a socket
+
+`pollThenSocket({ poll, onError, socket, onMessage, pollMs?, switchAfterMs?, socketFirst? })` of `@protobase/client`, in the browser and on Node, keeps up with anything that changes, until the function it returns is called. It calls `poll` at once and again `pollMs` (5 seconds) after each call ends, also after one that rejected, whose error goes to `onError`, and after `switchAfterMs` (30 seconds) opens the WebSocket `socket()` returns, such as `() => new WebSocket(url)`. Once the socket is open, polling stops: `poll` runs once more, for what changed before the socket opened, and `onMessage` gets each message's data. When the socket closes, or never opens, it polls again at once and opens a new socket `switchAfterMs` later. Polling goes on while a socket connects, so nothing waits on it. A short visit thus never opens a socket; `socketFirst: true` opens one at once instead, for a process that stays, and polls only while it is down.
+
 Who is on a record's page and what they send each other, which no change of a record says, goes over the record's [channel](channels.md).
 
 ## The table

package/skills/protobase/references/reference/mcp.md

@@ -14,7 +14,7 @@ An app can serve an MCP endpoint: a person adds its address to an AI client that
 export default defineConfig({ auth: { mcp: true } })
 ```
 
-Every auth store has the OAuth tables, so turning it on needs no migration. The endpoint is `https://<app>/api/mcp`, or the path `auth.mcp.path` names. How clients register, how people sign in and allow them, and how they disconnect them is in [OAuth for MCP clients](auth.md#oauth-for-mcp-clients).
+Every auth store has the OAuth tables, so turning it on needs no migration. The endpoint verifies its tokens with the app's own sign-in, so an app whose authenticator is its own, `auth/authenticate.ts`, does not start with MCP on. The endpoint is `https://<app>/api/mcp`, or the path `auth.mcp.path` names. How clients register, how people sign in and allow them, and how they disconnect them is in [OAuth for MCP clients](auth.md#oauth-for-mcp-clients).
 
 ## Connecting a client
 
@@ -33,10 +33,18 @@ Give the client the endpoint's address. It finds the app's sign-in from there, o
 
 ## The app's icon
 
+:::caution[Beta]
+Clients that draw no SVG get no icon for an app without PNGs of its own, as below.
+:::
+
 The endpoint names the app's [icon](app-identity.md#the-icons) to the client when it connects (`serverInfo.icons`), at absolute addresses on the app's origin: the project's 192 pixel, touch and 512 pixel PNGs it has, then its `protobase.favicon.svg`, or Protobase's without one. A client that draws server icons shows it beside the app's name. <gap>An app without PNGs of its own cannot offer clients that draw no SVG an icon because PNG versions of Protobase's icon are not implemented.</gap>
 
 ## The tools
 
+:::caution[Beta]
+`count_records` cannot count soft-deleted records per value yet, as below.
+:::
+
 Each tool reads as the signed-in person: their role's access rules, row filters, tenant and hidden fields apply as in the [REST API](api.md#access).
 
 | Tool | What it does |
@@ -90,6 +98,10 @@ It runs one `SELECT` in a read-only transaction, as the app's database role, **o
 
 ### Writes
 
+:::caution[Beta]
+An approval cannot be answered on another server instance or after a restart yet, as below.
+:::
+
 `mcpEndpoint.writes` also offers four tools that change records, to everyone signed in:
 
 ```ts
@@ -100,7 +112,7 @@ export default defineConfig({ auth: { mcp: true }, mcpEndpoint: { writes: true }
 | --- | --- |
 | `create_record` | Creates a record of a resource from `data`, field names to values, and returns its key and ETag with the fields it wrote, see [What a write returns](#what-a-write-returns). |
 | `update_record` | Changes the fields in `data` of one record by its key, and returns its key and new ETag with the fields it set. With the `etag` that `get_record` gave, it fails when someone changed the record since. It does not set the field a soft delete sets: a delete goes through `delete_record`. |
-| `delete_record` | Deletes one record by its key and the `etag` that `get_record` gave, and fails when someone changed the record since. A resource with a [soft delete](data-config.md) keeps the record, deleted; any other loses it for good. |
+| `delete_record` | Deletes one record by its key. With the `etag` that `get_record` gave, it fails when someone changed the record since; without one, or with `*`, it deletes the record whatever its version. A resource with a [soft delete](data-config.md) keeps the record, deleted; any other loses it for good. |
 | `batch_write` | Creates, updates and deletes records across resources in one transaction, see [Batch writes](#batch-writes). |
 
 Each write goes through the REST API as the person: their role's access rules, `validate`, write hooks, events and webhooks apply, so the client can do only what the person may do in the app.
@@ -129,6 +141,10 @@ A write returns its record small, so changing one field of a large record does n
 
 #### Writes without approval
 
+:::caution[Beta]
+A deleted record cannot be restored over MCP yet, as below.
+:::
+
 An app that runs service accounts over MCP, such as a backend job or an agent with no person present, names their roles in `mcpEndpoint.writes`:
 
 ```ts
@@ -162,6 +178,10 @@ A batch is checked before the person is asked: an operation other than a create,
 
 ## The app's own tools
 
+:::caution[Beta]
+Nothing refuses a tool result larger than an AI client takes yet, as below.
+:::
+
 `mcp/tools.ts` adds tools of the app's own, offered after the built-in ones to everyone signed in, whatever `mcpEndpoint.writes` says. Its default export is an array of `defineTool(...)` from `@protobase/server`, the same shape as the [assistant's own tools](assistant.md#the-apps-own-tools): a `name` of 1 to 64 letters, digits, `_` or `-`, a `description` the client's model reads, `parameters`, the JSON Schema of its arguments, which the endpoint checks each call against, `annotations`, MCP's tool hints such as `readOnlyHint`, optionally a `title` and `_meta`, which `tools/list` gives clients as they are, and `run(args, context)`, which returns the text the client reads. The file is found when the app starts, under `protobase dev` and `protobase serve` alike, and only with `auth.mcp` on; with `mcpEndpoint: false` it offers nothing.
 
 `context` holds the caller's `session`, the `locale` they read, `approve(request)`, `resources()`, the resources they may read, and `records`, the app's records **as that person**: their role's access rules, tenant, hidden fields, `validate` and write hooks apply, as in the REST API and the built-in tools. Its methods are the assistant's, listed [there](assistant.md#the-apps-own-tools); a refusal rejects with an `HttpProblem`. `show` does nothing over MCP, and there is no `conversation`.

package/skills/protobase/references/reference/plugins.md

@@ -42,8 +42,10 @@ Each place a plugin can fill is an extension point. The config names it, or a pl
 | [Action handler](custom-components.md#action-handlers) | `a.action('name')` in a view | `actions: { name }` | `ActionContext` | The button is disabled |
 | [Shell slot](custom-components.md#shell-slots) | Nothing: drawn on every page | `shell: { actions, rightPanel, logo, bell }` | Nothing; `logo` gets `compact`, `workspace`, `appName` and `appIcon` | Not drawn; Protobase's logo for `logo`, its notification bell for `bell` |
 | [Before sign-in](#before-sign-in) | `beforeSignIn: true` where the plugin is listed | `beforeSignIn` | `children`, `params`, `removeParams`, `signedIn` | The pages as they are without it |
+| Rules and hooks a view names | A [drop rule](ui-config.md#drop-rules), [board drop](ui-config.md#board-drops), [title rule](ui-config.md#titles-per-reader) or [marks hook](sidebar.md#marks-per-reader) by name in a view | `dropRules`, `boardDrops`, `titles`, `marks` | What its page says | What its page says |
+| [Presence](status.md#in-the-app) | Nothing: read on the members page and the sidebar | `presence` | Nothing; a hook | No one shows as online or away |
 
-Components and cards share one namespace of names, which `component('Name')` joins to the export; field types and action handlers each have their own. Props that name fields go through the same walker as everything else in `/api/meta`, so a user who may not read a field never gets it in a component's props; a field type's `props` are plain data, and a field the user may not read is left out of the view, field type and all.
+Components and cards share one namespace of names, which `component('Name')` joins to the export; field types, action handlers, drop rules, board drops, title rules and marks hooks each have their own. Props that name fields go through the same walker as everything else in `/api/meta`, so a user who may not read a field never gets it in a component's props; a field type's `props` are plain data, and a field the user may not read is left out of the view, field type and all.
 
 New extension points are new optional keys of `definePlugin`, so adding one never changes what a plugin built before it does.
 
@@ -67,7 +69,7 @@ export { DraftOrders } from './components/draft-orders'
 export default definePlugin({ name: 'sales-tools', actions: { remindCustomer } })
 ```
 
-It is written as a project's `protobase.ui.tsx` is: each component exported under the PascalCase name the config declares, from a file of its own, and the rest in the default export, `definePlugin({ name, actions, fields, shell, beforeSignIn, extends })` (`defineUi` is the same function). Its components use the hooks and components of `@protobase/ui`, which read the API as the signed-in user, under the same access rules as everything else.
+It is written as a project's `protobase.ui.tsx` is: each component exported under the PascalCase name the config declares, from a file of its own, and the rest in the default export, `definePlugin({ name, actions, fields, shell, beforeSignIn, extends, ... })` (`defineUi` is the same function), with the keys of [Extension points](#extension-points). Its components use the hooks and components of `@protobase/ui`, which read the API as the signed-in user, under the same access rules as everything else.
 
 **Imports.** `react`, `react/jsx-runtime` (the JSX), `react-dom` and `@protobase/ui`, by those names, come from the app. Everything else a plugin imports, its own files, icons or a chart library, is built into it. Other modules of those packages, such as `react-dom/client` or a file inside `@protobase/ui`, fail the build: a copy of its own would not work with the app's. Read data with `@protobase/ui`'s hooks (`useList`, `useRecord`, `useClient`), which share the app's cache: a data library of the plugin's own keeps a cache of its own.
 
@@ -235,7 +237,7 @@ When the user signs in, or before for a plugin that loads [before sign-in](#befo
 - The files in `assets/`, named by their content, forever (`Cache-Control: public, max-age=31536000, immutable`).
 - From another origin than the app's, with `Access-Control-Allow-Origin` (`*` is fine for public files), since the browser loads modules and `plugin.json` with CORS.
 
-The plugins are merged in the order listed. Two of them cannot define one name: a plugin that defines a component, action handler or field type an earlier one defines is turned off, and the earlier one keeps it. So the project's own names win over a platform's, and within a bundle the build already fails on such a name.
+The plugins are merged in the order listed. Two of them cannot define one name: a plugin that defines a component, action handler, field type, drop rule, board drop, title rule or marks hook an earlier one defines is turned off, and the earlier one keeps it. So the project's own names win over a platform's, and within a bundle the build already fails on such a name. The logo, the bell and the presence hook come from the last one that sets them, so the project's own replace a plugin's.
 
 `protobase dev` loads plugins the same way, its page sharing the same four modules. The project's own `protobase.ui.tsx` is built into the dev page with hot reload instead, merged after the plugins, and keeps its names over theirs.
 
@@ -326,7 +328,7 @@ From `@protobase/ui`:
 
 | | |
 | --- | --- |
-| `definePlugin(config)` | Typed identity for a plugin's default export: `name`, `actions`, `fields`, `shell`, `beforeSignIn`, `extends`, as `defineUi`. |
+| `definePlugin(config)` | Typed identity for a plugin's default export: `name`, `extends` and the keys of [Extension points](#extension-points), as `defineUi`. |
 | `BeforeSignInProps` | The props of a plugin's [`beforeSignIn`](#before-sign-in) component. |
 | `usePlugin()` | The plugin the calling component belongs to (see [above](#writing-a-plugin)). |
 | `useResourceClient(resource)` | The client of the API that serves a resource: the app's own, or a source's for a [remote resource](remote-resources.md). |

package/skills/protobase/references/reference/sidebar.md

@@ -6,6 +6,8 @@ How sidebar entries are grouped and which icon each shows, how an entry lists re
 
 The admin's sidebar has one entry per resource view, grouped by `nav.group` (default: the database schema, with no group name for `public`) and sorted by `nav.order`, then by the order `config/index.ts` exports them, in `protobase dev` and in a built bundle alike. The app opens on the first entry. A view's [named lists](ui-config.md#more-than-one-list) are entries of their own, placed by their own `nav`. `nav({ hidden: true })` leaves a resource out, for line and link tables; a resource in the [user menu](user-menu.md) is left out too. [Composed pages](layouts.md#setup) have entries of their own, and groups that hold pages come first. A [remote resource](remote-resources.md) has its entry where its source's view places it; while its source cannot be reached, it sits under the source's label, marked "Cannot reach" with the source's name.
 
+Below the `md` breakpoint (768px) the sidebar is a drawer, which the top bar's menu button opens, or **More** on a [bottom bar](bottom-bar.md).
+
 ## Sidebar icons
 
 Each resource shows the icon its view names, in the sidebar, the [bottom bar](bottom-bar.md) and the [user menu](user-menu.md), and its [named lists](ui-config.md#more-than-one-list) show the same icon:
@@ -49,6 +51,10 @@ export const directMessagesView = view<typeof directMessages>('direct_messages')
 
 ## Recent records
 
+:::caution[Beta]
+A marks hook that throws stops the whole sidebar, not only its own group.
+:::
+
 An entry can list a few of its records under it, each with a status dot, so the ones that need attention are one click away:
 
 ```ts

package/skills/protobase/references/reference/supabase-realtime.md

@@ -4,6 +4,10 @@
 
 The Realtime-compatible /api/sb/realtime/v1 that supabase-js's channel() joins, for postgres_changes checked under the subscriber's RLS policies, broadcasts and presence, on public and private channels, and broadcasts from the database.
 
+:::caution[Beta]
+A channel cannot `select` columns, a policy cannot read `request.headers`, and a project that was not imported has no `realtime.send()` yet: see the limits in each section.
+:::
+
 An app with API keys also serves `/api/sb/realtime/v1/websocket`, the socket that supabase-js's `channel()` joins. An app moved from Supabase keeps its `postgres_changes` listeners, broadcasts and presence: point the client at the app's `/api/sb` and give it the publishable key.
 
 ```ts
@@ -18,7 +22,7 @@ supabase
 
 ## Keys, roles and tokens
 
-The keys are `apiKeys` in `protobase.config.ts`, `{ publishable_key, secret_key }`, or else `PROTOBASE_PUBLISHABLE_KEY` and `PROTOBASE_SECRET_KEY`. The socket sends the key in its URL and is refused with `401` without a key of the app. Each channel joins with the client's access token: a signed-in user's token makes it `authenticated` with the token's claims, the publishable key alone `anon`, the secret key alone the app's own role. A token the client refreshes on an open socket replaces the channel's; a channel whose token expires is closed with a `Token has expired` system message, as on Supabase.
+The keys are `apiKeys` in `protobase.config.ts`, `{ publishable_key, secret_key }`, or else `PROTOBASE_PUBLISHABLE_KEY` and `PROTOBASE_SECRET_KEY`. The socket sends the key in its URL and is refused with `401` without a key of the app. Each channel joins with the client's access token: a user's access token from [`/api/sb/auth/v1`](auth.md#supabase-js-and-supabasessr), which supabase-js sends once `supabase.auth` has signed in, makes it `authenticated` with the token's claims, the publishable key alone `anon`, the secret key alone the app's own role. A token the client refreshes on an open socket replaces the channel's; a channel whose token expires is closed with a `Token has expired` system message, as on Supabase.
 
 The server serves the socket when the host gives `createAdmin` its WebSocket upgrade: `protobase serve` does, on Bun and Node, and so does `protobase dev`, beside Vite's hot reload socket. An edit to the project under `protobase dev` closes the open sockets with code `1012`, and supabase-js reconnects to the rebuilt API.
 

package/skills/protobase/references/reference/supabase-rest.md

@@ -4,6 +4,10 @@
 
 The PostgREST-compatible /api/sb/rest/v1 that supabase-js's from() and rpc() call, under the tables' RLS policies.
 
+:::caution[Beta]
+Some PostgREST features are not supported yet, such as many-to-many embeds, spreads, CSV, schemas other than `public` and aggregates: see [What it understands](#what-it-understands).
+:::
+
 An app with API keys also serves `/api/sb/rest/v1`, the API that supabase-js's `from()` and `rpc()` call. An app moved from Supabase keeps its data calls: point the client at the app's `/api/sb` and give it the publishable key.
 
 ```ts
@@ -20,7 +24,7 @@ The keys are `apiKeys` in `protobase.config.ts`, `{ publishable_key, secret_key
 | The request sends | It runs as |
 | --- | --- |
 | the publishable key | `anon` |
-| either key and a signed-in user's token | `authenticated` |
+| either key and a user's access token from [`/api/sb/auth/v1`](auth.md#supabase-js-and-supabasessr) | `authenticated` |
 | the secret key | the app's own role, which owns the tables |
 
 The transaction sets the role with `SET LOCAL ROLE` and the token's claims in `request.jwt.claims` and `request.jwt.claim.sub`, so Supabase's `auth.uid()`, `auth.role()` and `auth.jwt()` work, and the tables' RLS policies decide what the request may read and write. The resources' access rules (`.access(...)`) do not apply here: a table needs its own grants and policies, and one without a grant to `anon` or `authenticated` refuses them. The `role` claim is the database role, as on Supabase. The database needs the `anon` and `authenticated` roles, and the app's role must be allowed to `SET ROLE` to them.

package/skills/protobase/references/reference/supabase-storage.md

@@ -4,6 +4,10 @@
 
 The Storage-compatible /api/sb/storage/v1 that supabase-js's storage calls, over the app's file provider, under the restored storage policies.
 
+:::caution[Beta]
+Image transforms, resumable uploads, the S3 protocol and object versioning are not supported yet: see [What it serves](#what-it-serves).
+:::
+
 An app with API keys also serves `/api/sb/storage/v1`, the API that supabase-js's `storage` calls. An app moved from Supabase keeps its uploads, downloads, public URLs and signed URLs: point the client at the app's `/api/sb` and give it the publishable key.
 
 ```ts
@@ -24,7 +28,7 @@ The keys are `apiKeys` in `protobase.config.ts`, `{ publishable_key, secret_key
 | The request sends | It runs as |
 | --- | --- |
 | the publishable key | `anon` |
-| either key and a signed-in user's token | `authenticated` |
+| either key and a user's access token from [`/api/sb/auth/v1`](auth.md#supabase-js-and-supabasessr) | `authenticated` |
 | the secret key | the app's own role, which owns the tables |
 
 The role is set with `SET LOCAL ROLE` and the token's claims in `request.jwt.claims` and `request.jwt.claim.sub`, so Supabase's `auth.uid()` works in the policies. The database needs the `anon` and `authenticated` roles, and the app's role must be allowed to `SET ROLE` to them. Every read and write of `storage.objects` and `storage.buckets` runs as that role, with the token's claims set, so the restored policies decide, as on Supabase:

package/skills/protobase/references/reference/theme.md

@@ -123,7 +123,7 @@ The list is `packages/ui/src/tokens.css`, and a test fails when one of its token
 
 ## Logo and favicon
 
-The sidebar shows Protobase's logo, its mark alone when the sidebar shows only icons, or, for a project with its own favicon, that icon and the app's name ([App identity](app-identity.md)). A project draws something else with `shell.logo` in `protobase.ui.tsx`, a component drawn in its place ([Shell slots](custom-components.md#shell-slots)); it draws with these tokens like the rest of the app.
+The sidebar's logo is the project's own favicon, or Protobase's mark without one, beside the app's [name](app-identity.md#the-name), with the organization the user works in under it, and the icon alone when the sidebar shows only icons. An app that keeps Protobase's name and has no favicon of its own shows Protobase's wordmark beside the mark. A project draws something else with `shell.logo` in `protobase.ui.tsx`, a component drawn in its place ([Shell slots](custom-components.md#shell-slots)); it draws with these tokens like the rest of the app.
 
 The browser tab shows Protobase's mark. A project shows its own with a `protobase.favicon.svg` at its root, beside `protobase.theme.css`: the app's `index.html` links `/protobase.favicon.svg`, which `protobase build` writes to the bundle's `public/`, the project's file or Protobase's without one, and which `protobase dev` serves the same way. An SVG can follow the system's light or dark with a `prefers-color-scheme` media query inside it, as Protobase's does. PNGs beside it serve the platforms that take no SVG, such as an iPhone's home screen ([App identity](app-identity.md#the-icons)).
 

package/skills/protobase/references/reference/ui-config.md

@@ -60,7 +60,11 @@ export const repairsView = view<typeof repairs>('repairs')
 | `.signIn({ title, description, benefits?, icon?, signUp? })` | What a visitor who is not signed in is told about the resource, in place of its list and by a card's favorite button. See [Sign-in prompts](#sign-in-prompts). |
 | `.form((r) => ({ name, fields, thanks, title?, perMinute? }))` | A public form at `/-/forms/<name>` that creates a record for anyone, signed in or not, behind a rate limit and a bot check. See [Public forms](forms.md). |
 
-A browser tab names what it shows, then the app's name ([`name`](config/app.md#name)): `Nordlicht GmbH · Companies · Protobase` on a record page, the plural on a list, `New company · Companies · Protobase` on the create form, and a composed page's title on that page.
+A browser tab names what it shows, then the app's name ([`name`](config/app.md#name)): `Nordlicht GmbH · Companies · Protobase` on a record page, the plural on a list, `New company · Companies · Protobase` on the create form, and a composed page's title on that page, after the label of its tab when it has tabs.
+
+### Breadcrumbs
+
+The top bar shows where a page is: the sidebar group, the list and the record's title, each a link back. On a phone, a back button before them goes to the one just before the current page.
 
 ### Titles per reader
 
@@ -607,7 +611,7 @@ The create form at `/<resource>/new`, not a page of the app's own, can open the
 
 ## Sign-in prompts
 
-`.signIn({ title, description, benefits?, icon?, signUp? })` on a view tells a visitor who is not signed in what they could do with the resource once signed in. Where a signed-in user sees the list, the visitor sees the prompt: an icon (`icon`, as for field hints, a sign-in icon by default), `title`, `description` and a line per `benefits`, with **Sign in**, which opens the sign-in page and comes back to the same address. A card's [favorite button](#favorites) that saves to the resource, and a list's [Save search](#saved-searches) button that saves to it, open the same prompt as a dialog, with **Not now** to close it. With [open sign-up](auth.md#open-sign-up) on the server, the prompt also offers **Create an account**, which opens the app's own sign-up page. `signUp: { label, href }` names a page elsewhere instead, `https://`, `http://` or `mailto:`, opened in a new tab.
+`.signIn({ title, description, benefits?, icon?, signUp? })` on a view tells a visitor who is not signed in what they could do with the resource once signed in. Where a signed-in user sees the list, the visitor sees the prompt: an icon (`icon`, as for field hints, a sign-in icon by default), `title`, `description` and a line per `benefits`, with **Sign in**, which opens the sign-in page and comes back to the same address. A card's [favorite button](#favorites) that saves to the resource, and a list's [Save search](#saved-searches) button that saves to it, open the same prompt as a dialog, with **Not now** to close it. With [open sign-up](auth.md#open-sign-up) on the server, the prompt also offers **Create an account**, which opens the app's own sign-up page. `signUp: { label, href }` names a page elsewhere instead, `https://`, `http://` or `mailto:`, opened in a new tab. A visitor is most likely new, so where the prompt offers to make an account, that is its primary action and **Sign in** the secondary one.
 
 ```ts
 view<typeof favorites>('favorites').signIn({

package/skills/protobase/references/reference/versioning.md

@@ -49,9 +49,12 @@ Every commit message follows [Conventional Commits](https://www.conventionalcomm
 3. The tag is pushed, and the GitHub release of the tag gets the notes.
 4. Beside the checks, a pack job takes the tag `bun run release --dry-run` predicts, and `scripts/stamp-version.mjs` writes its version into every `package.json` and `bun.lock` in the runner, never committed. `scripts/publish.mjs --pack --out` then builds every package to `dist` and packs it with Bun (the private `@protobase/presets` is not published). Once the tag is pushed, npm, under Node, publishes those tarballs with [trusted publishing](https://docs.npmjs.com/trusted-publishers) and provenance (`scripts/publish.mjs --from`); there is no npm token, and only the publish job holds the identity token it needs. A tag other than the version the tarballs were stamped with fails the publish before anything is uploaded, and a run that cut no release packs and publishes nothing.
 5. Once npm serves the packages, the tag's version is written into the `package.json` files the same way, and `bun run images:context <image>` writes each image's build context at the tag from them, and the images are built natively for `linux/amd64` and `linux/arm64` and pushed to GitHub's registry as `ghcr.io/prototeamhq/protobase:<version>` and `ghcr.io/prototeamhq/protobase-dev:<version>` (see [Deploy](../guides/deploy.md#images)). A release whose publish failed has no images.
+6. Once npm serves the packages, `scripts/bump-repos/main.ts` starts the `protobase-bump.yml` workflow, with the release's version, of each repository the `PROTOBASE_BUMP_REPOS` secret lists, using the `PROTOBASE_BUMP_TOKEN` secret; an unset or empty list bumps nothing. Each listed repository owns that workflow, with a `version` input: it moves the repository's `@protobase` packages to the release in a pull request of its own, which merges itself once its CI is green and otherwise stays open for a fix. A repository that cannot be started within a minute fails the job after the others were started, and nothing else waits on it.
 
 When `main` moved on while the checks ran, the run of the newer push releases both. `bun run release --dry-run` prints the next version and its notes without tagging anything.
 
+A push made with GitHub Actions' own token, such as a pull request the AI review merged, [starts no workflow](https://docs.github.com/en/actions/concepts/security/github_token), but a run by hand always starts one. Running the workflow by hand from `main` without a tag (`gh workflow run release.yml`) releases `main`'s head as a push does, with the same checks, which then run in full, commitlint over the commits since the last `v<version>` tag, and the same release. A release started while another runs waits for it.
+
 Running the workflow by hand with a tag (`gh workflow run release.yml -f tag=v0.1.0`) only packs and publishes: the packages at that tag and its version, skipping every version npm already has, and the images, which repeats a missed or half-done publish. A publish that npm fails because it could not read the identity token, or because Sigstore's transparency log already holds its provenance (a 409 after npm's own retry), is tried again up to 3 times, and the 409 counts as published when npm has the version; any other failure fails the run. `node scripts/publish.mjs --dry-run` packs the packages and shows what `npm publish` would send, and `node scripts/publish.mjs --pack`, which CI runs, packs every package without asking npm or publishing. Each package on npm trusts `release.yml` of `PrototeamHQ/protobase` as its publisher; a new package has to be published once by hand before that can be set up. The workflow pushes the images with its own token; a new image on GitHub's registry starts out private and is made public once in its package settings.
 
 ## Bundled and locked projects
@@ -61,11 +64,11 @@ Where a project's `package.json` lists the `@protobase` packages decides whose c
 | `package.json` | Mode | Copies used by `dev`, `build` and `protobase run` | The bundle's `protobase` |
 | --- | --- | --- | --- |
 | `@protobase/*` in `devDependencies` | bundled (what the presets write) | the CLI's own | the CLI's version |
-| `@protobase/*` in `dependencies` | locked | the project's installed copies | the installed version |
+| `@protobase/*` in `dependencies` | locked | the project's installed copies, but the build reads the config with the CLI's own | the installed version |
 | no `@protobase/*`, or no `package.json` | bundled | the CLI's own | the CLI's version |
 
 - **Bundled.** Nothing of Protobase has to be installed: a `protobase.config.ts` alone is a project. The CLI that runs, installed globally or as the project's dev dependency, supplies every `@protobase` package and every package the serve runtime supplies to a bundle (`kysely`, `pg`, `react`, ...), whatever the project installed: to `dev`'s API and page, to the build, to [`protobase run`](cli.md#run) and, through [`protobase types`](cli.md#types), to the editor. Installing a newer CLI that the specifier holds updates the app with no change to its files or lockfile: dev and the next build use it, and the bundle names its version. `@types/react` and `@types/node` stay the project's own dev dependencies, since the CLI carries no types for them.
-- **Locked.** Move every `@protobase` package to `dependencies` at one exact version, and install. Dev, the build and scripts use the installed copies, and the bundle names that version, so a host serves exactly it. A CLI installed elsewhere hands a locked project over to the `@protobase/cli` it installed (see [CLI](cli.md)). The version moves only when the specifier and the lockfile do.
+- **Locked.** Move every `@protobase` package to `dependencies` at one exact version, and install. Dev and scripts use the installed copies, and the bundle names that version, so a host serves exactly it. The build reads the config with the building CLI's own `@protobase` packages, as a serve runtime supplies its own to the bundle, so it loads one copy of each. A CLI installed elsewhere hands a locked project over to the `@protobase/cli` it installed (see [CLI](cli.md)). The version moves only when the specifier and the lockfile do.
 
 Packages the runtime supplies, such as React, may be listed for their types, in either mode: in a bundle the runtime's copy runs, whichever the project installed. `dependencies` holds the packages the project's own code uses at runtime.
 

package/skills/protobase/references/reference/webhooks.md

@@ -116,6 +116,8 @@ It adds two pages, over a `webhooks` schema that [`protobase migration`](cli.md#
 - **Webhook subscriptions** (`webhook_subscriptions`, the table `webhooks.subscriptions`): a name, the events (`orders.created orders.large`, or `orders.*`), the URL, a filter, extra headers, full or thin payload, and whether it is enabled. The server sets the tenant and the owner, the person who made it, and makes the secret, which only a [reveal](api.md#sensitive-fields-and-audit) shows. Saving checks the events and the filter against the resources, and refuses a URL whose host is a private, loopback or link-local address.
 - **Webhook deliveries** (`webhook_deliveries`, a view over the delivery jobs): the deliveries that wait for their next try or failed for good, with their last error. A delivery leaves the list once it succeeds.
 
+The migration gives the subscriptions table an index for each sort, filter and search of its list, and creates the `pg_trgm` extension the search's indexes need (`create extension if not exists pg_trgm`, a trusted extension since Postgres 13, so any role that may create in the database can). A database that has an earlier version's schema gets the indexes from the next `protobase migration`; the server does not start until it is applied.
+
 Both are scoped to the tenant like any resource with `.tenant()`, and their access decides who may do what: `webhook_subscriptions.create`, `webhook_deliveries.update` and so on, as for the app's own resources. A role's wildcard over resources, such as `*.read`, grants none of them: their URLs and secrets let whoever reads them call the receivers, so with roles only admins (`*`) and roles that [name them](access.md#resources-that-need-named-grants) manage webhook subscriptions.
 
 A subscription made here **delivers as its owner**, with the role they act with now in its tenant (the [active role](auth.md#active-role) they last chose, else their first): only records and fields it may read. Letting people make subscriptions therefore grants them nothing they could not read already. The roles are read from the app's sign-in; a project that signs people in otherwise exports its own, `async ({ id, tenant }) => [...]`, as the default of `webhooks/owner-roles.ts`.