@protobase/cli 0.67.4 → 0.67.6

package/dist/cli/package.js

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

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

@@ -2,13 +2,14 @@
 /** 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.
+* Refuses a `userTables` that is no boolean, and user tables in an API that trusts the organization tokens of an auth
+* server elsewhere (`authenticate.organizations` without `auth.organizations`): it cannot read who owns or manages an
+* organization, which decides who sees its tables. With the app's own organizations, each keeps its own tables.
 */
 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");
+	if (userTablesOn(config) && config.authenticate?.organizations && !(config.auth && config.auth.organizations)) throw new Error("userTables and authenticate.organizations are both on without auth.organizations; tables users add need the app's own organizations, so turn one of them off");
 	return config;
 };
 //#endregion

package/dist/eject/read-ejected.js

@@ -7,7 +7,8 @@ import { userTableResources, userTablesSchema } from "@protobase/server/config-e
 const notServed = (name, problems) => problems.find((problem) => problem.startsWith(`The user table "${name}" `)) ?? `No table users added is named "${name}"`;
 /**
 * Each named table users added as the server serves it, with the constraints and indexes of its table, read from the
-* database at `url` in read-only sessions. A name the server serves no table of stops it, with why.
+* database at `url` in read-only sessions. A name the server serves no table of, or an organization's table, stops it,
+* with why.
 */
 const readEjected = async (url, names) => {
 	const sql = connect(url);
@@ -17,6 +18,7 @@ const readEjected = async (url, names) => {
 		const tables = names.map((name) => {
 			const definition = served.definitions.find((each) => each.name === name);
 			if (!definition) throw new Error(notServed(name, served.problems));
+			if (definition.organization_id !== null) throw new Error(`"${name}" belongs to an organization: take it over with \`protobase scaffold\`, which keeps its records in it`);
 			return {
 				table: relations.find((each) => each.schema === userTablesSchema && each.name === name),
 				definition,

package/dist/scaffold/data-file.js

@@ -58,5 +58,13 @@ const makeLiveInDataFile = (text) => {
 	chain.chainTop.replaceWithText(`${chain.chainTop.getText()}\n  .live()`);
 	return source.getFullText();
 };
+const addTenantToDataFile = (text, field) => {
+	const source = parseSource(text);
+	const chain = resourceChain(source);
+	if (!chain) throw new Error("data.ts has no resource(...) builder chain to scope to its tenant");
+	if (methodCalls(chain.chainTop, "tenant").length > 0) return text;
+	chain.chainTop.replaceWithText(`${chain.chainTop.getText()}\n  .tenant((r) => r.${field})`);
+	return source.getFullText();
+};
 //#endregion
-export { addFieldsToDataFile, makeLiveInDataFile, renderDataFile };
+export { addFieldsToDataFile, addTenantToDataFile, makeLiveInDataFile, renderDataFile };

package/dist/scaffold/organization-tables.js

@@ -0,0 +1,21 @@
+import { definitionsSchema, userTablesSchema } from "@protobase/server/config-exports";
+//#region src/scaffold/organization-tables.ts
+/**
+* The tables users add that belong to an organization, as `schema.table` with the organization's id, from their
+* definitions: none when the database keeps no definitions, or none made with organizations.
+*/
+const readOrganizationTables = async (sql) => {
+	const [found] = await sql`select exists (select from information_schema.columns
+    where table_schema = ${definitionsSchema} and table_name = 'tables' and column_name = 'organization_id') as organizations`;
+	if (!found?.organizations) return /* @__PURE__ */ new Map();
+	const rows = await sql`select table_name, organization_id
+    from ${sql(definitionsSchema)}.tables where organization_id is not null`;
+	return new Map(rows.map((row) => [`${userTablesSchema}.${row.table_name}`, row.organization_id]));
+};
+/**
+* What scaffold says when it takes over an organization's table: whose definition it took, that the records keep their
+* organization, and that the access rule the server gave the table does not come along.
+*/
+const takenOverLine = (table, organizationId) => `${table}: taken over from the definition of organization ${organizationId}; its records keep their organization through .tenant((r) => r.organization_id). Served from its definition, only that organization's owners and admins reached it; the resource in code follows the project's access rules instead, so add .access(...) to keep it to them`;
+//#endregion
+export { readOrganizationTables, takenOverLine };

package/dist/scaffold/plan.js

@@ -3,8 +3,9 @@ import { keyColumns } from "../db/keys.js";
 import { protobaseSchemas } from "./protobase-tables.js";
 import { camelCase } from "../infer/names.js";
 import { findField } from "./existing-config.js";
+import { takenOverLine } from "./organization-tables.js";
 import { proposeField } from "../infer/proposal.js";
-import { addFieldsToDataFile, makeLiveInDataFile, renderDataFile } from "./data-file.js";
+import { addFieldsToDataFile, addTenantToDataFile, makeLiveInDataFile, renderDataFile } from "./data-file.js";
 import { detectDrift } from "./drift.js";
 import { ensureExports } from "./index-file.js";
 import { assignNames } from "./resource-names.js";
@@ -96,8 +97,11 @@ const planScaffold = async (input) => {
 			const clash = decisions.find((d) => current.fields.some((f) => f.name === d.proposal.name));
 			if (clash) throw new Error(`${key}: field "${clash.proposal.name}" already exists, edit the name`);
 			const file = path.join(configDir, current.dir, "data.ts");
+			const organization = input.organizationTables?.get(key);
 			const fielded = addFieldsToDataFile(current.text, decisions);
-			changes.push(...change(file, current.text, isLive(key) ? makeLiveInDataFile(fielded) : fielded));
+			const scoped = organization === void 0 ? fielded : addTenantToDataFile(fielded, "organization_id");
+			if (organization !== void 0) warnings.push(takenOverLine(key, organization));
+			changes.push(...change(file, current.text, isLive(key) ? makeLiveInDataFile(scoped) : scoped));
 			if (isLive(key)) live.push(key);
 			drift.push(...detectDrift(current, table, context(table)));
 			await writeUi(current.dir, current.name, current.identifier, table, current, decisions);

package/dist/scaffold/run.js

@@ -1,6 +1,7 @@
 import { connect } from "../db/connect.js";
 import { introspect } from "../db/introspect.js";
 import { readExistingResources } from "./existing-config.js";
+import { readOrganizationTables } from "./organization-tables.js";
 import { parseTarget } from "./targets.js";
 import { planScaffold } from "./plan.js";
 import { acceptAll, interactive } from "./prompt.js";
@@ -31,6 +32,7 @@ const runScaffold = async (options, out) => {
 				target: parseTarget(options.target),
 				excludes: options.excludes,
 				live: options.live,
+				organizationTables: await readOrganizationTables(sql),
 				decide: options.decide ?? prompter?.decide ?? acceptAll,
 				ui: options.ui,
 				readText

package/package.json

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

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

@@ -7,3 +7,4 @@ Tables an app's users add from the admin UI, by hand or from a file, and how a d
 - [Tables defined in the database](../reference/user-tables.md#tables-defined-in-the-database) (beta): 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. Every server process serves a new table within a second of it being added.
 - [Adding tables and fields](../reference/user-tables.md#adding-tables-and-fields) (beta): Someone with the right capability creates a table with its fields, or adds a field to it, through the app's API. It is created in the database at once, with an index for every field but JSON so its list can be filtered by it, and sorted by it unless it is long text, and only admins can see it until access is widened.
 - [Taking a table over as code](../reference/cli.md#eject) (beta): `protobase eject` turns a table someone added in the admin app into ordinary config and a migration in the project, so a developer can customise it like any other resource. Its records stay where they are.
+- [Tables per organization](../reference/user-tables.md#organizations) (beta): In an app with organizations, a table someone adds belongs to their organization. Only its owners and admins, and superusers working in it, see the table and its records.

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

@@ -636,13 +636,13 @@ auth: {
 
 It is Better Auth's organization plugin, with its tables named in snake_case (`organization`, `member`, `invitation`, `session.active_organization_id`); every store has them, and `user.last_organization_id`, with organizations on or off (see [migrations](#migrations)).
 
-**Two kinds of role.** Every membership has an organization role, Better Auth's `owner`, `admin` or `member`, which decides who manages the organization: owners and admins invite, remove and change members and edit its details; only owners hand it over, delete it or make owners. App roles, the project's `roles`, decide what the app shows and allows. A user holds them **globally** (the admin plugin's `role` column, as without organizations), which applies in every organization, or **per membership** (`member.app_roles`), which applies there only. A request's role, `ctx.user.roles`, is the session's [active role](#active-role), of either kind; access rules never see the organization role. `admin` is the superuser: global only, it holds every role. With organizations every role needs a label; `owner` and `member` cannot be app role names, and `user` stands for an account without a global role.
+**Two kinds of role.** Every membership has an organization role, Better Auth's `owner`, `admin` or `member`, which decides who manages the organization: owners and admins invite, remove and change members and edit its details; only owners hand it over, delete it or make owners. App roles, the project's `roles`, decide what the app shows and allows. A user holds them **globally** (the admin plugin's `role` column, as without organizations), which applies in every organization, or **per membership** (`member.app_roles`), which applies there only. A request's role, `ctx.user.roles`, is the session's [active role](#active-role), of either kind; access rules see the organization role as `ctx.organization.role`, read from the membership on each request, absent for someone who is no member there, such as a superuser who entered it. `admin` is the superuser: global only, it holds every role. With organizations every role needs a label; `owner` and `member` cannot be app role names, and `user` stands for an account without a global role.
 
 **Who gives which role.** Someone may give or take away a member's app role only if they hold it, in that organization or globally, or hold a role whose `grants` list it (`manager` above gives `accountant` without holding it); grants do not chain, and a superuser may give any. Only a superuser changes global roles. The creator of an organization becomes its owner with every app role (`creatorAppRoles`, default `'all'`), so they can give them on; for a role added later, list it in a role owners hold, or run `protobase organizations add-app-role <role> --to owners`.
 
 **The organization in the token.** A new session starts in the organization the person last worked in, else their oldest membership. `/api/auth/token` adds `org` (the organization), `org_role` and `app_roles` (the membership's, narrowed to the active role), read when the token is issued; a removed member's token, or one carrying an app role taken away, [stops working](#when-a-token-stops-working) on its next request. The app's authenticator makes `org` the tenant and `ctx.organization.id`, and adds `app_roles` to the global roles. `POST /api/auth/organization/switch` with `{ organizationId }` moves the session; the next token names the new organization, without signing in again. Someone with a global role may switch into any organization, without being a member, and sees there what those roles allow; each such entry is an `organization.entered` [audit event](api.md#audit-events). `GET /api/auth/organization/search?query=&offset=` lists every organization for them, ordered by slug, 20 at a time with the `total`, narrowed by text in the name or slug; the Organizations page shows it as All organizations. A list across every organization stays a resource without `.tenant`, readable by the global role; a list across the organizations someone is a member of is a `.tenant` resource with `across: 'memberships'` (see [Lists across organizations](access.md#lists-across-organizations)).
 
-**Invitations.** Better Auth's `POST /api/auth/organization/invite-member` with `{ organizationId, email, role, appRoles }`; inviting again replaces the earlier invitation, and it works for `invitationDays` (default 7). The email links to `{url}/-/invitation?token=…` (`invitationUrl`), with a token signed with the app's `secret`, since members can read invitation ids; without a mailer, the answer carries the `link` to pass on. The link page shows `GET /api/auth/invitation?token=`, accepts with `POST /api/auth/invitation/accept` for someone signed in as the invited address, and makes an account with `POST /api/auth/invitation/sign-up` (`{ token, name, password? }`) for an address without one. Someone signed in sees the invitations for their own address with Better Auth's `GET /api/auth/organization/list-user-invitations`, on the organizations page, and accepts one there with `POST /api/auth/invitation/accept-own` (`{ invitationId }`). The link page and its sign-up serve [invitations to the app](#users-page) too. [Open sign-up](#open-sign-up) is not available with organizations: an invitation is the address someone vouched for.
+**Invitations.** Better Auth's `POST /api/auth/organization/invite-member` with `{ organizationId, email, role, appRoles }`; inviting again replaces the earlier invitation, and it works for `invitationDays` (default 7). The email links to `/-/invitation?token=…` on the origin the invitation was made on ([several origins](#several-origins)), or to `invitationUrl`, with a token signed with the app's `secret`, since members can read invitation ids; without a mailer, the answer carries the `link` to pass on. The link page shows `GET /api/auth/invitation?token=`, accepts with `POST /api/auth/invitation/accept` for someone signed in as the invited address, and makes an account with `POST /api/auth/invitation/sign-up` (`{ token, name, password? }`) for an address without one. Someone signed in sees the invitations for their own address with Better Auth's `GET /api/auth/organization/list-user-invitations`, on the organizations page, and accepts one there with `POST /api/auth/invitation/accept-own` (`{ invitationId }`). The link page and its sign-up serve [invitations to the app](#users-page) too. [Open sign-up](#open-sign-up) is not available with organizations: an invitation is the address someone vouched for.
 
 **Members.** Better Auth's `list-members`, `update-member-role`, `remove-member` and `leave`; `POST /api/auth/organization/set-app-roles` (`{ memberId, appRoles }`); `POST /api/auth/organization/transfer-ownership` (`{ memberId, keepAs? }`) makes a member owner and the caller an admin in one step. `GET /api/auth/organization/current` answers the organization a session works in with the caller's roles there. `GET /api/auth/organization/people` answers the members of that organization to any of its members, as `{ people: [{ id, name, image? }] }` with `id` the user id and no email addresses; anyone who is not a member of it, signed out or with a global role only, is refused.
 
@@ -795,7 +795,7 @@ url: 'https://erp-x1.protobase.net',
 auth: { origins: ['https://admin.shop.com'], passkeyDomain: 'admin.shop.com' },
 ```
 
-- A request to one of them is answered for its own host: the sign-in callbacks, the [password reset](#password-reset) link and its `redirectTo`, and a [staff sign-in](#staff-sign-in) stay there. A request to any other host is answered for the app's `url`.
+- A request to one of them is answered for its own host: the sign-in callbacks, the [password reset](#password-reset) link and its `redirectTo`, an invitation link, to the [app](#users-page) or an [organization](#organizations), unless `invitationUrl` names another page, and a [staff sign-in](#staff-sign-in) stay there. A request to any other host is answered for the app's `url`.
 - Tokens keep the app's `url` as issuer and audience, whichever origin issued them, so the API takes them on every origin.
 - Sessions are cookies of each host: a person signs in once per origin.
 - `GET /.well-known/webauthn` answers `{ "origins": [...] }` with every origin of the app, on each of them, so its [passkeys](#passkeys) work on all. `protobase serve` and `protobase dev` send that path to the server, whatever the bundle's `api` says; a host in front must too.

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

@@ -146,7 +146,7 @@ Takes [tables users added](user-tables.md) over as code. The URL comes as for [`
 - **`ui.ts`** has the definition's singular and plural label, its title field, each field's label, a long text field multiline, and the list `scaffold --ui` writes.
 - **The migration** makes each table as the catalogue has it: `create schema if not exists`, `create extension if not exists pg_trgm` when an index needs it, `create table if not exists` with the columns and constraints, and `create index if not exists` for each index, by its name. On the database the table is in it changes nothing and moves no row; on an empty one it makes the same table.
 
-Then it runs [`doctor`](#doctor) on the config. When doctor reports an error in an ejected resource, or cannot load the config, every file is put back as it was and the command fails. It refuses a name no definition the server serves has, saying why the server leaves it out, and one a resource in `config/` has, or whose table one reads, already.
+Then it runs [`doctor`](#doctor) on the config. When doctor reports an error in an ejected resource, or cannot load the config, every file is put back as it was and the command fails. It refuses a name no definition the server serves has, saying why the server leaves it out, and one a resource in `config/` has, or whose table one reads, already. It refuses a table that belongs to an [organization](user-tables.md#organizations), which `scaffold` takes over instead.
 
 ```sh
 protobase eject notes            # config/notes/data.ts, config/notes/ui.ts, db/migrations/NNN_eject_notes.sql

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

@@ -178,7 +178,7 @@ export default defineConfig(({ env }) => ({
 - **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).
+`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. With [organizations](../auth.md#organizations), each organization keeps its own tables; an API that trusts the organization tokens of an auth server elsewhere (`authenticate.organizations` without `auth.organizations`) cannot turn it on. See [User tables](../user-tables.md).
 
 ```ts
 export default defineConfig({ userTables: true })

package/skills/protobase/references/reference/config/sign-in.md

@@ -53,7 +53,7 @@ export default defineConfig({ auth: { roles: ['admin', 'sales', 'warehouse'], de
 - **Type:** `true | { create?: 'admins' | 'everyone'; creatorAppRoles?: 'all' | string[]; invitationDays?: number; membershipLimit?: number; deleteRecords?: 'refuse' | 'cascade'; invitationUrl?: string }`
 - **Default:** off: the app works as one organization
 
-Turns on organizations: people work in one at a time, records of `.tenant` resources are scoped to it, and roles are held globally or per membership. `create` is who may create one (default `admins`), `creatorAppRoles` the roles its creator holds there (default `all`), `invitationDays` how long an invitation works (default 7), `membershipLimit` the most members (default 1000), `deleteRecords` whether deleting one is refused while it has records (`refuse`, the default) or left to the foreign keys (`cascade`), and `invitationUrl` the page an invitation opens (default `<url>/-/invitation`). Its hooks are in `auth/hooks.ts`. See [Organizations](../auth.md#organizations).
+Turns on organizations: people work in one at a time, records of `.tenant` resources are scoped to it, and roles are held globally or per membership. `create` is who may create one (default `admins`), `creatorAppRoles` the roles its creator holds there (default `all`), `invitationDays` how long an invitation works (default 7), `membershipLimit` the most members (default 1000), `deleteRecords` whether deleting one is refused while it has records (`refuse`, the default) or left to the foreign keys (`cascade`), and `invitationUrl` the page an invitation opens (default `/-/invitation` on the origin the invitation was made on). Its hooks are in `auth/hooks.ts`. See [Organizations](../auth.md#organizations).
 
 ```ts
 export default defineConfig({ auth: { organizations: { create: 'everyone', invitationDays: 14 } } })

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

@@ -9,13 +9,11 @@ An app's resources usually come from its code: a resource in `config/` over a ta
 ## Tables defined in the database
 
 :::caution[Beta]
-Tables are added through the API; the admin app has no screens for them yet, and an app with organizations cannot use them.
+Tables are added through the API; the admin app has no screens for them yet.
 :::
 
 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. Every server process serves a new table within a second of it being added.
 
-<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 from the admin app yet because its screens for tables and fields are not implemented.</gap>
 
 ### The switch
@@ -26,7 +24,7 @@ User tables are off by default. Turn them on in `protobase.config.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.
+`userTables` takes only `true` or `false`. With [organizations](#organizations), each organization keeps its own tables. An API that trusts the organization tokens of an auth server elsewhere (`authenticate.organizations` without `auth.organizations`) cannot read who manages an organization, so there `dev`, `build` and `serve` stop with an error that names both settings.
 
 ### The schemas and the migration
 
@@ -34,8 +32,8 @@ The tables users add and their definitions live in two schemas of the app's data
 
 | 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, 1 when it is added, 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 |
+| `table_definitions` | `tables`, one row per table users add, with its singular and plural label, its title field, a version, 1 when it is added, its organization with organizations, and its table's name, 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, and with organizations an `organization_id` column |
 
 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.
 
@@ -56,7 +54,7 @@ A table's name and each field's name are lowercase letters, digits and `_`, star
 
 When the server starts, and whenever the definitions change, 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.
+- **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. With organizations, [its organization's owners and admins](#organizations).
 - **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.
@@ -94,7 +92,7 @@ With `userTables: true`, the API has two resources over the definitions, with th
 
 | Resource | A record | Fields |
 | --- | --- | --- |
-| `user_tables` | a table, at `/user_tables/<id>` | `name`, `singular_label`, `plural_label`, `title_field`; `id` and `version` are read-only |
+| `user_tables` | a table, at `/user_tables/<id>` | `name`, `singular_label`, `plural_label`, `title_field`; `id`, `version` and `table_name`, the name of its table and its address, are read-only |
 | `user_table_fields` | a field of a table, at `/user_table_fields/<table_id>,<name>` | `table_id`, `name`, `label`, `type` (one of the [types](#the-schemas-and-the-migration)), `position` (the order of the fields), `precision` and `scale` (a decimal's alone) |
 
 Make a table with its fields in one [batch write](api.md#batch-writes): the table, each field pointing at it, then the title field, which names a field that exists. Nothing is created unless all of it is:
@@ -111,10 +109,10 @@ POST /api/v1:batchWrite
 }
 ```
 
-The answer has the table's record, so a client links to the new table at `/notes`. Add a field later with `POST /api/v1/user_table_fields`.
+The answer has the table's record, so a client links to the new table at its `table_name`, `/notes`. Add a field later with `POST /api/v1/user_table_fields`.
 
 - **What is created.** A table is `user_tables.<name>` with its `id bigint generated always as identity` key. A field is a column of its type that may be empty and has no default, so the records already there read it as empty, with a btree index, or a `pg_trgm` one for `long_text`, whose values outgrow a btree entry; a `json` field gets none. The title field gets the `pg_trgm` index search needs. The rows, the table or column, its indexes and the version are written in one transaction: anything refused leaves none of them.
-- **What is refused.** A name outside the rules above, a word SQL reserves such as `select`, a field named `id` or `etag`, the name of a resource in code, of one Protobase adds or of a table `user_tables` already has, a field marked required, and a title that is not a text field of the table, each as a field error. A table whose name a resource in code has now, which is how a table is taken over as code, takes no new field.
+- **What is refused.** A name outside the rules above, a word SQL reserves such as `select`, a field named `id`, `etag` or `organization_id`, the name of a resource in code, of one Protobase adds or of a table `user_tables` already has, a field marked required, and a title that is not a text field of the table, each as a field error. A table whose name a resource in code has now, which is how a table is taken over as code, takes no new field.
 - **What changes later.** The labels, the title field and the fields' order. A name, a type, a decimal's precision and scale never change, and no table or field is deleted. <gap>A table or field cannot be renamed, retyped or removed because changing the columns of a table users add is not implemented.</gap>
 - **Who may.** With the project's [roles](access.md), the capabilities `user_tables.create` and `user_table_fields.create`, which only `*` or a grant that names them holds, never a wildcard such as `*.create`, like [resources that need named grants](access.md#resources-that-need-named-grants); reading and changing the labels need `.read` and `.update` the same way. Without roles, admins. Each new table is its admins' alone, as [each one served](#how-each-one-is-served) is.
 - **The rest of the app.** The process that made the change serves it before it answers, and every other process [within a second](#how-a-change-reaches-every-process). While a deploy freezes writes, a create answers as any write does then.
@@ -139,3 +137,19 @@ When a table needs more than the admin app gives it, such as a validation rule,
 Once the code serves, the table takes no new field from the admin app, and a new table cannot take its name. The resource starts as the admins' alone, as it was served; widen its access in `data.ts` as for any resource.
 
 <gap>A table cannot be taken over from the admin app or the assistant because an eject that writes to the project's repository is not implemented.</gap>
+
+## Organizations
+
+:::caution[Beta]
+A table belongs to one organization and is never shared with another. Only the organization's owners and admins reach it; access cannot be widened to its other members yet.
+:::
+
+In an app with organizations, a table someone adds belongs to their organization. Only its owners and admins, and superusers working in it, see the table and its records.
+
+- **Who makes and sees them.** The owners and admins of the organization a session works in, as its [organization role](auth.md#organizations) stands on that request, and superusers working in it. They make a table, add its fields and work with its records as [above](#adding-tables-and-fields); the project's roles and their capabilities do not widen it. Anyone else, in another organization or in none, gets not found at its address, and does not see it in `/meta`, the sidebar, search, the API document or the assistant. A member who is demoted or removed loses it on their next request. <gap>Members of an organization other than its owners and admins cannot see its tables because widening their access is not implemented.</gap>
+- **Its records.** Each table is a `.tenant` resource over its `organization_id` column, as [organizations](auth.md#organizations) describe: the server sets it on every record from the session, a request body cannot, and every query reads only the organization's own.
+- **Names.** A name is unique within an organization, so two organizations can each have a `contacts` table. Its table, and its address, is `t<id>_<name>`, such as `/t12_contacts`, with `<id>` the definition's; the labels the app shows are the ones it was given. With organizations a table's name is at most 42 bytes, and may be the name of a resource in code.
+- **Taking one over as code.** `protobase eject` refuses an organization's table, as the resource it writes would not keep its records in the organization. Declare a resource over its table instead, such as `resource('t12_contacts').table('user_tables.t12_contacts')`, and run [`protobase scaffold`](cli.md#scaffold): it adds the fields and `.tenant((r) => r.organization_id)`, so the records stay in their organization, and prints which organization's definition it took. The resource in code follows the project's access rules, not the owners-and-admins rule the definition had, so give it the `.access(...)` it needs.
+- **A table made before organizations.** One added while the app had no organizations belongs to none, and stays its superusers' alone.
+
+Every process serves the tables of every organization, so [a rebuild](#how-a-change-reaches-every-process) follows a change in any organization, and the times measured there count the tables of all organizations together.

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

@@ -49,7 +49,7 @@ 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.
+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, and an unset token bumps nothing with a warning in the run's summary that counts the repositories left unbumped. 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.