@antelopejs/interface-dms 0.10.4 → 0.13.0

package/docs/2.auth/4.users.md

@@ -1,13 +1,12 @@
 ---
 title: "Users"
-description: "The `User` table is the identity record every other part of this interface points at: the authentication decorators resolve a request to one, the token generators sign for one, and `Session` rows reference one."
+description: "The `User` table and `UserModel`, password hashing and policy, `sanitizeUser`, the account mail functions, and `announceRegistration`."
+mode: reference
 ---
 
-# Users
-
 ## Overview
 
-The `User` table is the identity record every other part of this interface points at: the authentication decorators resolve a request to one, the token generators sign for one, and `Session` rows reference one. The table, its constant and its model live on the `/db` subpath; the sanitizer and the mail entry points live on the root subpath.
+The `User` table is the identity record the rest of this interface points at. The authentication decorators resolve a request to a user, the token generators sign for one, and `Session` rows reference one. The table, its constant and its model live in `@antelopejs/interface-dms/auth/db`. The sanitizer and the mail functions live in `@antelopejs/interface-dms/auth`.
 
 ```typescript
 import { sanitizeUser } from "@antelopejs/interface-dms/auth";
@@ -18,9 +17,9 @@ import {
 } from "@antelopejs/interface-dms/auth/db";
 ```
 
-## The User Table
+## The user table
 
