@protobase/cli 0.66.7 → 0.66.9

package/dist/cli/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.66.7";
+var version = "0.66.9";
 //#endregion
 export { version };

package/dist/dev/api-forward.js

@@ -9,7 +9,8 @@ import { request } from "node:http";
 * discovery documents MCP clients read (`oauthWellKnownPaths`), below which a resource's own one is, and the push worker
 * (`withDevServiceWorker`). Vite serves the rest.
 */
-const isApiRequest = (url) => /^(\/api(\/|\?|$)|\/\.well-known\/webauthn(\?|$)|\/\.well-known\/oauth-(authorization-server|protected-resource)(\/|\?|$)|\/protobase\.sw\.js(\?|$))/.test(url);
+const apiRequestPattern = /^(\/api(\/|\?|$)|\/\.well-known\/webauthn(\?|$)|\/\.well-known\/oauth-(authorization-server|protected-resource)(\/|\?|$)|\/protobase\.sw\.js(\?|$))/;
+const isApiRequest = (url) => apiRequestPattern.test(url);
 const hopByHop = /* @__PURE__ */ new Set([
 	"connection",
 	"keep-alive",
@@ -67,4 +68,4 @@ const apiForward = (port) => ({
 	}
 });
 //#endregion
-export { apiForward, isApiRequest };
+export { apiForward, apiRequestPattern, isApiRequest };

package/dist/dev/app-files.js

@@ -0,0 +1,11 @@
+import { adminAppMain } from "../project/admin-app.js";
+import { existsSync } from "node:fs";
+import path from "node:path";
+//#region src/dev/app-files.ts
+/** Fails, naming them, when the admin app in `appDir` lacks the files `protobase dev` serves it from. */
+const requireAppFiles = (appDir) => {
+	const missing = ["index.html", adminAppMain].filter((file) => !existsSync(path.join(appDir, file)));
+	if (missing.length > 0) throw new Error(`The admin app is missing ${missing.join(", ")} in ${appDir}; \`protobase dev\` serves the app from there`);
+};
+//#endregion
+export { requireAppFiles };

package/dist/dev/check-remote-api.js

@@ -0,0 +1,18 @@
+//#region src/dev/check-remote-api.ts
+/**
+* Fails, before the dev server starts, when the instance at `origin` cannot be reached or does not answer `/api/meta`
+* as a Protobase API does, with the X-Meta-Version header.
+*/
+const checkRemoteApi = async (origin) => {
+	const meta = `${origin}/api/meta`;
+	const answer = await fetch(meta, {
+		signal: AbortSignal.timeout(1e4),
+		redirect: "manual"
+	}).catch((error) => {
+		throw new Error(`Cannot reach the API at ${meta}: ${error.cause?.message ?? error.message}`);
+	});
+	await answer.body?.cancel();
+	if (!answer.headers.has("x-meta-version")) throw new Error(`${origin} answered ${meta} with ${answer.status} and no X-Meta-Version header; is it a Protobase app?`);
+};
+//#endregion
+export { checkRemoteApi };

package/dist/dev/entry.js

@@ -55,7 +55,7 @@ const ui = {
 	icons: projectIcons(projectDir)
 };
 const { admin, jobs } = projectAdmin(project, db, ui, reporter, upgradeWebSocket);
-await devJobs(db, jobs, admin.decryptField, project.mailer);
+if (process.env.PROTOBASE_DEV_JOBS !== "false") await devJobs(db, jobs, admin.decryptField, project.mailer);
 devRealtimePrune(admin);
 var entry_default = withDevServiceWorker(new Hono(), Boolean(project.notifications)).route("/", admin);
 /** Whether the auth store has a user yet, for the banner's sign-in line; undefined without one. */

package/dist/dev/remote-api.js

@@ -0,0 +1,58 @@
+import { isAllowedHost } from "./allowed-host.js";
+import { apiRequestPattern } from "./api-forward.js";
+//#region src/dev/remote-api.ts
+/**
+* The origin of the Protobase instance `protobase dev --api` hands the API to, from the URL given: http or https, and
+* no path, since an instance serves its API at /api of its origin.
+*/
+const remoteApiOrigin = (value) => {
+	const url = URL.parse(value);
+	if (!url || url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`--api expects an http or https URL, such as https://app.example.com, not "${value}"`);
+	if (url.pathname !== "/" || url.search) throw new Error(`--api expects the instance's origin, such as ${url.origin}, without a path`);
+	return url.origin;
+};
+const ofDevServer = (value, request) => {
+	const url = value === void 0 ? null : URL.parse(value);
+	return url?.host === request.headers.host ? url : void 0;
+};
+/**
+* Hands the requests the API process answers in `protobase dev` (`isApiRequest`), and the API's WebSockets, to the
+* instance at `origin` through Vite's proxy. The instance sees its own Host, and its own origin in the Origin and Referer
+* of a page of this dev server, so its sign-in and its checks of a request's origin take them; a request from any other
+* page keeps the origin it came with. Its cookies come back without their Domain, for localhost to keep, and a
+* redirect to its own address comes back as a path on this server. A socket whose Host fails Vite's host check is
+* refused, as Vite refuses such a request.
+*/
+const remoteApi = (origin) => {
+	let allowedHosts = [];
+	return {
+		name: "protobase-remote-api",
+		config: () => ({ server: { proxy: { [apiRequestPattern.source]: {
+			target: origin,
+			changeOrigin: true,
+			ws: true,
+			rewriteWsOrigin: true,
+			cookieDomainRewrite: { "*": "" },
+			bypass: (request, response) => {
+				if (!(response === void 0)) return void 0;
+				return isAllowedHost(request.headers.host, allowedHosts) ? void 0 : false;
+			},
+			configure: (proxy) => {
+				proxy.on("proxyReq", (upstream, request) => {
+					if (ofDevServer(request.headers.origin, request)) upstream.setHeader("origin", origin);
+					const referer = ofDevServer(request.headers.referer, request);
+					if (referer) upstream.setHeader("referer", `${origin}${referer.pathname}${referer.search}`);
+				});
+				proxy.on("proxyRes", (answer) => {
+					const location = answer.headers.location;
+					if (location?.startsWith(`${origin}/`)) answer.headers.location = location.slice(origin.length);
+				});
+			}
+		} } } }),
+		configResolved: (config) => {
+			allowedHosts = config.server.allowedHosts;
+		}
+	};
+};
+//#endregion
+export { remoteApi, remoteApiOrigin };

package/dist/dev/run-ui.js

@@ -0,0 +1,34 @@
+import { adminAppDir } from "../project/admin-app.js";
+import { alsoOnIpv6, checkPortFree } from "./loopback.js";
+import { remoteApi } from "./remote-api.js";
+import { requireAppFiles } from "./app-files.js";
+import { checkRemoteApi } from "./check-remote-api.js";
+//#region src/dev/run-ui.ts
+/**
+* `protobase dev --api`: the admin app with the project's UI, theme and icons, as `runDev` serves it, with its API
+* requests handed to a running instance instead of an API process of its own; no database and no project config are read.
+*/
+const runUiDev = async (options, out) => {
+	const appDir = options.appDir ?? adminAppDir;
+	requireAppFiles(appDir);
+	await checkRemoteApi(options.api);
+	if (options.port !== 0) await checkPortFree(options.port);
+	const { createAppServer } = await import("./app-server.js");
+	const server = await createAppServer({
+		...options,
+		appDir,
+		extensions: options.extensions ?? []
+	}, [remoteApi(options.api)]);
+	const closeAndThrow = async (error) => {
+		await server.close();
+		throw error;
+	};
+	await server.listen().catch(closeAndThrow);
+	const address = server.httpServer?.address();
+	const port = typeof address === "object" && address ? address.port : options.port;
+	if (server.httpServer) await alsoOnIpv6(server.httpServer, port).catch(closeAndThrow);
+	out(`protobase dev ready at http://localhost:${port}\n  project  ${options.projectDir} (UI only)\n  api      ${options.api}/api/v1, through http://localhost:${port}/api/v1\n  login    sign in as a user of ${options.api}\n`);
+	return server;
+};
+//#endregion
+export { runUiDev };

package/dist/dev/run.js

@@ -1,18 +1,14 @@
 import { loadNearestEnvFile } from "./env.js";
-import { adminAppDir, adminAppMain } from "../project/admin-app.js";
+import { adminAppDir } from "../project/admin-app.js";
 import { alsoOnIpv6, checkPortFree } from "./loopback.js";
+import { apiForward } from "./api-forward.js";
+import { requireAppFiles } from "./app-files.js";
 import { checkDatabase } from "./check-database.js";
 import { authDriftLines } from "./auth-drift-lines.js";
 import { loginLine } from "./login-line.js";
-import { apiForward } from "./api-forward.js";
 import { forkApiChild } from "./api-child.js";
-import { existsSync } from "node:fs";
 import path from "node:path";
 //#region src/dev/run.ts
-const requireAppFiles = (appDir) => {
-	const missing = ["index.html", adminAppMain].filter((file) => !existsSync(path.join(appDir, file)));
-	if (missing.length > 0) throw new Error(`The admin app is missing ${missing.join(", ")} in ${appDir}; \`protobase dev\` serves the app from there`);
-};
 const runDev = async (options, out) => {
 	loadNearestEnvFile(options.projectDir);
 	const url = process.env[options.envVar];
@@ -25,6 +21,7 @@ const runDev = async (options, out) => {
 	process.env.PROTOBASE_PROJECT = options.projectDir;
 	process.env.PROTOBASE_EXTENSIONS = JSON.stringify(extensions);
 	process.env.PROTOBASE_DATABASE_URL = url;
+	process.env.PROTOBASE_DEV_JOBS = String(options.jobs ?? true);
 	const onApiExit = (code) => {
 		process.stderr.write(`error: the API process of protobase dev ended with exit code ${code}\n`);
 		server.close().then(() => process.exit(code || 1));
@@ -63,7 +60,7 @@ const runDev = async (options, out) => {
 	const started = await apiChild.start(`http://localhost:${port}`).catch(closeAndThrow);
 	apiReady(started);
 	const { anyUsers, authDrift } = started;
-	out(`protobase dev ready at http://localhost:${port}\n  project  ${options.projectDir}\n  api      http://localhost:${port}/api/v1 (docs at /api/docs)\n` + loginLine(anyUsers, process.env.npm_config_user_agent) + authDriftLines(authDrift));
+	out(`protobase dev ready at http://localhost:${port}\n  project  ${options.projectDir}\n  api      http://localhost:${port}/api/v1 (docs at /api/docs)\n` + (options.jobs === false ? "  jobs     off: no jobs run and no events are delivered (--no-jobs)\n" : "") + loginLine(anyUsers, process.env.npm_config_user_agent) + authDriftLines(authDrift));
 	return server;
 };
 //#endregion

package/dist/main.js

@@ -60,22 +60,34 @@ program.command("doctor").description("Check a config folder against the databas
 	}, out);
 	if (errors > 0) process.exitCode = 1;
 });
-program.command("dev").description("Serve the admin app and API for the project in the current directory").option("--port <port>", "port for the app and API", "5173").option("--env <variable>", "environment variable holding the database URL", "DATABASE_URL").option("--allowed-hosts <hosts>", "extra Host headers to accept, comma separated; a leading dot matches subdomains (.trycloudflare.com)").option("--cache-dir <dir>", "Vite's dependency cache, so parallel dev servers do not share one").option("--extend <dir>", "merge the protobase.config.ts and protobase.ui.tsx in this folder before the project's, repeatable", collect, []).action(async (opts) => {
-	const [{ runDev }, { resolveExtensions }, { writeProjectTypes }] = await Promise.all([
-		import("./dev/run.js"),
-		import("./project/extensions.js"),
-		import("./project/project-types.js")
-	]);
-	await writeProjectTypes(process.cwd());
+const runUiDevAgainst = async (api, options) => {
+	const [{ runUiDev }, { remoteApiOrigin }] = await Promise.all([import("./dev/run-ui.js"), import("./dev/remote-api.js")]);
+	return runUiDev({
+		...options,
+		api: remoteApiOrigin(api)
+	}, out);
+};
+const runFullDev = async (envVar, jobs, options) => {
+	const { runDev } = await import("./dev/run.js");
 	const server = await runDev({
+		...options,
+		envVar,
+		jobs
+	}, out);
+	warn(placeholderSecretWarning(process.env));
+	return server;
+};
+program.command("dev").description("Serve the admin app and API for the project in the current directory").option("--port <port>", "port for the app and API", "5173").option("--env <variable>", "environment variable holding the database URL", "DATABASE_URL").option("--allowed-hosts <hosts>", "extra Host headers to accept, comma separated; a leading dot matches subdomains (.trycloudflare.com)").option("--cache-dir <dir>", "Vite's dependency cache, so parallel dev servers do not share one").option("--extend <dir>", "merge the protobase.config.ts and protobase.ui.tsx in this folder before the project's, repeatable", collect, []).option("--no-jobs", "run none of the app's jobs and deliver none of its events, such as against its hosted database").option("--api <url>", "serve the admin app alone, with the API of the running Protobase instance at this URL; no database or API process").action(async (opts) => {
+	const [{ resolveExtensions }, { writeProjectTypes }] = await Promise.all([import("./project/extensions.js"), import("./project/project-types.js")]);
+	await writeProjectTypes(process.cwd());
+	const shared = {
 		extensions: resolveExtensions(opts.extend),
 		port: Number(opts.port),
-		envVar: opts.env,
 		projectDir: process.cwd(),
 		cacheDir: opts.cacheDir && path.resolve(opts.cacheDir),
 		allowedHosts: parseHosts(opts.allowedHosts)
-	}, out);
-	warn(placeholderSecretWarning(process.env));
+	};
+	const server = opts.api ? await runUiDevAgainst(opts.api, shared) : await runFullDev(opts.env, opts.jobs, shared);
 	process.once("SIGINT", () => void server.close().then(() => process.exit(0)));
 	process.once("SIGTERM", () => void server.close().then(() => process.exit(0)));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/cli",
-  "version": "0.66.7",
+  "version": "0.66.9",
   "description": "The protobase command: scaffold, doctor, dev, build and serve a Protobase project.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,12 +43,12 @@
   "dependencies": {
     "@better-auth/core": "^1.7.12",
     "@hono/node-server": "^2.1.3",
-    "@protobase/config": "0.66.7",
-    "@protobase/layout": "0.66.7",
-    "@protobase/query": "0.66.7",
-    "@protobase/schema": "0.66.7",
-    "@protobase/server": "0.66.7",
-    "@protobase/ui": "0.66.7",
+    "@protobase/config": "0.66.9",
+    "@protobase/layout": "0.66.9",
+    "@protobase/query": "0.66.9",
+    "@protobase/schema": "0.66.9",
+    "@protobase/server": "0.66.9",
+    "@protobase/ui": "0.66.9",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/vite-plugin": "^11.10.0",

package/skills/protobase/references/features/ai.md

@@ -6,16 +6,19 @@ Fields and actions filled by a model, the assistant beside the admin, and MCP.
 
 - [AI fields](../reference/ai.md#ai-fields): A model fills a field from a prompt that uses the record's other fields, after each change.
 - [AI actions](../reference/ai.md#ai-actions): A button asks a model to write a field now, such as a suggested priority or a translation.
-- [Assistant](../reference/assistant.md): A chat beside the admin that answers questions about the app, reads its data and proposes changes for approval.
+- [Assistant](../reference/assistant.md) (beta): A chat beside the admin that answers questions about the app, reads its data and proposes changes for approval.
 - [Choice of model](../reference/assistant.md#which-backend): The assistant runs on OpenRouter or any OpenAI-compatible endpoint, also a local one.
-- [Assistant tools](../reference/assistant.md#the-apps-own-tools): Your own tools for the assistant, acting on records as the user.
-- [MCP server](../reference/mcp.md#the-tools): AI clients connect to the app over MCP as the signed-in person: they list the resources in a small first call, describe one resource's fields when they need them, and find and read records within that person's access, soft-deleted ones too when asked.
+- [Assistant tools](../reference/assistant.md#the-apps-own-tools) (beta): Your own tools for the assistant, acting on records as the user.
+- [Assistant widgets](../reference/assistant.md#widget-parts): Your own React components in the chat, showing a record as it is now and taking decisions on it, from last month's chat too.
+- [Assistant backend of your own](../reference/assistant.md#another-backend): The chat beside the admin talks to a backend elsewhere, with its own prompt and tools, built from the same pieces as the built-in one.
+- [MCP server](../reference/mcp.md#the-tools) (beta): AI clients connect to the app over MCP as the signed-in person: they list the resources in a small first call, describe one resource's fields when they need them, and find and read records within that person's access, soft-deleted ones too when asked.
 - [MCP read fields](../reference/mcp.md#reading-only-what-is-needed): AI clients read only the fields they name, a plain list returns the columns of the app's table, and the server tells clients how to keep reads small.
-- [MCP counts](../reference/mcp.md#the-tools): AI clients count the records a filter finds, in all or per value of a field such as a status, without reading the records.
-- [MCP app icon](../reference/mcp.md#the-apps-icon): AI clients show the app's own icon beside its name when someone adds its MCP endpoint.
-- [MCP writes](../reference/mcp.md#writes): When turned on, for every resource or only those you list, AI clients create, update and delete records after the person approves each write.
+- [MCP counts](../reference/mcp.md#the-tools) (beta): AI clients count the records a filter finds, in all or per value of a field such as a status, without reading the records.
+- [MCP app icon](../reference/mcp.md#the-apps-icon) (beta): AI clients show the app's own icon beside its name when someone adds its MCP endpoint.
+- [MCP SQL for admins](../reference/mcp.md#sql-for-admins): People with the `admin` or `ai` role run read-only SQL over MCP when you turn it on.
+- [MCP writes](../reference/mcp.md#writes) (beta): When turned on, for every resource or only those you list, AI clients create, update and delete records after the person approves each write.
 - [Small MCP write results](../reference/mcp.md#what-a-write-returns): A write over MCP returns the record's key, new ETag, the fields written and the read-only fields that changed, not the whole record; `fields` asks for more.
-- [MCP writes without approval](../reference/mcp.md#writes-without-approval): Roles you name, such as service accounts, write over MCP without being asked to approve each write; everyone else is still asked.
+- [MCP writes without approval](../reference/mcp.md#writes-without-approval) (beta): Roles you name, such as service accounts, write over MCP without being asked to approve each write; everyone else is still asked.
 - [MCP comments](../reference/mcp.md#comments): AI clients read a record's comments, and with MCP writes on add one after the person approves it.
 - [MCP batch writes](../reference/mcp.md#batch-writes): When MCP writes are on, AI clients make many creates, updates and deletes across resources in one transaction, after the person approves the batch.
 - [Connected apps](../reference/auth.md#oauth-for-mcp-clients): People allow an AI client to sign in, and disconnect it later.

package/skills/protobase/references/features/build-and-run.md

@@ -6,6 +6,8 @@ Develop, build and run an app, on servers, in containers and on phones.
 
 - [Node and Bun](../reference/cli.md#how-it-runs): The `protobase` command runs on Node 22.12 or later or on Bun, and a bundle runs on both unless it is built for Bun only.
 - [Dev server](../reference/cli.md#dev): The admin app and the API on one port, with changes shown without a restart.
+- [Dev server without jobs](../reference/cli.md#dev): `protobase dev --no-jobs` runs no jobs and delivers no events, webhooks or pushes, to develop against a hosted app's database without doing its work twice.
+- [UI-only dev server](../reference/cli.md#ui-only) (beta): `protobase dev --api <url>` serves the app's UI from the project with the API of an app already running, such as its staging deploy, with no database.
 - [Editor types](../reference/cli.md#types): `protobase types` gives the editor and `tsc` the types of the CLI that builds the app, with nothing installed.
 - [Project scripts](../reference/cli.md#run): `protobase run` runs a seed or a migration script on the CLI's packages.
 - [Migrate command](../reference/cli.md#migrate): `protobase migrate` applies the project's SQL migrations in one transaction, with nothing installed.

package/skills/protobase/references/features/compatibility.md

@@ -6,10 +6,10 @@ Apps written for other systems that keep working on Protobase, and moving their
 
 ## Supabase
 
-- [Supabase import](../reference/cli.md#import-supabase): Moves a Supabase project into Protobase, with schema, data, users, functions, storage and scheduled jobs.
-- [Create a project on a Supabase database](../getting-started.md#on-an-existing-database) (beta): your Supabase users sign in to the new project with their own passwords, and Supabase's own auth schema stays as Supabase set it up.
-- [Supabase client API](../reference/supabase-rest.md): supabase-js `from()` and `rpc()` calls keep working, under the tables' RLS policies.
-- [Supabase Auth](../reference/auth.md#supabase-js-and-supabasessr): `supabase.auth` and `@supabase/ssr` calls keep working.
-- [Supabase Storage](../reference/supabase-storage.md): supabase-js storage calls keep working, over the app's file storage.
-- [Supabase Realtime](../reference/supabase-realtime.md): Database changes, broadcast and presence through supabase-js channels, private ones authorized by the policies on `realtime.messages`, broadcasts sent from a server without joining a channel, and broadcasts from the database with `realtime.send()` and `realtime.broadcast_changes()`, across [several processes](../reference/supabase-realtime.md#several-processes) serving one app.
+- [Supabase import](../reference/cli.md#import-supabase) (beta): Moves a Supabase project into Protobase, with schema, data, users, functions, storage and scheduled jobs, and a coding agent's skill finishes what its report leaves.
+- [Create a project on a Supabase database](../getting-started.md#on-a-supabase-database) (beta): your Supabase users sign in to the new project with their own passwords, and Supabase's own auth schema stays as Supabase set it up.
+- [Supabase client API](../reference/supabase-rest.md) (beta): supabase-js `from()` and `rpc()` calls keep working, under the tables' RLS policies.
+- [Supabase Auth](../reference/auth.md#supabase-js-and-supabasessr) (beta): `supabase.auth` and `@supabase/ssr` calls keep working.
+- [Supabase Storage](../reference/supabase-storage.md) (beta): supabase-js storage calls keep working, over the app's file storage.
+- [Supabase Realtime](../reference/supabase-realtime.md) (beta): Database changes, broadcast and presence through supabase-js channels, private ones authorized by the policies on `realtime.messages`, broadcasts sent from a server without joining a channel, and broadcasts from the database with `realtime.send()` and `realtime.broadcast_changes()`, across [several processes](../reference/supabase-realtime.md#several-processes) serving one app.
 - [Edge Functions](../guides/api-functions.md#functions-moved-from-supabase): Functions moved from Supabase answer at their old addresses.

package/skills/protobase/references/features/data-model.md

@@ -18,7 +18,7 @@ Describe the tables of an existing Postgres database as resources, with their fi
 - [Record validation](../reference/data-config.md#resource): A rule over the whole record runs on every create and update and reports each problem on the field it concerns.
 - [Rollups and formulas](../reference/data-config.md#rollups-and-formulas) (beta): Fields that hold counts, sums, averages, minimums or maximums of related records, or values calculated from the record's own numbers, kept current by the database.
 - [Sensitive fields](../reference/data-config.md#sensitive-fields): Values such as bank account numbers are left out of every response and shown masked. A permitted user reveals one value at a time, and each reveal is audited.
-- [Recent strong sign-in](../reference/data-config.md#recent-strong-sign-in): A sensitive field can ask for a passkey or a second step in the last minutes before it is revealed. The record page asks the person to confirm it's them, then shows it.
+- [Recent strong sign-in](../reference/data-config.md#recent-strong-sign-in): A sensitive field can ask for a passkey or a second step in the last minutes before it is revealed, or an emailed code for an account with neither. The record page asks the person to confirm it's them, then shows it.
 - [Computed reveals](../reference/data-config.md#computed-reveals) (beta): A secret kept elsewhere, or built from several values, is revealed like a sensitive field, with the same access, audit and recent sign-in check, but made when it is asked for.
 - [Encrypted fields](../reference/data-config.md#encrypted-fields): A sensitive text field is encrypted with the app's own key before it is stored, so dumps, backups and SQL readers see only ciphertext. A command encrypts the values a column already holds.
 - [Encrypted fields in jobs and functions](../reference/data-config.md#reading-in-jobs-and-functions) (beta): A job or an API function reads an encrypted value the app must use itself, such as a share's password, and each read is audited like a reveal.

package/skills/protobase/references/features/email-and-public-forms.md

@@ -7,6 +7,8 @@ Mail the app sends, the PDF documents it makes, and forms for people without an
 - [Email](../reference/email.md#configuration): The app sends mail through one SMTP server or a mailer you supply.
 - [Built-in emails](../reference/email.md#protobases-own-mail): Sign-in codes, password resets, invitations and mentions are sent in the app's name.
 - [Email templates](../reference/email.md#templates): Your own emails are React components with typed data, sent from jobs, hooks or functions.
+- [Protobase's mail look](../reference/email.md#the-look-of-protobases-own-mail): Your emails use the layout, button, code and note that Protobase's own mail is built from.
+- [Unsubscribe headers](../reference/email.md#templates): Your emails carry header fields of their own, such as a one-click unsubscribe link for bulk mail.
 - [Attachments](../reference/email.md#attachments): A message carries files, such as an invoice's PDF, through the app's mail or someone's own mailbox.
 - [PDF documents](../reference/pdf.md#documents): PDF files such as invoices and quotes are React components with typed data, rendered from jobs, hooks or functions and attached to mail as they are.
 - [Mail from your own mailbox](../reference/email.md#from-someones-own-mailbox) (beta): People link their Gmail on the account page, and the app's functions send mail from it, with a clear error when the link is missing or expired.

package/skills/protobase/references/features/events-webhooks-and-jobs.md

@@ -10,10 +10,12 @@ React to changes, deliver them to other systems, and run work in the background.
 - [Signed webhooks](../reference/webhooks.md#what-a-receiver-gets): Deliveries are signed under the Standard Webhooks spec.
 - [Delivery retries](../reference/webhooks.md#delivery-and-retries): Failed deliveries are retried for about three days.
 - [Webhooks in the admin app](../reference/webhooks.md#subscriptions-in-the-admin-app): Users create subscriptions, send test events and resend failures in the app.
+- [Webhook delivery log](../reference/webhooks.md#subscriptions-in-the-admin-app): Every try of the admin app's subscriptions, successes too, is kept for 30 days with its status and timing, when the app turns it on.
 - [Background jobs](../reference/jobs.md#enqueueing): Jobs are kept in the app's own Postgres and can be queued in the same transaction as a write, also from SQL.
 - [Typed jobs](../reference/jobs.md#typed-names-and-payloads): Code that queues a job, and the job itself, are checked against the names and arguments the config declares as they compile.
 - [Retries](../reference/jobs.md#failures): Failed jobs are retried with growing waits, and duplicates can be prevented with a key.
 - [Ordered groups](../reference/jobs.md#ordered-groups): Jobs in one group run one at a time, in order.
 - [Recurring jobs](../reference/jobs.md#recurring-jobs): Jobs run on a cron schedule in a chosen time zone.
 - [Failed jobs page](../reference/jobs.md#failed-jobs-page): Admins see jobs that failed for good and retry or delete them.
+- [Worker process](../reference/jobs.md#where-jobs-run): Jobs and event deliveries run beside the API, or in a worker process of their own from the same bundle.
 - [Jobs on hosts that sleep](../reference/jobs.md#hosts-that-sleep): A host that stops idle apps can wake them when a job is due.

package/skills/protobase/references/features/files-and-images.md

@@ -5,6 +5,7 @@
 Uploaded files and images, where they are kept and how they are served.
 
 - [File fields](../reference/files.md#what-the-column-holds): A text column holds an uploaded file, with limits on type and size.
+- [File uploads in forms](../reference/files.md#in-forms): Forms upload a dropped or chosen file at once with a progress bar, and replace or remove it; tables show its name and a thumbnail.
 - [File storage](../reference/files.md#providers): Files are kept on disk, or in a bucket of your own.
 - [S3-compatible buckets](../reference/files.md#s3-compatible-buckets) (beta): Files are kept in any bucket that speaks the S3 API, when the app runs on Bun.
 - [Files from a seed](../reference/files.md#writing-files-from-a-seed): A seed or another script writes files into the app's providers, read from its config and environment as the server reads them.

package/skills/protobase/references/features/look-and-language.md

@@ -8,6 +8,7 @@ The app's colours, name, icon, language and installation.
 - [Dark mode](../reference/theme.md#light-dark-or-the-system): Each user picks light, dark or the system setting.
 - [App name, icon and colours](../reference/app-identity.md): The app's own name, icon and colours in the sidebar, browser tabs, `/favicon.ico`, home-screen icon and mail.
 - [Logo and favicon](../reference/theme.md#logo-and-favicon): Your own favicon or logo replaces Protobase's.
+- [Named icons](../reference/layouts.md#named-actions): Actions, key facts and card meta show an icon picked by name from a set, such as `play`, `bed` or `cpu`.
 - [English and Dutch](../reference/languages.md): The built-in screens come in English and Dutch, with numbers and dates written to match.
 - [Installable app](../reference/installable-app.md): The admin installs as an app on phones and computers, and says when the server cannot be reached.
 - Reduced motion: When the system asks for less motion, animations and pulsing dots stop.

package/skills/protobase/references/features/navigation.md

@@ -4,14 +4,15 @@
 
 The sidebar, the user menu, the bottom bar on phones and the global search.
 
-- [Sidebar](../reference/sidebar.md): Resources and pages in groups, in the order you set.
+- [Sidebar](../reference/sidebar.md): Resources and pages in groups, in the order you set, and a drawer on phones.
 - [Sidebar icons](../reference/sidebar.md#sidebar-icons): Each resource shows the icon its view names in the sidebar, bottom bar and profile menu.
-- [Recent records](../reference/sidebar.md#recent-records): A sidebar entry lists a few records under it, with status dots or as titles alone, and marked per reader, such as unread ones in bold with a count.
+- [Recent records](../reference/sidebar.md#recent-records) (beta): A sidebar entry lists a few records under it, with status dots or as titles alone, and marked per reader, such as unread ones in bold with a count.
 - [Create link](../reference/sidebar.md#create-link): A sidebar entry links to its create form, such as "New message" under Direct messages, for whoever may create.
 - [The current organization](../reference/sidebar.md#the-current-organization): A sidebar entry opens its list on the organization you work in, which you can clear to see every organization you are a member of.
 - [User menu](../reference/user-menu.md): Account pages, help links, security settings, setting a status, the theme switch and Sign out.
 - [Bottom bar](../reference/bottom-bar.md): On phones, tabs along the bottom for each role's main screens.
 - [Global search](../reference/client.md#global-search): A search box, also on Cmd+K or Ctrl+K, finds records in every resource and jumps to pages and New forms.
-- Breadcrumbs: The top bar shows the group, list and record you are on, each a link back.
-- Update notice: When the server runs a newer Protobase version, open pages offer a reload so the user can save their work first.
+- [Breadcrumbs](../reference/ui-config.md#breadcrumbs): The top bar shows the group, list and record you are on, each a link back, and on a phone a back button to the one before.
+- [Tab titles](../reference/ui-config.md#names-and-columns): Browser tabs name the record, list or page they show, then the app.
+- [Update notice](../reference/versioning.md#a-new-version-under-an-open-page): When the server runs a newer Protobase version, open pages offer a reload so the user can save their work first.
 - Config refresh: When the config or the user's roles change, open pages load the new menus, columns and permissions without a reload.

package/skills/protobase/references/features/sign-in-and-accounts.md

@@ -5,11 +5,13 @@
 Sign-in methods, users, roles, organizations and tokens.
 
 - [Built-in sign-in](../reference/auth.md): Password sign-in, sessions and short-lived tokens, with no separate identity service.
+- [Sign-in page](../reference/client.md#the-admin-app): The app signs people in at its own address, where the browser's Back returns to the step before, and signing in comes back to the page they were on.
 - [First admin](../reference/auth.md#first-run): No account can be made over the web while the app has no users. You create the first admin from the terminal, and the last active admin cannot be deleted, demoted or blocked.
 - [Users from a script](../reference/auth.md#first-run): A seed or another script of the project creates and lists users, and mints their tokens, on the app's own sign-in.
 - [Versioned sign-in tables](../reference/auth.md#migrations): The sign-in tables come from numbered migrations that ship with Protobase, written as the project's own and recorded in the database, so a deploy checks them without comparing tables. Every feature has its tables from the start, so turning one on or off needs no migration.
 - [Existing users table](../reference/auth.md#an-existing-users-table): Sign-in can use the users table another system keeps in the same database.
 - [Users page](../reference/auth.md#users-page): Admins find people, set roles, block them, add accounts and invite people by email.
+- [Account page](../reference/auth.md#account-page): Everyone signed in has an account page for their profile, sign-in and security, devices and connected apps, and you add, hide or reorder its tabs.
 - [Password reset](../reference/auth.md#password-reset): People reset a forgotten password through an emailed link.
 - [Password changes](../reference/auth.md#name-password-and-devices): Changing the password signs out every other device and MCP client, and emails the account that its password changed. Guesses at the current password are limited for each account.
 - [Leaked passwords](../reference/auth.md#leaked-passwords): New passwords that appear in a known data breach are refused, when the app turns the check on.
@@ -19,8 +21,12 @@ Sign-in methods, users, roles, organizations and tokens.
 - [Open sign-up](../reference/auth.md#open-sign-up): Anyone can create an account after confirming an emailed code.
 - [Passkeys](../reference/auth.md#passkeys): People sign in with their device's face or fingerprint unlock, or with a security key.
 - [Two-factor authentication](../reference/auth.md#two-factor-authentication): A second step with an authenticator app, backup codes or emailed codes.
+- [Emailed confirmation code](../reference/auth.md#emailed-confirmation-code): Someone without a passkey or a second step confirms it's them with a code emailed on request, where they are, such as before a secret is shown.
+- [Confirming an account change](../reference/auth.md#confirming-an-account-change): Adding a passkey, unlinking a provider or deleting the account from an older session asks to confirm it's them in place, never to sign out and sign in again.
 - [Sign-in policy](../reference/auth.md#sign-in-policy): Admins choose which sign-in methods are on, off or required, and the server refuses a policy that would lock people out.
 - [GitHub and social sign-in](../reference/auth.md#sign-in-with-github): People sign in with GitHub or another social provider.
+- [Sign-in links](../reference/auth.md#sign-in-links-and-connected-accounts): A link signs someone in with a sign-in provider at once, without the sign-in page.
+- [Connected accounts](../reference/auth.md#sign-in-links-and-connected-accounts): People link GitHub or another sign-in provider to their account from the account page.
 - [SAML sign-in](../reference/auth.md#sign-in-with-saml): People sign in through any SAML provider.
 - [OpenID Connect provider](../reference/auth.md#platform-sign-in-provider): A host adds an OpenID Connect provider for people who already have an account.
 - [Staff sign-in](../reference/auth.md#staff-sign-in): The team that runs an app signs in as a person to help them, with a reason and a log entry.

package/skills/protobase/references/features/your-own-code.md

@@ -11,11 +11,13 @@ React components, field types, pages and handlers of your own, loaded as plugins
 - [Custom field types](../reference/plugins.md#field-types): Register how a kind of value is shown and edited, and pick it per field in a view.
 - [Custom create pages](../reference/custom-components.md#create-pages): Replace a resource's create form with your own page, such as a booking flow.
 - [Form parts](../reference/custom-components.md#form-parts): Build your own forms from the app's fields, pickers, switches, buttons and dialogs.
+- [Markdown](../reference/custom-components.md#components): Show markdown in your own components, such as a chat message, as the app's markdown fields draw it.
+- [Polling lists](../reference/custom-components.md#record-sections): A list your own component reads can refetch on an interval you set, to stay current.
 - [Image carousel](../reference/custom-components.md#image-carousel): Step through screenshots or a record's files in your own components by swiping or with arrows, as cards step through photos.
 - [Assistant parts](../reference/assistant.md#in-the-ui): The assistant's panel, chat messages, composer and action cards for your own components, with a frameless action card for a page that is already framed.
 - [Chat parts](../reference/custom-components.md#chat-parts): A chat between people from the app's parts: messages with their author, avatar, time and a status line, day and new-message lines, a thread that loads earlier messages, keeps the reader's place, opens on the new-message line, says when the reader has read to the end and jumps to the end when they send, and a composer of several lines with @mentions and slots for an attach button and a tray of picked files, which sends files without text and takes pasted and dropped files.
-- [Members' names](../reference/custom-components.md#members-names): The names and photos of the organization's members by user id, for message authors and @mentions in your own components; every member reads them, without email addresses.
-- [Signed-in user](../reference/custom-components.md#members-names): The signed-in person's user id and name in your own components, such as for a filter on their own messages.
+- [Members' names](../reference/custom-components.md#members-names) (beta): The names and photos of the organization's members by user id, for message authors and @mentions in your own components; every member reads them, without email addresses.
+- [Signed-in user](../reference/custom-components.md#signed-in-user): The signed-in person's user id and name in your own components, such as for a filter on their own messages.
 - [Action handlers](../reference/custom-components.md#action-handlers): Your own code for a named action, with the record, the API client and the action's inputs.
 - [Shell slots](../reference/custom-components.md#shell-slots): Your own components in the top bar, in a panel beside every page, or as the sidebar logo.
 - [Plugins](../reference/plugins.md#how-a-plugin-stays-working): Your React code is a plugin that the app loads at start and that keeps working across Protobase releases without changes.

package/skills/protobase/references/getting-started.md

@@ -61,8 +61,6 @@ Then it runs that `scaffold` in the project and prints the next steps. Without a
 
 It never writes to the database. The first of the next steps does: `bun run db:migrate` adds the `auth` schema that sign-in keeps its users in, and the `migrations` schema, where the script records the migrations it applied in `migrations.applied`. A `public.schema_migrations` another migration tool keeps is left as it is.
 
-On a Supabase database, which it knows by its `auth` and `storage` schemas and its `supabase_admin` role, as [`import supabase`](reference/cli.md#import-supabase) does, the `auth` schema is Supabase Auth's, and the project changes nothing in it. It leaves out `auth`, `storage` and the platform's other schemas, such as `realtime` and `supabase_migrations`, as Supabase's own tables. The project reads Supabase's users through a view over `auth.users` and keeps only its own sign-in data, in a schema of its own, `app_auth`: it points `protobase.config.ts` at the view, with [`users.keyTable`](reference/auth.md#a-view-over-another-systems-users), and writes migrations in place of those of Protobase's own user table: Better Auth's tables in `app_auth`, pointing at `auth.users`, then the view, its side table of the columns only Better Auth has, and each user's account with their Supabase password and social providers. `bun run db:migrate` applies them as the `postgres` role a Supabase connection string signs in as, and Supabase's users sign in with their own passwords, under their own ids. You can create, disable and delete users from either side, and a name changed in Supabase shows at once. <gap>A user who signs up through Supabase Auth later is a user of the project at once but cannot sign in with a password because sharing passwords with Supabase Auth is not implemented.</gap> Supabase's phone-only and anonymous users are not users of the project, since sign-in needs an email. A ban set in the project stays the project's own, while a ban set in Supabase holds in the project too.
-
 ```sh
 cd shop
 bun run db:migrate                  # the first write to the database
@@ -70,6 +68,14 @@ bun run protobase users create you@example.com --generate-password
 bun run dev                         # http://localhost:5173
 ```
 
+#### On a Supabase database
+
+:::caution[Beta]
+A user who signs up through Supabase Auth later cannot sign in to the project with a password yet, as below.
+:::
+
+On a Supabase database, which it knows by its `auth` and `storage` schemas and its `supabase_admin` role, as [`import supabase`](reference/cli.md#import-supabase) does, the `auth` schema is Supabase Auth's, and the project changes nothing in it. It leaves out `auth`, `storage` and the platform's other schemas, such as `realtime` and `supabase_migrations`, as Supabase's own tables. The project reads Supabase's users through a view over `auth.users` and keeps only its own sign-in data, in a schema of its own, `app_auth`: it points `protobase.config.ts` at the view, with [`users.keyTable`](reference/auth.md#a-view-over-another-systems-users), and writes migrations in place of those of Protobase's own user table: Better Auth's tables in `app_auth`, pointing at `auth.users`, then the view, its side table of the columns only Better Auth has, and each user's account with their Supabase password and social providers. `bun run db:migrate` applies them as the `postgres` role a Supabase connection string signs in as, and Supabase's users sign in with their own passwords, under their own ids. You can create, disable and delete users from either side, and a name changed in Supabase shows at once. <gap>A user who signs up through Supabase Auth later is a user of the project at once but cannot sign in with a password because sharing passwords with Supabase Auth is not implemented.</gap> Supabase's phone-only and anonymous users are not users of the project, since sign-in needs an email. A ban set in the project stays the project's own, while a ban set in Supabase holds in the project too.
+
 ## Admin over an existing database
 
 For a Postgres database you already have, `npm create protobase <database-url>` makes the project, as [above](#on-an-existing-database). [Admin over an existing database](guides/existing-database.md) does it by hand, in a folder of your own: install the packages, scaffold the config from the tables, check it with `doctor`, add sign-in and its tables, create the first admin and run `protobase dev`.

package/skills/protobase/references/guides/api-functions.md

@@ -419,9 +419,9 @@ export default defineFunction({ longQueries: true }, async (request, { db }) =>
 
 [`protobase import supabase`](../reference/cli.md#import-supabase) converts `supabase/functions` into `functions/`. A converted function keeps Supabase's shape, `defineFunction({ supabase: true }, { fetch })`, and keeps working with `@supabase/server` and supabase-js:
 
-- **At `/api/sb/functions/v1/<name>` too,** so `supabase.functions.invoke` callers do not change. Only a function with `supabase: true` answers there, and any other function answers `404`. There a protected function lets in a request with the app's publishable or secret key in the `apikey` header, and a user token of [`/api/sb/auth/v1`](../reference/auth.md#supabase-js-and-supabasessr) as the bearer, if any, as Supabase's `verify_jwt` does. A public function lets in anyone. The keys are those of [supabase-js's Realtime](../reference/supabase-realtime.md): without them, only public functions answer there. As on Supabase, the request's path starts at the function's name (`/<name>/more/parts`), and a CORS preflight reaches the function, which answers it.
+- **At `/api/sb/functions/v1/<name>` too,** so `supabase.functions.invoke` callers do not change. Only a function with `supabase: true` answers there, and any other function answers `404`. There a protected function lets in a request with the app's publishable or secret key in the `apikey` header, and a user token of [`/api/sb/auth/v1`](../reference/auth.md#supabase-js-and-supabasessr) as the bearer, if any, as Supabase's `verify_jwt` does. A public function lets in anyone. The keys are the app's [API keys](../reference/supabase-rest.md#keys-and-roles): without them, only public functions answer there. As on Supabase, the request's path starts at the function's name (`/<name>/more/parts`), and a CORS preflight reaches the function, which answers it.
 - **Its context there** is `{ name, db, caller() }`, where `caller()` resolves to who the key and token make the request: `{ role: 'anon' }` for the publishable key alone, `{ role: 'app' }` for the secret key, or `{ role: 'authenticated', claims }`. There is no `session` and no `records`. The publishable key alone lets callers in, so give `supabase: true` only to functions written for Supabase's `verify_jwt`. Together with `roles` or `capability`, which the address cannot check, it stops startup.
-- **Supabase's variables:** `protobase dev` sets `SUPABASE_URL` to the app's address with `/api/sb`, where supabase-js finds it, `SUPABASE_ANON_KEY`, `SUPABASE_PUBLISHABLE_KEY` and `SUPABASE_PUBLISHABLE_KEYS` to the publishable key, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_SECRET_KEY` and `SUPABASE_SECRET_KEYS` to the secret key, `SUPABASE_JWKS_URL` to the key set of `/api/sb/auth/v1`, and `SUPABASE_DB_URL` to the database. A variable set in `.env` wins. Under `protobase serve`, set them where the host keeps its settings.
+- **Supabase's variables:** `protobase dev` sets `SUPABASE_URL` to the app's address with `/api/sb`, where supabase-js finds it, `SUPABASE_ANON_KEY` and `SUPABASE_PUBLISHABLE_KEY` to the publishable key and `SUPABASE_PUBLISHABLE_KEYS` to `{"default":<publishable key>}`, `SUPABASE_SERVICE_ROLE_KEY` and `SUPABASE_SECRET_KEY` to the secret key and `SUPABASE_SECRET_KEYS` to `{"default":<secret key>}`, each only when the app has that key, `SUPABASE_JWKS_URL` to the key set of `/api/sb/auth/v1` when the app has sign-in, and `SUPABASE_DB_URL` to the database. A variable set in `.env` wins. Under `protobase serve`, set them where the host keeps its settings.
 - **`waitUntil(promise)`** from `@protobase/server` takes the place of `EdgeRuntime.waitUntil`. The response goes out at once, and the process waits for the work when it shuts down gracefully. Work still running when the host kills the process is lost. On Protobase Cloud's Starter plan an app stops 30 seconds after its last request, with 10 seconds to finish, so move longer work into a [job](../reference/jobs.md).
 
 ## What functions are not

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

@@ -115,7 +115,7 @@ Get responses carry `permissions: { update, delete, fields }`, where `fields` ma
 
 A field declared [`.sensitive()`](data-config.md#sensitive-fields) is in `/meta` (marked `sensitive: true`), in record `permissions.fields` and in create and update bodies, but in no list, get, `:search`, `:seek`, write or batch response, and `filter`, `order_by`, `fields` and the aggregates refuse it like an unknown field. `POST /{resource}/{key}:reveal` with `{ "field": "<name>" }` returns one record's value. It needs read access to the record and the field: another tenant's record, a row outside the caller's row filter or a key that does not exist is a `404`, a field the caller cannot read or that is not sensitive a `400`. An [encrypted field](data-config.md#encrypted-fields)'s reveal decrypts its value, and an empty one reveals `null`; a value that does not decrypt is a `500` reported to the operator, without an audit event. An update that changes the key of a record with encrypted fields is a `400` `key-change-unsupported`.
 
-A field with [`.strongSignIn()`](data-config.md#recent-strong-sign-in) is a `403` `strong-sign-in-required`, whose problem carries `minutes`, until the caller's sign-in proved a passkey or a second step that recently. The same request reveals a resource's [computed reveals](data-config.md#computed-reveals) by name, whose value the server makes when asked.
+A field with [`.strongSignIn()`](data-config.md#recent-strong-sign-in) is a `403` `strong-sign-in-required`, whose problem carries `minutes`, until the caller's sign-in proved a passkey or a second step that recently, or, for an account with neither, an [emailed confirmation code](auth.md#emailed-confirmation-code). The same request reveals a resource's [computed reveals](data-config.md#computed-reveals) by name, whose value the server makes when asked.
 
 Before answering, the server publishes an audit event to the app's audit queue, and when publishing fails the reveal fails (`500`), so no value leaves without its event. The event never holds the value:
 

package/skills/protobase/references/reference/app-identity.md

@@ -30,7 +30,7 @@ export default defineConfig({
 
 ## The icons
 
-`protobase.favicon.svg` is the one source of the app's icon: the tab shows it, the [web manifest](installable-app.md#the-manifest) names it, and with it the sidebar's logo draws it beside the app's name in place of Protobase's mark and wordmark. A project's own [`shell.logo`](custom-components.md#shell-slots) still wins.
+`protobase.favicon.svg` is the one source of the app's icon: the tab shows it, the [web manifest](installable-app.md#the-manifest) names it, and with it the sidebar's logo draws it in place of Protobase's mark, beside the app's name. A project's own [`shell.logo`](custom-components.md#shell-slots) still wins.
 
 Some platforms take no SVG, so a project may put PNGs of the same icon beside it, each square at its size: