@protobase/cli 0.66.16 → 0.67.1

package/dist/cli/package.js

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

package/dist/config/build-project.js

@@ -1,4 +1,5 @@
 import { projectFiles, projectFunctions, projectJobs, projectNotifications, projectOptions, projectResources, projectWebhooks } from "./project-parts.js";
+import { userTablesOn } from "./user-tables-config.js";
 import { buildAppAuth, buildAuthenticator, checkCallsOptions, checkStatusOptions } from "@protobase/server/internal";
 //#region src/config/build-project.ts
 /**
@@ -76,6 +77,7 @@ const buildProject = async (config, database) => {
 		...config.mobile && { mobile: config.mobile },
 		...config.secret && { secret: config.secret },
 		...identity && { app: identity },
+		...userTablesOn(config) && { userTables: true },
 		options
 	};
 };

package/dist/config/source-config.js

@@ -1,4 +1,5 @@
 import { mergeConfig } from "./merge-config.js";
+import { checkUserTables } from "./user-tables-config.js";
 import { importProjectFiles } from "../project/import-project-file.js";
 import { withDefaults } from "./config-defaults.js";
 import { sourceFiles } from "./project-files.js";
@@ -27,11 +28,11 @@ const loadSourceConfig = async (dir, { command, extensions = [], importModules =
 	}
 	const file = configFileOf(dir);
 	const own = file ? await readConfigFile(file, configEnv, importModules) : {};
-	return withDefaults(mergeConfig(...extended, {
+	return checkUserTables(withDefaults(mergeConfig(...extended, {
 		config: own,
 		files: sourceFiles(dir, importModules),
 		label: file ? path.basename(file) : "config/index.ts"
-	}), command, process.env);
+	}), command, process.env));
 };
 //#endregion
 export { loadSourceConfig };

package/dist/config/user-tables-config.js

@@ -0,0 +1,15 @@
+//#region src/config/user-tables-config.ts
+/** Whether the app keeps tables its users add: the one reading of `userTables`, after `checkUserTables`. */
+const userTablesOn = (config) => config.userTables === true;
+/**
+* Refuses a `userTables` that is no boolean, and user tables together with organizations, whose definitions and records
+* are not kept per organization. Organizations are on for any truthy `auth.organizations`, as sign-in reads it.
+*/
+const checkUserTables = (config) => {
+	const value = config.userTables;
+	if (value !== void 0 && typeof value !== "boolean") throw new Error(`userTables is ${JSON.stringify(value)}; it takes true or false`);
+	if (userTablesOn(config) && config.auth && config.auth.organizations) throw new Error("userTables and auth.organizations are both on; tables users add are not kept per organization yet, so turn one of them off");
+	return config;
+};
+//#endregion
+export { checkUserTables, userTablesOn };

package/dist/dev/entry.js

@@ -2,12 +2,13 @@ import { buildProject } from "../config/build-project.js";
 import { projectIcons } from "../build/app-icons.js";
 import { projectErrorReporter } from "../project/error-reporter.js";
 import { projectAdmin } from "../project/project-admin.js";
+import { projectUserTables } from "../project/project-user-tables.js";
 import { devJobs } from "./dev-jobs.js";
 import { devRealtimePrune } from "./dev-prune.js";
 import { devDatabase, loadDevConfig } from "./project.js";
 import { withDevServiceWorker } from "./service-worker-route.js";
 import { setMissing, supabaseEnv } from "./supabase-env.js";
-import { apiKeySettings, assistantSettings, authSchemaDrift, authStoreTables, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkWebhooksSchema, configExports, hasUsers, relayed, sqlSends } from "@protobase/server";
+import { apiKeySettings, assistantSettings, authSchemaDrift, authStoreTables, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkUserTablesSchema, checkWebhooksSchema, configExports, hasUsers, relayed, sqlSends } from "@protobase/server";
 import { upgradeWebSocket } from "@hono/node-server";
 import { Hono } from "hono";
 //#region src/dev/entry.ts
@@ -42,6 +43,7 @@ if (relayed(project.realtime)) await checkRealtimeRelay(db);
 if (sqlSends(project.realtime)) await checkChannelSends(db);
 if (project.notifications) await checkNotificationsSchema(db, project.notifications, project.auth);
 if (project.status) await checkStatusSchema(db, project.status, project.auth);