-`User` extends `Table.with(HashModifier)` and is registered as the `users` table under the DMS core schema, so its rows are shared across tenants and its model is retrieved without a tenant instance. `USERS_TABLE_NAME` holds the table name, `"users"`.
+`User` extends `Table.with(HashModifier)` and is registered as the `users` table in the DMS core schema. Its rows are shared across tenants, and you obtain its model without a tenant instance. `USERS_TABLE_NAME` holds the table name, `"users"`.
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
@@ -29,32 +28,45 @@ import {
 | `updatedAt` | `Date` | Set on write by the update-time decorator. Indexed. |
 | `email` | `string` | Login identifier. Indexed. |
 | `name` | `string` | Display name. |
-| `avatar` | `DefaultDataTypes.ImageValue \| null` | Profile picture as an image value (`{ key, alt? }`) in the default storage, downscaled client-side to a square of at most 100×100 pixels. |
+| `avatar` | `ImageValue \| null` | Profile picture as an image value (`{ key, alt? }`) in the default storage, downscaled in the browser to a square of at most 100 by 100 pixels. |
 | `language` | `string` | Preferred language or locale, for example `"en"` or `"fr"`. Indexed. |
-| `password` | `string \| null` | Hashed by the `HashModifier`; reads back as the hash, not the plaintext. `null` for accounts with no password. |
-| `authKey` | `string` | Per-user secret that takes part in JWT signing. Rotating it invalidates every token already issued to the user. |
+| `timeZone` | `string \| null`, optional | IANA time zone that dates and times are shown in, for example `"Europe/Brussels"`. |
+| `weekStart` | `UserWeekStart \| null`, optional | First day of the week in calendars and date pickers: `0` Sunday, `1` Monday, `6` Saturday. |
+| `timeFormat` | `UserTimeFormat \| null`, optional | Clock used for times: `"h23"` for a 24-hour clock, `"h12"` for a 12-hour clock. |
+| `dateFormat` | `UserDateFormat \| null`, optional | How full dates are written: `"numeric"` (01/10/2026) or `"text"` (1 Oct 2026). |
+| `password` | `string \| null` | Hashed by `HashModifier`. Reads back as the hash, not the plaintext. `null` for accounts with no password. |
+| `passwordChangedAt` | `Date \| null` | When the user last set the password, by a change or a recovery. `null` for an account that never changed it since the field was added. |
+| `authKey` | `string` | Per-user secret that is part of the JWT signing secret. Rotating it invalidates every token already issued to the user. |
 | `isValidated` | `boolean` | Whether the email address has been validated. Indexed. |
 | `validationToken` | `string \| null` | Current email-validation code. Indexed. |
 | `validationRequestedAt` | `Date \| null` | When the validation code was issued, for expiry and rate limiting. |
 | `forgotPasswordToken` | `string \| null` | Current password-reset code. Indexed. |
 | `forgotPasswordRequestedAt` | `Date \| null` | When the reset code was issued, for expiry and rate limiting. |
-| `owner` | `boolean` | Platform owner flag. This is what `AuthOwnerOnly` checks — see [Authentication](/docs/interfaces/auth/authentication). |
+| `owner` | `boolean` | Platform owner flag. `AuthOwnerOnly` checks it. See [Authentication](/docs/interfaces/auth/authentication). |
+| `lastActiveAt` | `Date \| null` | The last time the user made a request with a valid access token. The DMS writes it at most once a minute, so it is accurate to that interval. `null` until the first authenticated request. |
 | `twoFactorMethods` | `string[]` | Second factors enabled on the account. |
 | `twoFactorSecret` | `string \| null` | Active TOTP secret. |
-| `twoFactorPendingSecret` | `string \| null` | TOTP secret awaiting confirmation during enrolment. |
-| `twoFactorTotpLastStep` | `number \| null` | 30-second time step of the last TOTP code accepted; a code from that step or an earlier one is refused, so each code works once. Unset until one is accepted. |
+| `twoFactorPendingSecret` | `string \| null` | TOTP secret that awaits confirmation during enrollment. |
+| `twoFactorTotpLastStep` | `number \| null`, optional | The 30-second time step of the last TOTP code accepted. A code from that step or an earlier one is refused, so each code works once. Unset until a code is accepted. |
 | `twoFactorBackupCodes` | `string[]` | Remaining single-use backup codes. |
-| `twoFactorEmailCode` | `string \| null` | Hash of the current emailed second-factor code — hex SHA-256 of `JSON.stringify([userId, code])` — never the code itself. |
+| `twoFactorBackupCodesGeneratedAt` | `Date \| null` | When the current set of backup codes was generated. |
+| `twoFactorBackupCodesSavedAt` | `Date \| null` | When the user confirmed they kept the current backup codes, by download, copy or acknowledgment. `null` until then. |
+| `twoFactorEmailCode` | `string \| null` | Hash of the current emailed second-factor code, never the code itself. The hash is the hex SHA-256 of `JSON.stringify([userId, code])`. |
 | `twoFactorEmailCodeRequestedAt` | `Date \| null` | When the emailed code was issued, for expiry and rate limiting. |
 
-The indexed fields — `createdAt`, `updatedAt`, `email`, `language`, `isValidated`, `validationToken`, `forgotPasswordToken` — are the ones you can look up through `getAll` on the underlying table or `getBy` on the model, which is how `UserModel.getByEmail` works.
+`UserWeekStart`, `UserTimeFormat` and `UserDateFormat` are exported next to `User`. `ImageValue` comes from `@antelopejs/interface-dms/types`.
+
+The indexed fields are `createdAt`, `updatedAt`, `email`, `language`, `isValidated`, `validationToken` and `forgotPasswordToken`. You can look a user up by these fields through `getAll` on the underlying table or `getBy` on the model. `UserModel.getByEmail` works this way.
 
-## Store and Check a Password
+## Store and check a password
 
-`password` carries the `@Hashed` decorator, and the table composes `HashModifier`. Assign a plaintext value on write and it is hashed on the way into the database; read it back and you get the hash, not the original.
+`password` carries the `@Hashed` decorator, and the table composes `HashModifier`. Assign a plaintext value on write, and the modifier hashes it on the way into the database. Read it back, and you get the hash.
 
 ```typescript
-import type { UserModel } from "@antelopejs/interface-dms/auth/db";
+import {
+  normalizeEmail,
+  type UserModel,
+} from "@antelopejs/interface-dms/auth/db";
 import randomstring from "randomstring";
 
 const AUTH_KEY_LENGTH = 64;
@@ -69,7 +81,7 @@ export async function createUser(
     createdAt: new Date(),
     updatedAt: new Date(),
     name,
-    email: email.toLowerCase(),
+    email: normalizeEmail(email),
     password, // hashed by the modifier on insert
     authKey: randomstring.generate({ length: AUTH_KEY_LENGTH }),
     owner: false,
@@ -79,7 +91,7 @@ export async function createUser(
 }
 ```
 
-To check a candidate password, call `testHashAsync` on the loaded row. The mixin hashes the candidate with the salt and the cost in the stored hash, on the thread pool, and compares the results.
+To check a candidate password, call `testHashAsync` on the loaded row. The mixin hashes the candidate on the thread pool, with the salt and the cost that the stored hash holds, and compares the result with the stored hash.
 
 ```typescript
 import { HTTPResult } from "@antelopejs/interface-api";
@@ -92,7 +104,7 @@ export async function checkCredentials(
   email: string,
   password: string,
 ) {
-  const user = await userModel.getByEmail(email.toLowerCase());
+  const user = await userModel.getByEmail(email);
   if (!user || !(await user.testHashAsync("password", password))) {
     throw new HTTPResult(UNAUTHORIZED, "error.invalid_credentials");
   }
@@ -102,19 +114,19 @@ export async function checkCredentials(
 
 A successful sign-in through `/auth/login` also writes the password again when `isHashOutdated("password")` reports an older hash on the row.
 
-Emails are stored trimmed and lowercased. `getByEmail` normalizes its argument itself; normalize with `normalizeEmail` (exported alongside `UserModel`) before writing one.
+Emails are stored trimmed and lowercased. `getByEmail` normalizes its argument itself. Before you write an email, normalize it with `normalizeEmail`, exported next to `UserModel`.
 
-## Query Users with UserModel
+## Query users with `UserModel`
 
-`UserModel` extends `BasicDataModel(User, USERS_TABLE_NAME)`, so it has the standard `get`, `getBy`, `getAll`, `insert`, `update` and `delete` operations, plus three lookups of its own.
+`UserModel` extends `BasicDataModel(User, USERS_TABLE_NAME)`. It has the standard `get`, `getBy`, `getAll`, `insert`, `update` and `delete` operations, plus three lookups of its own.
 
 | Method | Signature | Description |
 | ------ | --------- | ----------- |
-| `getByEmail` | `(email: string) => Promise<User \| undefined>` | The user with this email, trimmed and lowercased before the lookup through the `email` index, or `undefined`. |
+| `getByEmail` | `(email: string) => Promise<User \| undefined>` | The user with this email, or `undefined`. The email is trimmed and lowercased, then looked up through the `email` index. |
 | `getOwners` | `() => Promise<User[]>` | Every user with `owner === true`. |
 | `countOwnersExcluding` | `(excludedIds: string[]) => Promise<number>` | How many owners remain once the given user ids are set aside. Pass an empty array to count all owners. |
 
-`countOwnersExcluding` exists for the last-owner check: before removing the owner flag from a set of users, count who would be left and refuse the operation if the answer is zero.
+`countOwnersExcluding` serves the last-owner check. Before you remove the owner flag from a set of users, count who would remain, and refuse the operation if the answer is zero.
 
 ```typescript
 import { HTTPResult } from "@antelopejs/interface-api";
@@ -134,9 +146,9 @@ export async function demoteOwners(userModel: UserModel, userIds: string[]) {
 }
 ```
 
-## Invalidate Every Token for a User
+## Invalidate every token for a user
 
-`authKey` takes part in the signing secret of every token issued for the user, so replacing it makes all outstanding access, refresh, two-factor and tenant-assignment tokens fail validation at once. Combine it with `SessionModel.deleteByUserId` from [Tokens and Sessions](/docs/interfaces/auth/tokens-and-sessions) to sign a user out everywhere.
+`authKey` is part of the signing secret of every token issued for the user. Replacing it makes all outstanding access, refresh, two-factor and tenant-assignment tokens fail validation at once. Combine it with `SessionModel.deleteByUserId` from [Tokens and sessions](/docs/interfaces/auth/tokens-and-sessions) to sign a user out everywhere.
 
 ```typescript
 import type {
@@ -159,17 +171,25 @@ export async function signOutEverywhere(
 }
 ```
 
-`userModel.update(user)` takes the primary key from the object; the two-argument form `update(id, partial)` updates a subset of fields instead.
+`userModel.update(user)` takes the primary key from the object. The two-argument form `update(id, partial)` updates a subset of fields.
 
-## Strip Secrets Before Responding
+## Strip secrets before responding
 
-A `User` loaded from the database carries authentication secrets. `sanitizeUser` returns a copy without them, and is what you return over HTTP.
+A `User` loaded from the database carries authentication secrets. `sanitizeUser` returns a copy without them. Return that copy over HTTP.
 
-```typescript
+```typescript fragment
 sanitizeUser(user: User): Promise<Partial<User>>
 ```
 
-It removes the account's secret material — the `authKey`, the email-validation and password-reset tokens with their timestamps, and the two-factor secret, the secret of an enrolment in progress, backup codes and email code with its timestamp — along with any additional keys the deployment lists in its authentication configuration. Because the removed set is configurable, the return type is `Partial<User>`: treat every field as possibly absent rather than assuming a fixed shape.
+It removes these fields:
+
+- `authKey`;
+- `validationToken` and `validationRequestedAt`;
+- `forgotPasswordToken` and `forgotPasswordRequestedAt`;
+- `twoFactorSecret`, `twoFactorPendingSecret`, `twoFactorTotpLastStep` and `twoFactorBackupCodes`;
+- `twoFactorEmailCode` and `twoFactorEmailCodeRequestedAt`.
+
+It also removes the keys the deployment lists in the `userSensitiveKeys` setting of its authentication configuration. A dotted key such as `profile.secret` removes a nested property. Because the removed set is configurable, the return type is `Partial<User>`. Treat every field as possibly absent.
 
 ```typescript
 import { Controller, Get } from "@antelopejs/interface-api";
@@ -187,18 +207,26 @@ export class MeController extends Controller("/api/me") {
 }
 ```
 
-## Send Account Emails
+## Send account emails
 
-Four entry points send the account emails the authentication flows depend on. Each returns a promise that resolves once the message has been accepted and rejects when the mail provider reports a failure, so decide per call site whether to await it or dispatch it in the background.
+Four functions send the account emails the authentication flows depend on. Each returns a promise that resolves once the mail provider accepts the message, and rejects when the provider reports a failure. Decide at each call site whether to await it or send it in the background.
 
 | Function | Signature | Sends |
 | -------- | --------- | ----- |
 | `send2FAEmail` | `(user: User, code: string) => Promise<void>` | The emailed second-factor code, to `user.email`. |
-| `sendEmailValidationEmail` | `(user: User) => Promise<void>` | The email-validation message, using the `validationToken` currently stored on the user. |
-| `sendEmailForgotEmail` | `(user: User) => Promise<void>` | The password-reset message, using the `forgotPasswordToken` currently stored on the user. |
-| `sendAdminInviteEmail` | `(email: string, token: string, inviteeName?: string) => Promise<void>` | An invite carrying a signup link built from `token`, to an address that has no user row yet. `inviteeName` addresses the invitee by name when the invite carried one. |
+| `sendEmailValidationEmail` | `(user: User) => Promise<void>` | The email-validation message, with the `validationToken` currently stored on the user. |
+| `sendEmailForgotEmail` | `(user: User) => Promise<void>` | The password-reset message, with the `forgotPasswordToken` currently stored on the user. |
+| `sendAdminInviteEmail` | `(email: string, token: string, inviteeName?: string, context?: AdminInviteEmailContext) => Promise<void>` | An invite with a signup link built from `token`, to an address that has no user row yet. `inviteeName` addresses the invitee by name when the invite carried one. |
+
+`AdminInviteEmailContext` has three optional fields. Without them, the invite email keeps its generic wording.
 
-`sendEmailValidationEmail` and `sendEmailForgotEmail` read the code off the user, so generate it, persist it, and only then send.
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `workspaceName` | `string` | The workspace the invitee joins. |
+| `inviterName` | `string` | Who sent the invitation. |
+| `language` | `string` | The invitee's language (`en`, `fr`, and others). English when the language is not supported. |
+
+`sendEmailValidationEmail` and `sendEmailForgotEmail` read the code from the user. Generate the code, persist it, and only then send.
 
 ```typescript
 import { sendEmailForgotEmail } from "@antelopejs/interface-dms/auth";
@@ -211,7 +239,7 @@ export async function requestPasswordReset(
   userModel: UserModel,
   email: string,
 ) {
-  const user = await userModel.getByEmail(email.toLowerCase());
+  const user = await userModel.getByEmail(email);
   if (!user) return; // answer identically whether or not the address exists
 
   user.forgotPasswordToken = randomstring.generate({
@@ -225,23 +253,23 @@ export async function requestPasswordReset(
 }
 ```
 
-`sendAdminInviteEmail` takes a bare address and a token instead of a `User`, because an invitee has no user row until they sign up. The invite record itself, its token and its expiry belong to the [Core](/docs/interfaces/core/introduction) domain, whose invite helper dispatches this mail for you.
+`sendAdminInviteEmail` takes a bare address and a token instead of a `User`, because an invitee has no user row until they sign up. The invite record, its token and its expiry belong to the [Core](/docs/interfaces/core/invites) domain, whose `inviteUserToTenant` sends this email for you.
 
-## Password Policy
+## Password policy
 
-`@antelopejs/interface-dms/auth/password` exports the policy every DMS flow applies when a password is set: at least `PASSWORD_MIN_LENGTH` (8) characters, with at least one uppercase letter, one digit and one of `@$!%*?&`, and no character outside ASCII letters, digits and those special characters. `PASSWORD_PATTERN` holds the character rules without the length.
+`@antelopejs/interface-dms/auth/password` exports the policy every DMS flow applies when a password is set. A password needs at least `PASSWORD_MIN_LENGTH` (8) characters, with at least one uppercase letter, one digit, and one of `@$!%*?&`. It may contain only ASCII letters, digits and those special characters. `PASSWORD_PATTERN` holds the character rules without the length.
 
-```typescript
+```typescript fragment
 isPasswordCompliant(password: string): boolean
 ```
 
-It is a pure function, not an interface call, so it works without the DMS loaded. Call it from any flow you own that stores a password — a public signup, for instance — before hashing it, so your module accepts exactly the passwords the DMS accepts.
+`isPasswordCompliant` is a pure function, not an interface call, so it works without the DMS loaded. Call it from any flow you own that stores a password, such as a public signup, before you hash the password. Your module then accepts exactly the passwords the DMS accepts.
 
-## Announce a Registration
+## Announce a registration
 
-`announceRegistration` runs everything that must happen once an account has really joined a tenant: the welcome notification, the collaborator notification to the platform owners, and then the `USER_REGISTERED` hook.
+`announceRegistration` runs what must happen once an account has joined a tenant. It sends the welcome notification and the collaborator notification to the platform owners, then fires the `USER_REGISTERED` hook with `tenantId`, `userId`, `email` and `name`.
 
-```typescript
+```typescript fragment
 announceRegistration(
   userModel: UserModel,
   user: User,
@@ -249,10 +277,10 @@ announceRegistration(
 ): Promise<void>
 ```
 
-Call it from any registration flow you own — a module with its own signup, a SaaS transactional flow calling it once provisioning has committed. The DMS password signup and a provider login consuming an invitation both go through it, which is what keeps notifications and automations independent of which door the account came through.
+Call it from any registration flow you own: a module with its own signup, or a SaaS transactional flow once provisioning has committed. The DMS password signup and a provider login that consumes an invitation both go through it. Notifications and automations therefore run the same way, whichever flow created the account.
 
-The hook is observational: registration is already complete when it runs, so a failing subscriber is logged rather than allowed to fail the request and strand a user whose account exists but whose retry token is gone. The same is true of the notifications — they are dispatched in the background and a failure there is logged, not propagated.
+The hook only observes. Registration is already complete when it runs, so a failing subscriber is logged and does not fail the request. Failing the request would leave a user whose account exists but whose retry token is gone. The notifications are sent in the background, and a failure there is logged, not propagated.
 
-## Next Steps
+## Next steps
 
-[External Identities](/docs/interfaces/auth/external-identities) covers binding a user to the accounts they own on a login provider.
+[External identities](/docs/interfaces/auth/external-identities) covers binding a user to the accounts they own on a login provider.

package/docs/2.auth/5.external-identities.md

@@ -1,15 +1,14 @@
 ---
-title: "External Identities"
-description: "An external identity binds an account a user owns on a login provider — GitHub, Google, whichever the deployment configures — to a `User` row, so that signing in through that provider resolves to the same account…"
+title: "External identities"
+description: "Bind the accounts a user owns on external login providers, list them, and read the `UserExternalIdentity` table and model."
+mode: reference
 ---
 
-# External Identities
-
 ## Overview
 
-An external identity binds an account a user owns on a login provider — GitHub, Google, whichever the deployment configures — to a `User` row, so that signing in through that provider resolves to the same account every time. The binding is what the provider login flow reads; the provider account id, not the email, is what identifies it.
+An external identity binds an account a user owns on a login provider, such as GitHub, Google, or any provider the deployment configures, to a `User` row. Signing in through that provider then resolves to the same account every time. The provider login flow reads the binding. The provider account id identifies it, not the email.
 
-The two functions live on the root subpath, the table and its model on `/db`.
+The two functions live in `@antelopejs/interface-dms/auth`. The table and its model live in `@antelopejs/interface-dms/auth/db`.
 
 ```typescript
 import {
@@ -24,11 +23,11 @@ import {
 } from "@antelopejs/interface-dms/auth/db";
 ```
 
-This surface is scoped to authentication. A provider connection that powers a product feature — repository access, deployments — owns its own storage and must never be derived from these rows: they say who the user is, not what the deployment may do on their behalf.
+These rows serve authentication only. A provider connection behind a product feature, such as repository access or deployments, owns its own storage and must never be derived from these rows. They say who the user is, not what the deployment may do on the user's behalf.
 
-## Bind a Provider Account
+## Bind a provider account
 
-```typescript
+```typescript fragment
 linkExternalIdentity(
   userId: string,
   identity: ExternalIdentityInput,
@@ -49,13 +48,13 @@ interface ExternalIdentityLinkResult {
 
 | Field | Description |
 | ----- | ----------- |
-| `provider` | Provider identifier, as declared in the instance's OAuth configuration. |
-| `providerAccountId` | Immutable account identifier on the provider side. Never the email: users change their provider email without changing account. |
+| `provider` | Provider identifier, as declared in the OAuth configuration of the instance. |
+| `providerAccountId` | Immutable account identifier on the provider side. Never the email, because users change their provider email without changing account. |
 | `email` | Email the provider reported, stored lowercased for support and audit only. |
 
-`wasCreated` distinguishes a first binding from a refresh, which is what a login flow needs to decide whether the user just connected a new provider or simply signed in again.
+`wasCreated` is `true` for a first binding and `false` for a refresh. A login flow reads it to tell whether the user just connected a new provider or signed in again.
 
-```typescript
+```typescript fragment
 import { linkExternalIdentity } from "@antelopejs/interface-dms/auth";
 
 const { wasCreated } = await linkExternalIdentity(user._id, {
@@ -65,25 +64,25 @@ const { wasCreated } = await linkExternalIdentity(user._id, {
 });
 ```
 
-The call is idempotent for the owning user: re-linking the same provider account only refreshes its `email` and `lastLoginAt`. Binding an account already owned by another user throws `409` with the message `error.oauth.identity_already_linked` — a provider account is a single-user credential.
+The call is idempotent for the owning user. Linking the same provider account again only refreshes its `email` and `lastLoginAt`. Binding an account that another user already owns throws `409` with the message `error.oauth.identity_already_linked`, because a provider account is a single-user credential.
 
-Uniqueness is enforced by the row's deterministic primary key rather than by a secondary index, so two concurrent bindings of the same provider account collide instead of duplicating; the loser re-reads the row and either refreshes it or gets the `409`.
+The deterministic primary key of the row enforces uniqueness, not a secondary index. Two concurrent bindings of the same provider account therefore collide instead of creating a duplicate. The call that loses reads the row again, and either refreshes it or throws the `409`.
 
-## List a User's Identities
+## List a user's identities
 
-```typescript
+```typescript fragment
 getExternalIdentities(userId: string): Promise<UserExternalIdentity[]>
 ```
 
-Returns an empty array for a user who only signs in with a password, which is how an account-settings screen decides whether to offer disconnecting a provider.
+It returns an empty array for a user who only signs in with a password. An account settings screen reads it to decide whether to offer disconnecting a provider.
 
-## The `UserExternalIdentity` Table
+## The `UserExternalIdentity` table
 
-Table `user_external_identities` in the DMS core schema, so its rows are shared across tenants like `users`. `USER_EXTERNAL_IDENTITIES_TABLE_NAME` holds the name.
+Table `user_external_identities` in the DMS core schema. Like `users`, its rows are shared across tenants. `USER_EXTERNAL_IDENTITIES_TABLE_NAME` holds the name.
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `_id` | `string` | `<provider>:<providerAccountId>`. Being the primary key is what makes the binding unique. |
+| `_id` | `string` | `<provider>:<providerAccountId>`. As the primary key, it makes the binding unique. |
 | `userId` | `string` | Owning user. Indexed, related to `User`. |
 | `provider` | `string` | Provider identifier. |
 | `providerAccountId` | `string` | Account identifier on the provider side. |
@@ -91,7 +90,7 @@ Table `user_external_identities` in the DMS core schema, so its rows are shared
 | `createdAt` | `Date` | Set on insert. Indexed. |
 | `lastLoginAt` | `Date` | Refreshed on every successful login through this identity. |
 
-`buildExternalIdentityId(provider, providerAccountId)` composes the id. Use it rather than formatting the string yourself, so a lookup by id keeps matching what `linkExternalIdentity` writes.
+`buildExternalIdentityId(provider, providerAccountId)` composes the id. Use it instead of formatting the string yourself, so a lookup by id keeps matching what `linkExternalIdentity` writes.
 
 ## `UserExternalIdentityModel`
 
@@ -101,11 +100,11 @@ Table `user_external_identities` in the DMS core schema, so its rows are shared
 | ------ | --------- | ----------- |
 | `getByProviderAccount` | `(provider: string, providerAccountId: string) => Promise<UserExternalIdentity \| undefined>` | The identity a provider account is bound to, or `undefined` when the account is unknown. |
 | `getByUserId` | `(userId: string) => Promise<UserExternalIdentity[]>` | Every identity bound to a user, read through the `userId` index. |
-| `deleteByUserId` | `(userId: string) => Promise<void>` | Drop every identity of a user. |
+| `deleteByUserId` | `(userId: string) => Promise<void>` | Deletes every identity of a user. |
 
-`getByProviderAccount` is the login-side lookup: resolve the provider profile to an identity, and its `userId` to the account to sign in.
+`getByProviderAccount` is the lookup on the login side. Resolve the provider profile to an identity, then its `userId` to the account to sign in.
 
-```typescript
+```typescript fragment
 import { GetModel } from "@antelopejs/interface-database-decorators";
 import {
   UserExternalIdentityModel,
@@ -119,4 +118,4 @@ const user = identity
   : undefined;
 ```
 
-An unknown provider account means no account exists for it yet — hand the flow to signup or to invite redemption rather than creating one implicitly. `deleteByUserId` belongs to account deletion: leaving identities behind would let a recycled provider account resolve to a user row that is gone.
+An unknown provider account means no account exists for it yet. Hand the flow to signup or to invite redemption, and do not create an account implicitly. `deleteByUserId` belongs to account deletion. Identities left behind would let a recycled provider account resolve to a user row that no longer exists.

package/docs/3.base/1.introduction.md

@@ -1,52 +1,51 @@
 ---
 title: "Introduction"
 description: "The base domain is the component vocabulary of the DMS: forms, tables, charts and cards, layout containers, data types and shared prop types."
+mode: explanation
 ---
 
-# Introduction
-
 ## Overview
 
 The `base` domain of `@antelopejs/interface-dms` is the component vocabulary of the DMS: forms, tables, charts and cards, layout containers, trees, the data types behind every field, and the shared prop types they all draw from.
 
-Every component here is a builder. `Form({...})`, `TableView(controller, {...})` and `ChartLine({...})` do not render anything — they return a `ComponentBuilder` from `@antelopejs/interface-dms/component`, which is a serializable description of a component: its name, its options, and its children. You assign that description to a static field of a page class, and the frontend reads the page's tree and draws it. The options you set are therefore data, and the components that need data are given a `fetchUrl` and a `submitUrl` pointing back at routes you declare on the same page or on a data controller.
+Every component here is a builder. `Form({...})`, `TableView(controller, {...})` and `ChartLine({...})` do not render anything. They return a `ComponentBuilder` from `@antelopejs/interface-dms/component`, which is a serializable description of a component: its name, its options, and its children. You assign that description to a static field of a page class, and the frontend reads the page's tree and draws it. The options you set are therefore data, and the components that need data are given a `fetchUrl` and a `submitUrl` pointing back at routes you declare on the same page or on a data controller.
 
-Two consequences shape the whole domain. First, a component's contract is its props interface: what you can express is exactly what the props allow, which is why this reference documents them field by field. Second, anything the frontend must receive has to survive serialization, so a builder that accepts a nested `Component` — a modal target, a kanban card, a chart inside a card — stores its serialized form instead.
+Two consequences shape the whole domain. First, a component's contract is its props interface: what you can express is exactly what the props allow, which is why this reference documents them field by field. Second, anything the frontend must receive has to survive serialization, so a builder that accepts a nested `Component`, such as a modal target, a kanban card or a chart inside a card, stores its serialized form instead.
 
 The DMS documentation carries task-shaped chapters on the same components, organised around what you are building. This folder is the contract behind them: the exact symbol names, option fields and return types.
 
-### Subpath Map
+### Subpath map
 
 `@antelopejs/interface-dms/base` is the barrel over the modules below, and re-exports most of them. The ones marked as not in the barrel are imported from their own subpath. Every row is a subpath of `@antelopejs/interface-dms/base`.
 
 | Subpath | Holds | In the root barrel | Documented in |
 | --- | --- | --- | --- |
-| `types` | Base props, colours, tones (`TONES`, `Tone`, `ICON_TONES`, `IconTone`), sizes, buttons, action targets, row-action rules, guards, watch actions, enums | yes | [Shared Types](/docs/interfaces/base/types) |
+| `types` | Base props, colours, tones (`TONES`, `Tone`, `ICON_TONES`, `IconTone`), sizes, buttons, action targets, row-action rules, guards, watch actions, enums | yes | [Shared types](/docs/interfaces/base/types) |
 | `form` | `Form`, the field and group shapes, `FormComponents`, `FormEvents`, the schema helpers | yes | [Forms](/docs/interfaces/base/forms) |
 | `table-view` | `TableView`, `@Column`, `TableViewRoutes`, guards, row actions | yes | [Tables](/docs/interfaces/base/tables) |
-| `chart` | Chart builders, series and point shapes, chart props | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
-| `chart-card` | `ChartCard` | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
-| `kpi-card` | `KpiCard` | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
-| `top-list-card` | `TopListCard` | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
-| `period-selector` | `PeriodSelector` | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
-| `live-toggle` | `LiveToggle` | yes | [Display Blocks](/docs/interfaces/base/display-blocks#live-toggle) |
-| `page-toolbar` | `PageToolbar`, `pageToolbar` | yes | [Display Blocks](/docs/interfaces/base/display-blocks#page-toolbar) |
-| `grid` | `Grid`, `GridRow` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
-| `stack` | `HStack`, `VStack`, `Spacer` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
-| `tab` | `Tab` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
-| `guard` | `Guard` | yes | [Layout and Containers](/docs/interfaces/base/layout#guard) |
-| `layouts` | `DefaultLayout`, `FormPageLayout`, `SettingsLayout`, `EmptyLayout` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
-| `placeholder` | `Placeholder` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
-| `display` | `BlockLinkAction`, `BlockItemsSource`, `BlockEmptyText` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
-| `stat-group` | `StatGroup` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
-| `key-value-list` | `KeyValueList` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
-| `nav-card-grid` | `NavCardGrid` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
-| `empty-state` | `EmptyState` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
-| `banner` | `Banner` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
-| `card` | `Card` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
-| `code-block` | `CodeBlock` | yes | [Display Blocks](/docs/interfaces/base/display-blocks) |
-| `custom` | `CustomComponent` | no | [Layout and Containers](/docs/interfaces/base/layout) |
-| `data-types` | `DataType`, the registration decorators, `DefaultDataTypes`, `DefaultDataCompareTypes`, `StatusType` | no | [Data Types](/docs/interfaces/base/data-types) |
+| `chart` | Chart builders, series and point shapes, chart props | yes | [Charts and widgets](/docs/interfaces/base/charts-and-widgets) |
+| `chart-card` | `ChartCard` | yes | [Charts and widgets](/docs/interfaces/base/charts-and-widgets) |
+| `kpi-card` | `KpiCard` | yes | [Charts and widgets](/docs/interfaces/base/charts-and-widgets) |
+| `top-list-card` | `TopListCard` | yes | [Charts and widgets](/docs/interfaces/base/charts-and-widgets) |
+| `period-selector` | `PeriodSelector` | yes | [Charts and widgets](/docs/interfaces/base/charts-and-widgets) |
+| `live-toggle` | `LiveToggle` | yes | [Display blocks](/docs/interfaces/base/display-blocks#live-toggle) |
+| `page-toolbar` | `PageToolbar`, `pageToolbar` | yes | [Display blocks](/docs/interfaces/base/display-blocks#page-toolbar) |
+| `grid` | `Grid`, `GridRow` | yes | [Layout and containers](/docs/interfaces/base/layout) |
+| `stack` | `HStack`, `VStack`, `Spacer` | yes | [Layout and containers](/docs/interfaces/base/layout) |
+| `tab` | `Tab` | yes | [Layout and containers](/docs/interfaces/base/layout) |
+| `guard` | `Guard` | yes | [Layout and containers](/docs/interfaces/base/layout#guard) |
+| `layouts` | `DefaultLayout`, `FormPageLayout`, `SettingsLayout`, `EmptyLayout` | yes | [Layout and containers](/docs/interfaces/base/layout) |
+| `placeholder` | `Placeholder` | yes | [Layout and containers](/docs/interfaces/base/layout) |
+| `display` | `BlockLinkAction`, `BlockItemsSource`, `BlockEmptyText` | yes | [Display blocks](/docs/interfaces/base/display-blocks) |
+| `stat-group` | `StatGroup` | yes | [Display blocks](/docs/interfaces/base/display-blocks) |
+| `key-value-list` | `KeyValueList` | yes | [Display blocks](/docs/interfaces/base/display-blocks) |
+| `nav-card-grid` | `NavCardGrid` | yes | [Display blocks](/docs/interfaces/base/display-blocks) |
+| `empty-state` | `EmptyState` | yes | [Display blocks](/docs/interfaces/base/display-blocks) |
+| `banner` | `Banner` | yes | [Display blocks](/docs/interfaces/base/display-blocks) |
+| `card` | `Card` | yes | [Display blocks](/docs/interfaces/base/display-blocks) |
+| `code-block` | `CodeBlock` | yes | [Display blocks](/docs/interfaces/base/display-blocks) |
+| `custom` | `CustomComponent` | no | [Layout and containers](/docs/interfaces/base/layout) |
+| `data-types` | `DataType`, the registration decorators, `DefaultDataTypes`, `DefaultDataCompareTypes`, `StatusType` | no | [Data types](/docs/interfaces/base/data-types) |
 | `searchable` | `Searchable`, `SearchableMeta` | yes | [Helpers](/docs/interfaces/base/helpers) |
 | `export-jobs` | `runExportJob` and the export-job lifecycle | yes | [Helpers](/docs/interfaces/base/helpers) |
 | `tenant-export-archive` | `startTenantExportJob`, `buildTenantExportArchive` | yes | [Helpers](/docs/interfaces/base/helpers) |
@@ -55,33 +54,33 @@ The DMS documentation carries task-shaped chapters on the same components, organ
 
 Within `types`, four modules are outside that subpath's barrel and are imported from `types/action-target`, `types/row-action`, `types/row-action-operators` and `types/guards`; the guard types and `RowActionRule` are also re-exported by `table-view`.
 
-## Key Features
+## What the package provides
 
-- **Builders that produce data** — Every component function returns a `ComponentBuilder`, so a page's UI is a plain value you can factor, reuse and compose with `.child()`.
-- **Forms from typed fields** — A field names a `DataType`, and the type supplies both the input component and the Zod schema; `Form` compiles the field list into one schema and ships its JSON Schema form with the component.
-- **Tables from data controllers** — `TableView` reads a controller's data-api metadata and its `@Column` declarations to build the columns, the `new` / `edit` / `view` forms, and the permission-carrying actions in one call.
-- **Server-enforced row rules and guards** — Row-action rules are a small algebra evaluated on both sides, and guards run inside the mutating routes, so what the row menu offers is what the server accepts.
-- **A chart and widget set with a shared period scope** — Thirteen chart types plus KPI, chart and top-list cards; one `PeriodSelector` id ties them to the same range and comparison.
-- **Layout without a frontend build** — Grids, stacks, tabs and page layouts arrange components, and `CustomComponent` names a Vue component when the vocabulary runs out.
-- **An extensible data-type registry** — `@RegisterDataType` and `@RegisterDataCompareMode` add your own types and filter operators to the catalogue the forms, columns and filters draw from.
-- **Shared prop vocabulary** — Colours, sizes, HTTP methods, action targets, readonly behaviour and watch actions are declared once in `types` and reused by every component.
+- **Builders that produce data.** Every component function returns a `ComponentBuilder`, so a page's UI is a plain value you can factor, reuse and compose with `.child()`.
+- **Forms from typed fields.** A field names a `DataType`, and the type supplies both the input component and the Zod schema; `Form` compiles the field list into one schema and ships its JSON Schema form with the component.
+- **Tables from data controllers.** `TableView` reads a controller's data-api metadata and its `@Column` declarations to build the columns, the `new` / `edit` / `view` forms, and the permission-carrying actions in one call.
+- **Server-enforced row rules and guards.** Row-action rules are a small algebra evaluated on both sides, and guards run inside the mutating routes, so what the row menu offers is what the server accepts.
+- **A chart and widget set with a shared period scope.** Thirteen chart types plus KPI, chart and top-list cards; one `PeriodSelector` id ties them to the same range and comparison.
+- **Layout without a frontend build.** Grids, stacks, tabs and page layouts arrange components, and `CustomComponent` names a Vue component when the vocabulary runs out.
+- **An extensible data-type registry.** `@RegisterDataType` and `@RegisterDataCompareMode` add your own types and filter operators to the catalogue the forms, columns and filters draw from.
+- **Shared prop vocabulary.** Colors, sizes, HTTP methods, action targets, readonly behaviour and watch actions are declared once in `types` and reused by every component.
 
 ## Dependencies
 
 This interface relies on the following AntelopeJS packages:
 
-- [@antelopejs/interface-api](https://github.com/AntelopeJS/interface-api) - Request context, controller metadata and route parameters.
-- [@antelopejs/interface-api-util](https://github.com/AntelopeJS/interface-api-util) - `assert` for failing a route with an HTTP status.
-- [@antelopejs/interface-core](https://github.com/AntelopeJS/interface-core) - Metadata storage, decorator factories, interface functions and logging.
-- [@antelopejs/interface-data-api](https://github.com/AntelopeJS/interface-data-api) - Data controllers, default routes, list parameters and field metadata.
-- [@antelopejs/interface-database](https://github.com/AntelopeJS/interface-database) - The value proxies compare modes build their filters from.
-- [@antelopejs/interface-database-decorators](https://github.com/AntelopeJS/interface-database-decorators) - Models and the localization modifier.
-- [@antelopejs/interface-file-storage](https://github.com/AntelopeJS/interface-file-storage) - Upload constraints, staged-key promotion and file deletion behind the file and image types.
-- [zod](https://www.npmjs.com/package/zod) and [zod-to-json-schema](https://www.npmjs.com/package/zod-to-json-schema) - Field validation schemas and their JSON Schema form.
+- [`@antelopejs/interface-api`](https://github.com/AntelopeJS/interface-api): Request context, controller metadata and route parameters.
+- [`@antelopejs/interface-api-util`](https://github.com/AntelopeJS/interface-api-util): `assert` for failing a route with an HTTP status.
+- [`@antelopejs/interface-core`](https://github.com/AntelopeJS/interface-core): Metadata storage, decorator factories, interface functions and logging.
+- [`@antelopejs/interface-data-api`](https://github.com/AntelopeJS/interface-data-api): Data controllers, default routes, list parameters and field metadata.
+- [`@antelopejs/interface-database`](https://github.com/AntelopeJS/interface-database): The value proxies compare modes build their filters from.
+- [`@antelopejs/interface-database-decorators`](https://github.com/AntelopeJS/interface-database-decorators): Models and the localization modifier.
+- [`@antelopejs/interface-file-storage`](https://github.com/AntelopeJS/interface-file-storage): Upload constraints, staged-key promotion and file deletion behind the file and image types.
+- [`zod`](https://www.npmjs.com/package/zod) and [`zod-to-json-schema`](https://www.npmjs.com/package/zod-to-json-schema) - Field validation schemas and their JSON Schema form.
 
 It also builds on other domains of the same package: `/component` for `Component` and `ComponentBuilder`, `/page` for the page a component is registered on, `/permissions` for the action permissions a table view declares, and `/auth` for the authenticated user its routes receive.
 
-## Quick Start
+## A first page
 
 A page declaring one component. The `Form` builder describes the fields; the two routes on the same class serve and accept the values. Define the backing model first; `SettingsModel` is application code, not a DMS export.
 
@@ -108,7 +107,7 @@ export class SettingsModel extends BasicDataModel(Settings, "settings") {}
 
 The page edits one module-wide record, so restrict it to platform owners. It returns defaults before the first save and upserts only `SETTINGS_ROW_ID`, rather than updating every row in the table.
 
-```typescript [settings-page.ts]
+```typescript fragment [settings-page.ts]
 import { Get, JSONBody, Post } from "@antelopejs/interface-api";
 import { assert } from "@antelopejs/interface-api-util";
 import { GetModel } from "@antelopejs/interface-database-decorators";
@@ -180,7 +179,7 @@ export class SettingsPage extends PageController(
 
 Import the page and provision the schema from your module's entry file. Merge this into an existing `start()` if your module already has one:
 
-```typescript [index.ts]
+```typescript fragment [index.ts]
 import "./settings-page";
 import { RegisterSchema } from "@antelopejs/interface-database-decorators";
 import { SETTINGS_SCHEMA } from "./db";
@@ -190,14 +189,19 @@ export async function start(): Promise<void> {
 }
 ```
 
-The page registers itself at import time, and its routes are mounted under the page's slug — which is why the form fetches from and submits to `/settings/`. `Form` serializes the field descriptions and JSON Schema for the frontend; the custom write route must still validate the request on the server, as the `formSchema` call does here. For per-tenant settings, use a tenant-scoped schema and model instead of this module-wide record.
-
-## Documentation Sections
-
-- [Shared Types](/docs/interfaces/base/types) - Base props, colours, sizes, action targets, row-action rules, guards and the small enums.
-- [Forms](/docs/interfaces/base/forms) - The `Form` builder, fields and groups, input components and the validation schema.
-- [Tables](/docs/interfaces/base/tables) - Table views over a data controller: columns, routes, row actions, guards, displays and generated forms.
-- [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) - Chart types and props, chart cards, KPI cards, top lists and the period selector.
-- [Layout and Containers](/docs/interfaces/base/layout) - Grids, stacks, tabs, the guard, page layouts, the placeholder and the custom-component escape hatch.
-- [Data Types](/docs/interfaces/base/data-types) - The `DataType` contract, the registries, the default catalogue and a custom type.
-- [Helpers](/docs/interfaces/base/helpers) - Searchable columns, export jobs, file references and the archive-mode defaults.
+The page registers itself at import time, and its routes are mounted under the page's slug, so the form fetches from and submits to `/settings/`. `Form` serializes the field descriptions and JSON Schema for the frontend; the custom write route must still validate the request on the server, as the `formSchema` call does here. For per-tenant settings, use a tenant-scoped schema and model instead of this module-wide record.
+
+## Pages in this section
+
+- [Shared types](/docs/interfaces/base/types): Base props, colours, sizes, action targets, row-action rules, guards and the small enums.
+- [Forms](/docs/interfaces/base/forms): The `Form` builder, fields and groups, input components and the validation schema.
+- [Tables](/docs/interfaces/base/tables): Table views over a data controller: the controller, its routes, columns and table view options.
+- [Table sources and tenant gates](/docs/interfaces/base/table-sources-and-gates): Table views over a module's route, and behind a tenant gate.
+- [Table row actions](/docs/interfaces/base/table-row-actions): Row actions, archive mode and guards.
+- [Table filters and forms](/docs/interfaces/base/table-filters-and-forms): Filters, tabs, displays and generated forms.
+- [Table events and helpers](/docs/interfaces/base/table-events-and-helpers): Exports, realtime, metadata, route helpers and events.
+- [Charts and widgets](/docs/interfaces/base/charts-and-widgets): Chart types and props, chart cards, KPI cards, top lists and the period selector.
+- [Layout and containers](/docs/interfaces/base/layout): Grids, stacks, tabs, the guard, the placeholder and `CustomComponent`.
+- [Page layouts](/docs/interfaces/base/page-layouts): The layouts a page renders in, its header actions, and pages that fill the panel.
+- [Data types](/docs/interfaces/base/data-types): The `DataType` contract, the registries, the default catalogue and a custom type.
+- [Helpers](/docs/interfaces/base/helpers): Searchable columns, export jobs, file references and the archive-mode defaults.