+if (project.userTables) await checkUserTablesSchema(db);
 setMissing(process.env, supabaseEnv({
 	url: process.env.PROTOBASE_DEV_URL,
 	databaseUrl: process.env.PROTOBASE_DATABASE_URL,
@@ -54,7 +56,7 @@ const ui = {
 	fieldTypes: {},
 	icons: projectIcons(projectDir)
 };
-const { admin, jobs } = projectAdmin(project, db, ui, reporter, upgradeWebSocket);
+const { admin, jobs } = projectAdmin(project, db, ui, reporter, upgradeWebSocket, await projectUserTables(project, db));
 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);

package/dist/doctor/run.js

@@ -1,3 +1,4 @@
+import { userTablesOn } from "../config/user-tables-config.js";
 import { loadSourceConfig } from "../config/source-config.js";
 import { connect } from "../db/connect.js";
 import { introspect } from "../db/introspect.js";
@@ -9,6 +10,7 @@ import { indexIssues } from "./index-issues.js";
 import { readShapes } from "./read-shapes.js";
 import { relationIssues } from "./relation-issues.js";
 import { sortIssues } from "./sort-issues.js";
+import { userTableModels } from "./user-table-models.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { tableIndexes } from "@protobase/query";
@@ -18,26 +20,36 @@ const runDoctor = async (options, out) => {
 	if (!existsSync(path.join(options.configDir, "index.ts"))) throw new Error(`No config in ${options.configDir}: write it with \`protobase scaffold\`, or pass --config <dir>`);
 	const config = await loadDataConfig(options.configDir, options.projectDir);
 	if (config.models.length === 0) throw new Error(`No resources exported from ${options.configDir}/index.ts`);
-	const builtIn = builtInModels(await loadSourceConfig(options.projectDir, { command: "tool" }), config.models);
-	const models = [...builtIn.models, ...config.models];
+	const source = await loadSourceConfig(options.projectDir, { command: "tool" });
+	const builtIn = builtInModels(source, config.models);
 	const sql = connect(options.url);
 	const tables = await introspect(sql, { views: true }).finally(() => sql.end());
 	const db = readOnlyDb(options.url);
+	const userTables = userTablesOn(source) ? await userTableModels(db, [...builtIn.models, ...config.models]) : {
+		models: [],
+		issues: []
+	};
+	const models = [
+		...builtIn.models,
+		...config.models,
+		...userTables.models
+	];
 	const shapes = readShapes({
 		models,
 		views: [...builtIn.views, ...config.views],
 		pages: config.pages
 	});
 	const indexes = await Promise.all(models.map(async (model) => indexIssues(model, await tableIndexes(db, model), shapes))).then((found) => found.map((issues, i) => i < builtIn.models.length ? builtInIndexIssues(issues) : issues)).finally(() => db.destroy());
-	const issues = models.flatMap((model, i) => [
+	const issues = [...userTables.issues, ...models.flatMap((model, i) => [
 		...checkResource(model, tables),
 		...relationIssues(model, models),
 		...sortIssues(model, shapes),
 		...indexes[i]
-	]);
+	])];
 	for (const issue of issues) out(format(issue));
 	const errors = issues.filter((i) => i.severity === "error").length;
-	out(`Checked ${builtIn.models.length > 0 ? `${config.models.length} resources and ${builtIn.models.length} built-in ones` : `${models.length} resources`}: ${errors} errors, ${issues.length - errors} warnings.\n`);
+	const counted = userTables.models.length > 0 ? `${config.models.length} resources, ${userTables.models.length} user tables` : `${config.models.length} resources`;
+	out(`Checked ${builtIn.models.length > 0 ? `${counted} and ${builtIn.models.length} built-in ones` : counted}: ${errors} errors, ${issues.length - errors} warnings.\n`);
 	return {
 		errors,
 		warnings: issues.length - errors

package/dist/doctor/user-table-models.js

@@ -0,0 +1,26 @@
+import { userTableResources } from "@protobase/server/config-exports";
+//#region src/doctor/user-table-models.ts
+/**
+* The models of the tables users add, which doctor checks like the config's, and an error for each definition that
+* does not fit the database or whose name a resource in code has, as the server leaves those out.
+*/
+const userTableModels = async (db, codeModels) => {
+	const tables = await userTableResources(db);
+	const taken = new Set(codeModels.map((model) => model.name));
+	const built = tables.resources.map((source) => source.toModel());
+	const issues = [...tables.problems.map((message) => ({
+		severity: "error",
+		resource: "user tables",
+		message
+	})), ...built.filter((model) => taken.has(model.name)).map((model) => ({
+		severity: "warning",
+		resource: model.name,
+		message: "a resource in code has the name of this user table, which is not served"
+	}))];
+	return {
+		models: built.filter((model) => !taken.has(model.name)),
+		issues
+	};
+};
+//#endregion
+export { userTableModels };

package/dist/migration/load-project.js

@@ -1,5 +1,6 @@
 import { loadNearestEnvFile } from "../dev/env.js";
 import { projectJobs, projectNotifications, projectResources, projectWebhooks } from "../config/project-parts.js";
+import { userTablesOn } from "../config/user-tables-config.js";
 import { projectAuth } from "../config/build-project.js";
 import { loadSourceConfig } from "../config/source-config.js";
 import { openAppDatabase } from "../project/pg-db.js";
@@ -44,6 +45,7 @@ const migrationProject = async (config, url) => {
 		...notifications && { notifications },
 		...config.status && { status: checkStatusOptions(config.status) },
 		jobs,
+		userTables: userTablesOn(config),
 		readOnlyQueries: assistantSettings(config.assistant, process.env)?.kind === "built-in",
 		authTables: auth ? authStoreTables(auth) : {
 			tables: [],

package/dist/migration/parts.js

@@ -1,5 +1,5 @@
 import { authMigrationTitle } from "../auth/migration-file.js";
-import { authSchemaMigration, callsMigration, changesMigration, channelSendsMigration, commentsMigration, computedMigration, isCaptured, jobsSchemaMigration, notificationsMigration, queryRunnerMigration, realtimeRelayMigration, relayed, sqlSends, statusMigration, webhooksMigration } from "@protobase/server";
+import { authSchemaMigration, callsMigration, changesMigration, channelSendsMigration, commentsMigration, computedMigration, isCaptured, jobsSchemaMigration, notificationsMigration, queryRunnerMigration, realtimeRelayMigration, relayed, sqlSends, statusMigration, userTablesMigration, webhooksMigration } from "@protobase/server";
 //#region src/migration/parts.ts
 /** Every feature the project's config enables, in the order their files are written. */
 const migrationParts = (project) => {
@@ -61,6 +61,11 @@ const migrationParts = (project) => {
 			title: "The relay of Realtime broadcasts and presence between the processes serving the app",
 			sql: () => realtimeRelayMigration(project.db)
 		}] : [],
+		...project.userTables ? [{
+			name: "user_tables",
+			title: "The schemas of the tables users add and of their definitions, and pg_trgm",
+			sql: () => userTablesMigration(project.db)
+		}] : [],
 		...sqlSends(project.realtime) ? [{
 			name: "channel_sends",
 			title: "SQL's broadcasts to the record channels, channels.send()",

package/dist/project/project-admin.js

@@ -6,14 +6,16 @@ import { configExports, createAdmin } from "@protobase/server";
 * types and which icons are the project's own (`protobase dev` passes the project's icons alone). `jobs` are the
 * project's own and the delivery of its events and history. With a `reporter`, every error the API turns into a 500,
 * and every stopped query, goes to the error tracker too, besides the project's `onUnhandledError` or the console. With
-* the host's `upgradeWebSocket`, it serves `/api/sb/realtime/v1` too.
+* the host's `upgradeWebSocket`, it serves `/api/sb/realtime/v1` too. With `userTables`, the tables users add serve
+* beside the config's resources (see `projectUserTables`).
 */
-const projectAdmin = (project, db, ui, reporter, upgradeWebSocket) => {
+const projectAdmin = (project, db, ui, reporter, upgradeWebSocket, userTables) => {
 	const { resources, views, pages, userMenu, bottomBars, subscriptions } = configExports(project.config);
 	const unhandled = project.options?.onUnhandledError ?? ((error) => console.error(error));
 	const admin = createAdmin({
 		resources,
 		views,
+		...userTables && { userTables },
 		pages,
 		...userMenu && { userMenu },
 		bottomBars,

package/dist/project/project-user-tables.js

@@ -0,0 +1,15 @@
+import { userTableResources } from "@protobase/server";
+//#region src/project/project-user-tables.ts
+/**
+* The tables users add, read from their definitions when the project turns `userTables` on, nothing otherwise, even
+* when the definitions are in the database. Each definition that does not fit the database is printed as a warning and
+* left out, so the rest of the app serves.
+*/
+const projectUserTables = async (project, db) => {
+	if (!project.userTables) return;
+	const tables = await userTableResources(db);
+	for (const problem of tables.problems) console.warn(problem);
+	return tables;
+};
+//#endregion
+export { projectUserTables };

package/dist/scaffold/plan.js

@@ -45,7 +45,7 @@ const planScaffold = async (input) => {
 	const byTable = new Map(existing.map((resource) => [resource.table, resource]));
 	const wanted = (table) => matchesTarget(input.target, table) && !isExcluded(input.excludes, table);
 	const tables = input.tables.filter((table) => table.kind === "table");
-	const protobase = protobaseSchemas(tables, input.target);
+	const protobase = protobaseSchemas(tables, input.target, new Set(byTable.keys()));
 	const skipped = protobase.map((found) => ({
 		...found,
 		tables: found.tables.filter(wanted)

package/dist/scaffold/protobase-tables.d.ts

@@ -2,7 +2,7 @@ import { DbTable } from "../db/model.js";
 //#region src/scaffold/protobase-tables.d.ts
 export type ProtobaseSchema = {
   schema: string;
-  what: 'auth store' | 'job queue' | 'record of migrations';
+  what: 'auth store' | 'job queue' | 'record of migrations' | 'table definitions' | 'user tables';
   tables: DbTable[];
 };
 //#endregion

package/dist/scaffold/protobase-tables.js

@@ -1,4 +1,6 @@
+import { tableKey } from "../db/model.js";
 import { migrationsTableName, storeTableNames } from "@protobase/server/auth-store";
+import { definitionsSchema, userTablesSchema } from "@protobase/server/config-exports";
 //#region src/scaffold/protobase-tables.ts
 const storeCore = [
 	"session",
@@ -21,14 +23,28 @@ const authStore = (schema, tables) => {
 };
 const jobQueue = (schema, tables) => schema === "jobs" && ["job", "version"].every((name) => tables.some((table) => table.name === name)) ? tables : [];
 const migrationRecord = (schema, tables) => schema === "migrations" && tables.some((table) => table.name === "applied") ? tables : [];
-const protobaseSchemas = (tables, target) => [...bySchema(tables)].flatMap(([schema, own]) => {
+const tableDefinitions = (schema, tables) => schema === definitionsSchema && ["tables", "fields"].every((name) => tables.some((table) => table.name === name)) ? tables : [];
+const userTables = (schema, tables, claimed) => schema === userTablesSchema ? tables.filter((table) => !claimed.has(tableKey(table))) : [];
+const protobaseSchemas = (tables, target, claimed = /* @__PURE__ */ new Set()) => [...bySchema(tables)].flatMap(([schema, own]) => {
 	const store = authStore(schema, own);
 	if (store.length > 0) return [{
 		schema,
 		what: "auth store",
 		tables: store
 	}];
+	const added = userTables(schema, own, claimed);
+	if (added.length > 0) return [{
+		schema,
+		what: "user tables",
+		tables: added
+	}];
 	if (target.schema === schema) return [];
+	const definitions = tableDefinitions(schema, own);
+	if (definitions.length > 0) return [{
+		schema,
+		what: "table definitions",
+		tables: definitions
+	}];
 	const queue = jobQueue(schema, own);
 	if (queue.length > 0) return [{
 		schema,

package/dist/serve/lifecycle.js

@@ -2,6 +2,7 @@ import { protobaseVersion } from "../version/version.js";
 import { buildProject } from "../config/build-project.js";
 import { openAppDatabase } from "../project/pg-db.js";
 import { projectAdmin } from "../project/project-admin.js";
+import { projectUserTables } from "../project/project-user-tables.js";
 import { apiWebSocketServer } from "../project/api-websocket-server.js";
 import { withClientAddress } from "./client-address.js";
 import { createServeApp } from "./app.js";
@@ -9,7 +10,7 @@ import { startCleanupTimer } from "./cleanup-timer.js";
 import { closeSockets } from "./close-sockets.js";
 import { servedRelease } from "./mobile-release.js";
 import pg from "pg";
-import { assistantSettings, authStoreTables, backgroundSettled, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkWebhooksSchema, configExports, createFileCleanup, relayed, sqlSends, startJobs } from "@protobase/server";
+import { assistantSettings, authStoreTables, backgroundSettled, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkUserTablesSchema, checkWebhooksSchema, configExports, createFileCleanup, relayed, sqlSends, startJobs } from "@protobase/server";
 import { createAdaptorServer, upgradeWebSocket } from "@hono/node-server";
 //#region src/serve/lifecycle.ts
 const listen = (server, port) => new Promise((resolve, reject) => {
@@ -48,7 +49,8 @@ const startServe = async ({ config, env, openDb = (url) => openAppDatabase(pg, u
 		if (env.startupChecks && sqlSends(project.realtime)) await checkChannelSends(db);
 		if (env.startupChecks && project.notifications) await checkNotificationsSchema(db, project.notifications, project.auth);
 		if (env.startupChecks && project.status) await checkStatusSchema(db, project.status, project.auth);
-		const { admin, jobs: definitions } = projectAdmin(project, db, ui, reporter, upgradeWebSocket);
+		if (env.startupChecks && project.userTables) await checkUserTablesSchema(db);
+		const { admin, jobs: definitions } = projectAdmin(project, db, ui, reporter, upgradeWebSocket, await projectUserTables(project, db));
 		if (env.startupChecks && definitions.length > 0) await checkJobsSchema(db);
 		const jobs = definitions.length > 0 ? await startJobs({
 			db,

package/dist/serve/load-bundle.js

@@ -1,4 +1,5 @@
 import { mergeConfig } from "../config/merge-config.js";
+import { checkUserTables } from "../config/user-tables-config.js";
 import { withDefaults } from "../config/config-defaults.js";
 import { calledConfig } from "../config/called-config.js";
 import { bundleBasePath } from "../bundle/manifest.js";
@@ -36,7 +37,7 @@ const bundledConfig = async (bundle, command, root) => {
 		files: projectFiles(files, bundle.packages),
 		label
 	});
-	const config = withDefaults(mergeConfig(...sources), command, process.env);
+	const config = checkUserTables(withDefaults(mergeConfig(...sources), command, process.env));
 	const basePath = config.apiPath;
 	if (basePath !== void 0 && basePath !== "/api/v1") throw new Error(`apiPath is ${JSON.stringify(basePath)}; a bundle's UI and manifest expect the API at ${bundleBasePath}, so remove it (see https://docs.protobase.net/reference/cli/#the-manifest)`);
 	return config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/cli",
-  "version": "0.66.16",
+  "version": "0.67.1",
   "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.16",
-    "@protobase/layout": "0.66.16",
-    "@protobase/query": "0.66.16",
-    "@protobase/schema": "0.66.16",
-    "@protobase/server": "0.66.16",
-    "@protobase/ui": "0.66.16",
+    "@protobase/config": "0.67.1",
+    "@protobase/layout": "0.67.1",
+    "@protobase/query": "0.67.1",
+    "@protobase/schema": "0.67.1",
+    "@protobase/server": "0.67.1",
+    "@protobase/ui": "0.67.1",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/vite-plugin": "^11.10.0",

package/skills/protobase/SKILL.md

@@ -101,6 +101,7 @@ Reference:
 - When using components and action handlers of your own in layouts → read [Custom components](references/reference/custom-components.md)
 - When building or loading plugins → read [Plugins](references/reference/plugins.md)
 - When using resources another Protobase API serves → read [Remote resources](references/reference/remote-resources.md)
+- When an app keeps tables its users add in its own database (`userTables`) → read [User tables](references/reference/user-tables.md)
 - When setting the app's tokens, colors and fonts → read [Theme](references/reference/theme.md)
 - When setting the app's name, icon, home-screen icons or install colours → read [App identity](references/reference/app-identity.md)
 - When showing the app's screens in Dutch → read [Languages](references/reference/languages.md)

package/skills/protobase/references/features/user-tables.md

@@ -0,0 +1,7 @@
+<!-- Generated by scripts/protobase-skill.ts from docs/website/src/content/docs/features/user-tables.md: run `bun run docs:skill`, do not edit. -->
+
+# Tables users add
+
+Tables an app's users add from the admin UI, by hand or from a file, and how a developer takes them over as code.
+
+- [Tables defined in the database](../reference/user-tables.md#tables-defined-in-the-database) (in development): An app can keep tables its users add in its own database, beside the resources in its code. Each one is served like any other resource, at its own address with its list, record page, search and API.

package/skills/protobase/references/features.md

@@ -16,6 +16,7 @@ A feature without a mark is stable. The others say so after their name:
 
 - [Start a project](features/start-a-project.md): Start a new app, or an admin over an existing Postgres database, and keep the config in step with it.
 - [Data model](features/data-model.md): Describe the tables of an existing Postgres database as resources, with their fields, keys and rules.
+- [Tables users add](features/user-tables.md): Tables an app's users add from the admin UI, by hand or from a file, and how a developer takes them over as code.
 - [Access](features/access.md): Decide who may read and change which records and fields.
 - [Lists](features/lists.md): The list page of each resource, with its columns, filters, charts, search, exports and imports.
 - [List displays](features/list-displays.md): Show a list as cards, a map, a board, a calendar or a timeline, and reorder records by hand.

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

@@ -232,7 +232,7 @@ The page is checked like any other, and the account blocks are allowed on it alo
 With mail configured, the sign-in page offers "Forgot password?": the person enters their email, gets a link, and chooses a new password on the page the link opens. It is Better Auth's own reset: `POST /api/auth/request-password-reset` with `{ email, redirectTo }`, the emailed link `GET /api/auth/reset-password/<token>`, which sends the browser back to `redirectTo` with `?token=...` (or `?error=INVALID_TOKEN`), and `POST /api/auth/reset-password` with `{ token, newPassword }`.
 
 ```sh
-PROTOBASE_SMTP_URL=smtps://user:password@smtp.example.com:465   # or smtp://...:587, STARTTLS when the server offers it
+PROTOBASE_SMTP_URL=smtps://user:password@smtp.example.com:465   # or smtp://...:587, which requires STARTTLS unless the URL ends in ?requireTLS=false
 PROTOBASE_MAIL_FROM=noreply@admin.example.com
 ```
 

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

@@ -403,7 +403,7 @@ Serves the API of a bundle from `protobase build` and owns the process around it
 | `PROTOBASE_DB_CONNECTIONS` | the connections that pool opens, such as the database's limit for the app; default 10. Sign-in's store shares them. [API functions](../guides/api-functions.md) and [jobs](jobs.md) hold at most one less, so a long import leaves a connection to page and API requests; those with [`longQueries`](../guides/api-functions.md#long-queries) take theirs from one more connection, kept for them. A query waits at most 2 seconds for a free connection, then fails with `503 connections-busy` ([Safety](api.md#safety)); a new connection may take up to 30 seconds to open, such as while a database that scaled to zero wakes |
 | `PORT` | default 8787 |
 | `REQUEST_LOG` | `true` logs every request; default `false` |
-| `PROTOBASE_SMTP_URL` | the SMTP server for password-reset mail, emailed sign-in and two-factor codes and the app's own [email](email.md), credential included: `smtp://user:password@host:587` (STARTTLS when offered) or `smtps://...:465`; without it they are off ([Password reset](auth.md#password-reset), [Emailed sign-in codes](auth.md#emailed-sign-in-codes)) |
+| `PROTOBASE_SMTP_URL` | the SMTP server for password-reset mail, emailed sign-in and two-factor codes and the app's own [email](email.md), credential included: `smtp://user:password@host:587` (STARTTLS required, `?requireTLS=false` sends in plaintext, see [Email](email.md#configuration)) or `smtps://...:465`; without it they are off ([Password reset](auth.md#password-reset), [Emailed sign-in codes](auth.md#emailed-sign-in-codes)) |
 | `PROTOBASE_MAIL_FROM` | the sender of that mail, a plain address such as `noreply@admin.example.com`; set with `PROTOBASE_SMTP_URL` or not at all |
 | `PROTOBASE_APP_NAME` | the app's name, such as `Property Finder`: what its auth emails, its sidebar, its browser tabs and the [installed app](installable-app.md) call it, and the sender's display name of its mail, over the config's [`name`](config/app.md#name) |
 | `PROTOBASE_SIGN_IN_ISSUER`, `PROTOBASE_SIGN_IN_CLIENT_ID`, `PROTOBASE_SIGN_IN_CLIENT_SECRET` | an OpenID Connect provider people who have an account can sign in with; all three or none. `PROTOBASE_SIGN_IN_PROVIDER` and `PROTOBASE_SIGN_IN_NAME` are optional ([Platform sign-in provider](auth.md#platform-sign-in-provider)) |

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

@@ -173,6 +173,17 @@ export default defineConfig(({ env }) => ({
 }))
 ```
 
+## userTables
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+`true` keeps the tables the app's users add in its own database, in the `table_definitions` and `user_tables` schemas that [`protobase migration`](../cli.md#migration) writes, and serves each one like a resource in code. It cannot be on together with organizations. See [User tables](../user-tables.md).
+
+```ts
+export default defineConfig({ userTables: true })
+```
+
 ## Code of the API
 
 Two files of the project's own change what the API does, each its default export, with no key in the config:

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

@@ -28,7 +28,7 @@ Each key is described with its type and default in the option pages:
 | --- | --- |
 | [App options](config/app.md) | `name`, `url`, `secret`, `previousSecrets`, `locale`, `timezone`, `themeColor`, `backgroundColor`, `mobile` |
 | [Sign-in options](config/sign-in.md) | `auth`, `authenticate`, `signingKeyDays`, `signingKeyGraceDays` |
-| [API options](config/api.md) | `apiPath`, `apiKeys`, `cors`, `defaultAccess`, `rowPermissions`, `statementTimeoutMs`, `scanGuard`, `errorReporting`, `writeHooks`, `mcpEndpoint`, `remoteResources`, `runtimeUpdates`, `realtime`, `calls` |
+| [API options](config/api.md) | `apiPath`, `apiKeys`, `cors`, `defaultAccess`, `rowPermissions`, `statementTimeoutMs`, `scanGuard`, `errorReporting`, `writeHooks`, `mcpEndpoint`, `remoteResources`, `runtimeUpdates`, `realtime`, `calls`, `userTables` |
 | [Admin app options](config/admin-app.md) | `assistant`, `maps`, `plugins` |
 | [Jobs and events options](config/jobs-and-events.md) | `jobs`, `events`, `history`, `webhooks`, `notifications`, `status` |
 | [Files options](config/files.md) | `files` |

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

@@ -10,7 +10,7 @@ An app sends mail through one SMTP server: Protobase's own mail ([password reset
 
 | Variable | |
 | --- | --- |
-| `PROTOBASE_SMTP_URL` | The SMTP server, credential included: `smtp://user:password@host:587` (STARTTLS when the server offers it) or `smtps://user:password@host:465` (TLS from the start). |
+| `PROTOBASE_SMTP_URL` | The SMTP server, credential included: `smtp://user:password@host:587` (STARTTLS required) or `smtps://user:password@host:465` (TLS from the start). |
 | `PROTOBASE_MAIL_FROM` | The sender, a plain address such as `noreply@shop.example.com`. The client greets the server with its domain; a `?name=` on the URL overrides that. |
 | `PROTOBASE_APP_NAME` | Optional: the app's name, such as `Shop`, which mail clients show as the sender's name (`Shop <noreply@shop.example.com>`). It overrides the config's [`name`](config/app.md#name). Without either the sender has no name. |
 
@@ -22,10 +22,12 @@ Set both or neither. One without the other, a URL that is not `smtp://` or `smtp
 docker run -d -p 8025:8025 -p 1025:1025 axllent/mailpit   # its inbox is http://localhost:8025
 
 # .env
-PROTOBASE_SMTP_URL=smtp://localhost:1025
+PROTOBASE_SMTP_URL=smtp://localhost:1025?requireTLS=false
 PROTOBASE_MAIL_FROM=noreply@shop.example.com
 ```
 
+Over `smtp://` the client always upgrades the connection with STARTTLS before it logs in or sends anything, so nobody between the app and the server reads the server's password or the mail, such as a sign-in code or a reset link. A server that does not offer STARTTLS, or an answer from which someone on the way removed it, fails the send, with the code `ETLS` when the server refuses the upgrade. `?requireTLS=false` on the URL is the only way to send in plaintext, for a server that has no TLS, such as the mail catcher above or a server on the same host. `smtps://` uses TLS from the start.
+
 A project that delivers its mail another way exports a mailer, `{ send({ to, subject, text, html, headers }) }`, as the default of `auth/mailer.ts`: sign-in and the jobs (`mail` in their context) both send with it. `auth: { mailer: false }` turns sign-in's mail off whatever the environment says. A host that runs jobs itself passes a mailer to `startJobs`. A template's `send` takes one too, see [Templates](#templates).
 
 ### When the server does not answer

package/skills/protobase/references/reference/user-tables.md

@@ -0,0 +1,66 @@
+<!-- Generated by scripts/protobase-skill.ts from docs/website/src/content/docs/reference/user-tables.md: run `bun run docs:skill`, do not edit. -->
+
+# User tables
+
+The switch that keeps tables users add in the app's own database, the two schemas they live in, the migration that adds them, and how each one is served.
+
+An app's resources usually come from its code: a resource in `config/` over a table a migration made. With user tables on, the app also keeps tables its users add in its own database, and serves each one beside the resources in code.
+
+## Tables defined in the database
+
+:::caution[In development]
+The server serves the tables defined in the database, but no screen or API adds one yet, and a definition added while the server runs is served after its next start.
+:::
+
+An app can keep tables its users add in its own database, beside the resources in its code. Each one is served like any other resource, at its own address with its list, record page, search and API.
+
+<gap>Tables users add cannot be used in an app with organizations because keeping their definitions and records per organization is not implemented.</gap>
+
+<gap>Users cannot add a table yet because the screens and the API that create one are not implemented.</gap>
+
+<gap>A definition added while the server runs cannot be served before the server starts again because picking up new definitions while serving is not implemented.</gap>
+
+### The switch
+
+User tables are off by default. Turn them on in `protobase.config.ts`:
+
+```ts
+export default defineConfig({ userTables: true })
+```
+
+`userTables` takes only `true` or `false`. Together with organizations (`auth.organizations`), `dev`, `build` and `serve` stop with an error that names both settings.
+
+### The schemas and the migration
+
+The tables users add and their definitions live in two schemas of the app's database, so a table's name can never reach a definition:
+
+| Schema | What it holds |
+| --- | --- |
+| `table_definitions` | `tables`, one row per table users add, with its singular and plural label, its title field and a version, and `fields`, each table's fields in order with their label, type and whether they are required |
+| `user_tables` | the tables themselves, each with an `id bigint generated always as identity` primary key and a column per field |
+
+With `userTables: true`, [`protobase migration`](cli.md#migration) writes a migration that adds both schemas, the two definition tables and the `pg_trgm` extension when it is missing, and grants the app's database role CREATE on `user_tables` alone, and writes nothing once the database has them. Apply it with the project's other migrations; the server never creates them itself. At start, `dev` and `serve` stop while one is missing; `PROTOBASE_STARTUP_CHECKS=false` skips that check in `serve`, as it skips the others.
+
+A table's name and each field's name are lowercase letters, digits and `_`, starting with a letter, at most 63 bytes. A field is one of these types:
+
+| Type | Column |
+| --- | --- |
+| `text` | `text` |
+| `long_text` | `text`, edited in a box that grows with it |
+| `integer` | `integer` |
+| `decimal` | `numeric`, with the definition's precision and scale |
+| `boolean` | `boolean` |
+| `date` | `date` |
+| `timestamp` | `timestamptz` |
+| `json` | `jsonb` |
+
+### How each one is served
+
+When the server starts, it builds a resource from each definition and serves it at `/<table>` and `/<table>/<key>`, with its list, record page, sidebar entry and REST API, and in `/meta`, as the resources in code are. The labels of the definition are the names the admin app shows.
+
+- **Admins only.** Each table starts readable and writable by admins alone, and is left out of role wildcards such as `*.read`, like [resources that need named grants](access.md#resources-that-need-named-grants). Anyone else does not see it.
+- **Filters, sorts and search follow the indexes.** A field can be filtered or sorted by only where an index of its table serves it, and the table is searched on its title field only where a `pg_trgm` index serves that field, as the [scan guard](config/api.md#scanguard) requires.
+- **A definition that does not fit is left out.** A definition with a name or type outside the rules above, or whose table or columns do not match it, is not served, and the server prints why at start. The rest of the app serves.
+- **Code wins.** A resource in code with the name of a user table, or a resource Protobase adds, is served instead of the definition, which is then ignored with a warning. This is how a table users added is taken over as code.
+
+[`protobase doctor`](cli.md#doctor) checks each definition against the database as it checks the resources in code, and reports each one it leaves out as an error. [`protobase scaffold`](cli.md#scaffold) leaves out the definitions and the tables in `user_tables` that no resource in code claims, and writes and updates the config of one that a resource claims.