@terreno/mcp 57.2.0 → 57.4.0

package/dist/docs/versioned/next/reference/api.md

@@ -9,25 +9,35 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 - [Authentication](#authentication)
 - [Model Schema Conventions](#model-schema-conventions)
 - [Mongoose Plugins](#mongoose-plugins)
+- [Organizations](#organizations)
 - [Request Validation](#request-validation)
 - [Middleware](#middleware)
 - [Logging & Tracing](#logging--tracing)
 - [Extensibility](#extensibility)
+- [In-app notifications](#in-app-notifications)
 - [Webhooks & Notifications](#webhooks--notifications)
 - [HTTP Client](#http-client)
 - [Utilities](#utilities)
 - [Script Helpers](#script-helpers)
+- [Migrations](#migrations)
 
 ## Key exports
 
 - `TerrenoApp`, `setupServer`, `modelRouter`, `Permissions`, `OwnerQueryFilter`
+- Organizations: `Organization`, `Membership`, `OrgsApp`, `orgScopedPlugin`,
+  `orgContextMiddleware`, `getOrgContext`, `OrgQueryFilter`,
+  `Permissions.IsOrganizationMember`, `organizationSlugFromName`
+- `AuditApp`, `createAuditEventModel`, `persistRbacAuditToAuditEvent`
 - `registerMCPTool`, `getMCPRegistry`
 - `APIError`, `logger`, `asyncHandler`, `authenticateMiddleware`
 - Logging: `logger`, `createScopedLogger`, `createFeatureFlaggedLogger`, `setupLogging`, `formatLogContextSuffix`
 - Correlation: `runWithRequestContext`, `getCurrentLogContext`, `requestContextMiddleware`, `REQUEST_CONTEXT_ATTRIBUTE_NAMES`
 - `createOpenApiBuilder`
+- Seeds: `runSeeds`, `runSeedCli`, `seedBetterAuthUser`
+- Migrations: `assertMigrationsAllowed`, `runMigrations`, `runDownMigrations`, `checkMigrationFiles`, `resolveMigrationDir`, `exerciseReversibleMigrations`, `MIGRATIONS_COLLECTION` (`terreno-migrate` bin)
 - `githubUserPlugin`, `setupGitHubAuth`, `addGitHubAuthRoutes`
-- Mongoose plugins: `findExactlyOne`, `findOneOrNone`, `upsertPlugin`, `DateOnly`
+- `AuthToken`, `AUTH_TOKEN_TTL` (hashed single-use password-reset / email-verification tokens)
+- Mongoose plugins: `findExactlyOne`, `findOneOrNone`, `upsertPlugin`, `DateOnly`, `emailVerificationPlugin`
 - Validation: `configureOpenApiValidator`, `validateRequestBody`, `validateQueryParams`, `createValidator`
 - Middleware: `openApiEtagMiddleware`, `sentryAppVersionMiddleware`
 - Extensibility: `TerrenoPlugin` interface
@@ -38,6 +48,14 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 
 Two patterns for building Terreno APIs:
 
+### Deprecated: modelRouter `realtime`
+
+`modelRouter({ realtime })` (RTK cache-patching websocket events) is **deprecated** and **will be removed in Terreno 58**. Use `sync` with [`@terreno/syncdb`](syncdb.md). See [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md).
+
+`RealtimeApp` is **not** deprecated. It still hosts Socket.io, change streams, and `sync:delta`.
+
+Keep `admin.realtime` when you want admin `admin:model.changed` events.
+
 ### TerrenoApp (Recommended)
 
 Fluent API with a register pattern:
@@ -67,7 +85,88 @@ const app = new TerrenoApp({userModel: User})
 - `register(registration)` — Register `ModelRouterRegistration` or `TerrenoPlugin`
 - `addMiddleware(fn)` — Add Express middleware
 - `build()` — Build Express app without listening
-- `start()` — Build and start server
+`start()` — Build and start server. Pass `httpServer` to attach to an already-listening `http.Server` instead of binding a new port (Cloud Run: bind `PORT` before MongoDB connect).
+
+`migrations.runOnStart` defaults to **false**. When `true`, `start()` binds listen first, then runs `ensureSyncIndexes`, then wet `up`. Production still requires `ALLOW_MIGRATIONS=true` (boot counts as `--force`). Omitted `migrations` never reads `terreno_migrations`.
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  migrations: {dir: "./migrations", runOnStart: true},
+});
+```
+
+### HTTP rate limiting
+
+Opt-in. Pass `rateLimit: {}` on `TerrenoApp` to enable (omitted = off; Terreno 58 defaults on).
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined,
+});
+```
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `store` | `"memory"` | `"memory"` \| `"redis"` \| `"mongo"` |
+| `limits.authMax` | 20 / 15 min | login, signup, refresh, OTP, GitHub OAuth, Better Auth sign-in / sign-up / password reset / OAuth callback |
+| `betterAuthBasePath` | `BetterAuthApp` `config.basePath` or `/api/auth` | Prefix used to classify Better Auth credential routes |
+| `limits.apiMax` | 600 / 15 min | modelRouter and other HTTP |
+| `trustProxy` | `false` | Express `trust proxy`. Use `1` on Cloud Run. Unauthenticated key is `req.ip` |
+
+Skip: `GET /health`, `/healthz`, `/openapi.json`, `/swagger` (trailing slashes and letter case ignored). 429 is `APIError` `code: "rate-limit-exceeded"` with `Retry-After` and `RateLimit` / `RateLimit-Policy`. JWT login/signup/refresh ignore a stale access token. Operator guide: [Rate limiting](../how-to/rate-limiting.md).
+
+### MCP service tokens
+
+Opt-in. Omitted or `enabled: false` leaves `/mcp/service-tokens` unmounted and ignores `mcp_` Bearer credentials on `/mcp`.
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpServiceTokens: {
+    enabled: true,
+    publicMcpUrl: process.env.PUBLIC_API_URL,
+  },
+});
+```
+
+`mcpServiceTokens: true` is `{enabled: true}`. When enabled, TerrenoApp mounts the self-serve routes (passing its OpenAPI bundle) and sets `mcpServiceTokens` on MCP auth. Operator steps: [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md).
+
+### Audit log (`AuditApp`)
+
+Opt-in append-only log. Register the plugin; importing `@terreno/api` does **not** compile `AuditEvent` onto the default mongoose connection.
+
+```typescript
+import {
+  AuditApp,
+  persistRbacAuditToAuditEvent,
+  TerrenoApp,
+  modelRouter,
+} from "@terreno/api";
+
+new TerrenoApp({userModel: User})
+  .register(new AuditApp()) // optional {retentionDays: 90}
+  .register(
+    modelRouter("/todos", Todo, {
+      audit: true, // or {redact: ["ssn"]}
+      permissions: {/* ... */},
+    })
+  )
+  .start();
+```
+
+| Surface | How it writes |
+| --- | --- |
+| `modelRouter` | `audit: true` or `{redact?: string[]}` after successful HTTP create/update/delete and array push/update/remove |
+| `AdminApp` | Auto when `AuditApp` is registered (`source: "admin"`). `onAdminAudit` is extra |
+| RBAC | `createAccess({auditSink: persistRbacAuditToAuditEvent})` (`source: "rbac"`) |
+
+HTTP is list+read only: `GET /audit-events` with `Permissions.IsAdmin`. Empty create/update/delete permission arrays mean POST/PATCH/DELETE return **405**, including `/admin/audit-events` (`admin.adminPermissions`). Non-admin list is also **405** (`permissionMiddleware`). There is no `isDeletedPlugin`; rows are not soft-deleted.
+
+`createAuditEventModel(connection, {retentionDays?})` is the factory for tests and scripts. Never audit `AuditEvent` itself. Diffs run on the request; persist is fire-and-forget (the HTTP handler does not await Mongo). Recorder failures (including serialization) log and leave the mutation 2xx. Secret field names (`password`, `hash`, `salt`, `token`, `secret`, `refreshToken`) are stripped at every object and array depth, including compound keys such as `tokenHash`. AdminApp diffs also omit `hiddenFields` and `excludeFields`.
+
+When `GCP_TASKS_AUDIT_QUEUE`, `AUDIT_TASKS_URL`, `GCP_PROJECT`, `GCP_LOCATION`, and `AUDIT_TASKS_SECRET` are set, `AuditApp` enqueues the write with Cloud Tasks (`@google-cloud/tasks` optional install) instead of writing Mongo in-process, and mounts `POST /internal/audit-events` (header `X-Terreno-Audit-Secret`) so the worker persists. Pass `enqueue` yourself to use any other queue. Default retention is forever (no TTL index). `new AuditApp({retentionDays: n})` for `n > 0` replaces the plugin `{created: 1}` index with `{created: 1, expireAfterSeconds: n * 86400}`. Drop that index yourself if you later remove TTL. Operator steps: [Enable the framework audit log](../how-to/audit-log.md).
 
 ### setupServer (Legacy)
 
@@ -84,7 +183,45 @@ setupServer({
 });
 ``````
 
-Both patterns create the same middleware stack (CORS, auth, logging, OpenAPI).
+Both patterns create the same middleware stack (CORS, auth, logging, OpenAPI). HTTP rate limiting is a `TerrenoApp` option only — migrate from `setupServer` to `TerrenoApp` to enable it.
+
+## Collection catalog
+
+`modelRouter("/path", Model, options)` writes one catalog record per route path. MCP, realtime, and sync surfaces read that record; TerrenoApp calls `replaceCollectionOptions` once when access control is injected. Test helpers `clearMCPRegistry`, `clearRealtimeRegistry`, and `clearSyncRegistry` clear the entire catalog.
+
+## modelRouter actions
+
+Named GET/POST operations on a collection or document. Use these instead of `app.get` /
+`app.post` / `router.get` / `router.post` for application APIs.
+
+See [modelRouter actions](../explanation/model-router-actions.md). Example:
+
+```typescript
+export const todoRouter = modelRouter("/todos", Todo, {
+  collectionActions: {
+    bulkComplete: {
+      method: "POST",
+      permissions: [Permissions.IsAuthenticated],
+      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
+      handler: async ({body, user}) => {
+        return {matched: 0, modified: 0};
+      },
+    },
+  },
+  instanceActions: {
+    markComplete: {
+      method: "POST",
+      permissions: [Permissions.IsOwner],
+      handler: async ({doc}) => {
+        return doc;
+      },
+    },
+  },
+  permissions: { /* CRUD */ },
+});
+```
+
+Do not add `endpoints: (router) => { router.get(...) }` when an action fits.
 
 ## MCP tools
 
@@ -102,6 +239,34 @@ const todoRouter = modelRouter("/todos", Todo, {
 
 Cross-model tools use `registerMCPTool` (see the example backend's `users_todo_statuses`). How-to: [Expose MCP tools](../how-to/expose-mcp-tools.md). In-process Vercel AI SDK wrappers: `getMCPTools` from `@terreno/ai`.
 
+Create, update, and delete tools share REST permission, hook, and persistence semantics: they call the same `executeCreate` / `executeUpdate` / `executeDelete` pipeline. MCP error results use `APIError.title` (for example `Create not allowed`, `preCreate hook error`). User-role stripping for RBAC User writes happens in the executor after hooks; MCP supplies the registry `modelName` for that check. List and read stay MCP handlers. `excludeFields` and `mcpResponseHandler` still apply after the executor returns. Invalid ids on instance writes 404 only when the document `_id` cannot be cast, not when a populate ref fails.
+
+### MCP service token model
+
+`McpServiceToken` stores the hashed credential records used by the optional MCP service-token feature. It is not a `modelRouter` model: consumer-facing create, list, and revoke routes are registered only when `mcpServiceTokens` is enabled on `TerrenoApp`.
+
+```typescript
+import {McpServiceToken} from "@terreno/api";
+
+const {mcpServiceToken, token} = await McpServiceToken.issueFor(
+  {_id: user._id},
+  {name: "Perplexity"}
+);
+// Store or show `token` once. Only its SHA-256 hash is persisted.
+```
+
+The token begins with `mcp_` followed by 32 random bytes encoded as hex. `verify(token)` returns `null` for unknown, expired, or revoked tokens. `revokeForUser(user, tokenId)` records `revokedAt`, and `countActiveForUser(userId)` excludes expired or revoked records. Document `deleteOne` (admin DELETE) also sets `revokedAt` and leaves the row for audit. Never return or log `tokenHash` or the plaintext token outside the initial issue result.
+
+Self-serve HTTP routes live at `/mcp/service-tokens`. `TerrenoApp` mounts them when `mcpServiceTokens` is enabled, passing its OpenAPI bundle. You can also call `addMcpServiceTokenRoutes(app, {publicMcpUrl, openApi})` yourself. They require session or JWT auth and **reject** `Authorization: Bearer mcp_…` so a service token cannot mint or list tokens.
+
+| Method | Path | Body / params | Response |
+| --- | --- | --- | --- |
+| POST | `/mcp/service-tokens` | `{name, expiresAt?}` | `{data: {id, name, token, tokenPrefix, mcpUrl, expiresAt, created}}` |
+| GET | `/mcp/service-tokens` | `?page&limit` | `{data, page, limit, total, more}` — no `token` or `tokenHash` |
+| DELETE | `/mcp/service-tokens/:id` | — | `{data: {id, revokedAt}}` — owner only |
+
+`expiresAt` is an optional ISO-8601 datetime (Luxon `DateTime.fromISO`). Omit it for a token that does not expire. Create returns `mcpUrl` from `publicMcpUrl`, else `BETTER_AUTH_URL`, else the request host, with `/mcp` appended when missing. An 11th **active** token for the same user is `400`. Revoke and cross-owner access are `404`. List includes revoked rows for the owner so the UI can show history. Default page size is 100 (maximum 100).
+
 ## Authentication
 
 @terreno/api includes built-in authentication with multiple strategies:
@@ -128,9 +293,46 @@ setupServer({
 - `POST /auth/signup` — Create user account
 - `POST /auth/login` — Authenticate with email/password
 - `POST /auth/refresh_token` — Refresh access token
+- `POST /auth/forgotPassword` — Always 202; mails a reset link only when the email exists
+- `POST /auth/resetPassword` — `{token, password}`; also aliased at `POST /resetPassword` for the RTK client
+- `POST /auth/sendVerification` — Authenticated; 202 only after delivery succeeds; mails a verification link when `emailVerified` is not true
+- `POST /auth/verifyEmail` — `{token}` sets `emailVerified` true
 - `GET /auth/me` — Get current user profile
 - `PATCH /auth/me` — Update current user profile
 
+Signup and `PATCH /auth/me` drop privileged fields: `admin`, `roles`, `organizationIds`,
+`emailVerified`, and `tokenEpoch`. Request logs redact `password`, `newPassword`,
+`oldPassword`, `token`, and `refreshToken` in request bodies and in URL query strings. Changing the mailbox through `PATCH /auth/me`
+invalidates unused `passwordReset` AuthTokens for that user even when the schema has no
+`emailVerified` field. When the schema uses `emailVerificationPlugin`, mailbox change also
+sets `emailVerified` to false and invalidates unused `emailVerification` tokens; changing letter
+casing alone does not.
+
+**AuthToken (password reset / email verification):** hashed single-use tokens live in a separate
+`AuthToken` collection, not on User. `AuthToken.issueFor(user, type)` invalidates other
+unused, unexpired tokens of that type for the same user, then returns a 32-byte hex
+plaintext once and stores only the SHA-256 hash. `AuthToken.consume(token, type)` atomically
+marks one unused, unexpired row. TTL is 1 hour for `passwordReset` and 24 hours for
+`emailVerification` (`AUTH_TOKEN_TTL`). Mongo also TTL-indexes `expiresAt`.
+
+Wire `authOptions.publicAppUrl` and `authOptions.sendMail` (typically
+`getCommsService().sendMail`) so forgot-password can deliver the link
+`${publicAppUrl}/resetPassword?token=...`. Forgot-password skips issuing a token when
+`publicAppUrl` is missing. Authenticated `POST /auth/sendVerification` returns 501 in that
+case instead of 202. Email lookup is case-insensitive. Successful reset calls `setPassword`, increments
+`tokenEpoch` so outstanding **refresh** tokens fail, and returns new JWT tokens. When
+`BetterAuthApp` is registered, JWT reset also updates that user's Better Auth password
+and deletes Better Auth sessions. Better Auth password reset updates the JWT password
+and `tokenEpoch` for the matching app User. Access
+tokens stay valid until expiry (default 15m). `POST /resetPassword`
+matches the `@terreno/rtk` `resetPassword` mutation path (`password` or `newPassword`).
+
+Add `tokenEpoch` (number, default 0) on the User schema so epoch bumps persist under
+`strict: "throw"`. See `example-backend` User. Opt in to `emailVerified` with
+`emailVerificationPlugin`. Set `authOptions.requireEmailVerification` to reject login
+with 403 `email-not-verified` until `POST /auth/verifyEmail`. Signup still returns JWTs
+and sends `${publicAppUrl}/verifyEmail?token=...` so the user can complete verification.
+
 **Environment variables:**
 - `TOKEN_SECRET` — JWT signing secret (required)
 - `TOKEN_ISSUER` — JWT issuer claim (required)
@@ -197,6 +399,21 @@ app.register(new BetterAuthApp({config: betterAuthConfig, userModel: User}));
 const server = app.start();
 ``````
 
+Set `publicAppUrl`, `sendMail`, and `renderAuthMail` (from `@terreno/comms`) so Better Auth
+`sendResetPassword` / `sendVerificationEmail` use the same templates as JWT recovery mail.
+Those hooks throw 501 and do not send when `publicAppUrl` is missing, so links are never
+relative. Password reset also sets `revokeSessionsOnPasswordReset`, so existing Better Auth sessions
+are deleted when that reset path succeeds. JWT `POST /auth/resetPassword` updates the
+Better Auth password and deletes those sessions when `BetterAuthApp` is registered.
+Optional `authMailTemplates` overrides
+subject/text/html per template id.
+
+In-process seed helpers (for example `seedBetterAuthUserInProcess`) should pass
+`disableRateLimit: true` on that throwaway Better Auth instance. Better Auth
+turns its built-in limiter on when `NODE_ENV=production`, so seeding six demo
+users during a preview smoke test otherwise 429s on the fourth signup. Do not
+set this on the public `BetterAuthApp`.
+
 **Endpoints (when enabled):**
 - `POST /api/auth/signup/email` — Email/password signup
 - `POST /api/auth/signin/email` — Email/password signin
@@ -262,6 +479,20 @@ Field descriptions appear in:
 
 @terreno/api provides several Mongoose plugins to extend model functionality with common patterns.
 
+### orgScopedPlugin
+
+Adds a required indexed `organizationId` (ref `Organization`) to consumer schemas. Save fails
+without an organization. Use this on tenant-scoped models; query scoping lands with org context.
+After creation, `organizationId` is immutable — REST PATCH, admin writes, sync updates, and
+direct `doc.save()` / `updateOne()` attempts to retarget another organization return HTTP 400
+with title `organizationId cannot be changed`.
+
+``````typescript
+import {orgScopedPlugin} from "@terreno/api";
+
+projectSchema.plugin(orgScopedPlugin);
+``````
+
 ### findExactlyOne & findOneOrNone
 
 **Critical:** Never use `Model.findOne` directly. Use these plugins instead to prevent ambiguous queries.
@@ -403,6 +634,21 @@ userSchema.plugin(baseUserPlugin);
 // - admin: boolean (default: false)
 ``````
 
+### emailVerificationPlugin
+
+Opt-in `emailVerified` boolean for user schemas. Defaults to `false` so existing users stay
+unverified until they complete the verification flow. Apply this plugin; do not add the
+field by hand.
+
+``````typescript
+import {emailVerificationPlugin, type EmailVerified} from "@terreno/api";
+
+userSchema.plugin(emailVerificationPlugin);
+
+// Adds:
+// - emailVerified: boolean (default: false)
+``````
+
 ### firebaseJWTPlugin
 
 Firebase authentication integration.
@@ -434,6 +680,138 @@ export const addDefaultPlugins = (schema) => {
 todoSchema.plugin(addDefaultPlugins);
 ``````
 
+## Organizations
+
+Organizations are **opt-in**. Existing and single-tenant apps omit them: do not pass
+`organizations: true` to `createAccess` or `TerrenoApp`, and do not register `OrgsApp`.
+New apps from `create-terreno-app` enable organizations by default.
+
+| App kind | What to do |
+| --- | --- |
+| Existing / single-tenant | Leave `createAccess` and `TerrenoApp` without `organizations`. No `operator` seed, no membership grants, no `/orgs` routes. |
+| New app (bootstrap) | Generated `backend/src/access.ts` uses `createAccess({ organizations: true })`. `TerrenoApp({ organizations: true, accessControl: access })` mounts `OrgsApp`. Seed creates a default org and makes `admin@example.com` an `operator` and `org-admin`. |
+| Existing app adopting orgs | `createAccess({ organizations: true })`, `await access.roles.seedDefaults()`, and `TerrenoApp({ organizations: true, accessControl })` or `.register(new OrgsApp({ access, userModel }))`. |
+
+`Organization` and `Membership` models register on first use, not when you import `@terreno/api`.
+
+Native `Organization` and `Membership` models live in `@terreno/api`.
+
+| Model | Fields |
+| --- | --- |
+| `Organization` | `name` (required), `slug` (unique, generated from name), `ownerId`, `settings` (app-defined; Mixed until you register a nested schema), `disabled` |
+| `Membership` | `organizationId`, `userId`, `roleName` (`org-admin` \| `member`, default `member`), `status` (`active` \| `suspended`) |
+
+Compound unique index: `(organizationId, userId)`. Duplicate memberships throw a Mongo duplicate-key error.
+
+`Membership` statics: `findActiveForUser`, `isOrgAdmin`, `isMember` (active rows only). Per-org
+`org-admin` is stored on Membership, not on `user.roles`.
+
+### Organization.settings
+
+Do not add top-level fields to the native `Organization` model. Extend `settings`:
+
+| Helper | Role |
+| --- | --- |
+| `createOrganizationSettingsSchema(definition)` | Nested schema with `_id: false` and `strict: "throw"` |
+| `registerOrganizationSettings(schema)` | Validate settings on create/save/PATCH. Call with no argument to clear |
+| `organizationSettingsOf(organization)` | Type-safe read; defaults to `{}` |
+| `OrganizationSettings` | Empty interface for `declare module "@terreno/api"` merging |
+
+Pass `settingsSchema` on `TerrenoApp({ organizations: { settingsSchema } })` or `new OrgsApp({ settingsSchema })`. Keep settings fields optional or defaulted so existing documents still save. See [Add organizations](../how-to/add-organizations.md#3-type-organization-settings).
+
+### OrgsApp routes
+
+| Method | Path | Required access |
+| --- | --- | --- |
+| `POST` | `/orgs` | `organization:create` |
+| `GET` | `/orgs` | `organization:list` |
+| `GET` | `/orgs/mine` | Active org-admin membership, operator, or superadmin (disabled orgs omitted) |
+| `GET` | `/orgs/:id` | `organization:read` in that org |
+| `PATCH` | `/orgs/:id` | `organization:update`; disabling also requires `organization:disable` |
+| `DELETE` | `/orgs/:id` | `organization:delete` |
+| `GET` / `POST` | `/orgs/:id/members` | `organization:manageMembers` |
+| `PATCH` / `DELETE` | `/orgs/:id/members/:memberId` | `organization:manageMembers`; cannot remove or demote the last org-admin |
+
+Creating an organization does not create a membership automatically. Member
+attach accepts an existing `userId` or email (case-insensitive); it does not send
+an invitation. Disabling or deleting an organization suspends its memberships.
+Member attach, update, and remove routes reject disabled organizations with 403.
+Operators may still `GET` and `PATCH /orgs/:id` on a disabled organization to
+re-enable it; `GET /orgs` continues to list disabled organizations.
+
+### Request organization context
+
+Tenant-scoped routes run `orgContextMiddleware({required: true})` after auth, then
+`queryFilter: OrgQueryFilter`.
+
+| Condition | Result |
+| --- | --- |
+| `X-Organization-Id` present, organization disabled | 403 `Organization is disabled` |
+| `X-Organization-Id` present, caller is `operator`/`superadmin` or an active member, org enabled | `req.organization` set |
+| `X-Organization-Id` present, caller is not a member and not a platform org actor | 403 |
+| Tenant-scoped route, `operator`/`superadmin`, header omitted | 400 |
+| Caller is `org-admin` of exactly one enabled org, header omitted | that org is inferred |
+| Caller is `org-admin` of many orgs, header omitted | 400 |
+| Otherwise on tenant-scoped routes | 403 |
+
+`OrgQueryFilter` always ANDs `{organizationId: context.id}`. Client `organizationId` query params
+and `$or` cannot list another org.
+
+`user.admin` is not operator. Platform org actors are `user.roles` containing `operator` or
+`superadmin`.
+
+Use `Permissions.IsOrganizationMember` on read, update, and delete methods for
+tenant models. It requires the object's `organizationId` to match the active
+request organization context (AsyncLocalStorage from `orgContextMiddleware`, and
+from `X-Organization-Id` on `POST /sync/mutate`) for every caller. Platform actors (`operator` / `superadmin`) then pass; members
+must also hold an active Membership in that organization. Direct `GET` / `PATCH`
+by document id does not apply `OrgQueryFilter`, so this object-level check is
+what blocks cross-tenant reads and writes. `getOrgContext()` exposes the
+resolved organization to create hooks so they can overwrite client-provided
+organization ids. Duplicate organization names that generate the same slug,
+including slugs still held by soft-deleted organizations, return **409**
+`Organization name already in use` on `POST /orgs` and on rename
+via `PATCH /orgs/:id`. See [Add organizations](../how-to/add-organizations.md)
+for complete route wiring.
+
+### Organization RBAC
+
+`terrenoStatements.organization` actions: `create`, `list`, `read`, `update`, `delete`,
+`manageMembers`, `disable`.
+
+| Role | Where it lives | Organization grants |
+| --- | --- | --- |
+| `superadmin` | `user.roles` | `*` (includes every organization action) |
+| `operator` | seeded locked `user.roles` when `createAccess({ organizations: true })` | all `organization` actions, plus `admin:access` and `user:list\|read\|update` |
+| `org-admin` | `Membership.roleName` in the current org context | `organization:read\|update\|manageMembers` and `admin:access` |
+| `admin` | `user.roles` | none of `organization:*` |
+
+`createAccess({ organizations: true })` prepends a membership permission source (`ttlMs: 0`) and
+seeds the locked `operator` role. Without that flag, membership `org-admin` grants nothing extra
+and `operator` is not seeded. Putting `org-admin` on `user.roles` does not grant those permissions.
+Permission cache keys include the current organization id and membership role so org-admin grants
+do not leak across orgs.
+
+``````typescript
+import {createAccess, Membership, Organization, terrenoStatements} from "@terreno/api";
+
+const access = createAccess({
+  connection: mongoose.connection,
+  organizations: true,
+  statements: terrenoStatements,
+  userModel: User,
+});
+
+const org = await Organization.create({name: "Acme Corp", ownerId: user._id});
+// org.slug === "acme-corp"
+
+await Membership.create({
+  organizationId: org._id,
+  roleName: "org-admin",
+  userId: user._id,
+});
+``````
+
 ## Request Validation
 
 @terreno/api provides runtime validation of incoming requests against OpenAPI schemas using [AJV](https://ajv.js.org/). Validation is opt-in and can be enabled globally or per-route.
@@ -477,7 +855,9 @@ setupServer({
 
 ### Using with modelRouter
 
-When validation is enabled globally, modelRouter automatically validates create and update requests:
+When validation is enabled globally, modelRouter automatically validates create and update requests.
+
+Create (POST) enforces Mongoose required fields. Update (PATCH) is partial: present fields are type-checked, but omitted required fields are allowed so a client can send `{completed: true}` without repeating `title`.
 
 ``````typescript
 import {modelRouter, Permissions} from "@terreno/api";
@@ -491,6 +871,10 @@ router.use("/todos", modelRouter(Todo, {
 }));
 ``````
 
+### Builder validation
+
+Call `.withValidation()` before `.build()` so body and query checks run in the same handler that documents the route. `build()` still returns one Express `RequestHandler`, so callers can nest it in a middleware array. OpenAPI metadata stays on that handler, so the route remains in `/openapi.json`.
+
 ### Manual Validation
 
 For custom routes, use validation middleware directly:
@@ -608,6 +992,46 @@ router.post("/todos", [
 
 **Learn more:** See `api/src/openApiValidator.ts` for advanced usage and `api/src/api.ts` for modelRouter integration.
 
+## describeModel
+
+Walk a Mongoose model once and get a canonical field graph (`ModelDescription`). OpenAPI, admin config, and MCP Zod tools format that graph instead of re-walking `schema.paths`.
+
+``````typescript
+import {
+  describeModel,
+  describeModelForRouter,
+  modelDescriptionToOpenApiSpec,
+  modelDescriptionToAdminFields,
+  fieldDescriptionToZodType,
+} from "@terreno/api";
+
+const description = describeModel(Todo);
+const openApi = modelDescriptionToOpenApiSpec(description);
+const adminFields = modelDescriptionToAdminFields(description);
+``````
+
+### Field kinds
+
+| Kind | Description |
+|------|-------------|
+| `string` | String (optional `enum`) |
+| `number` | Number |
+| `boolean` | Boolean |
+| `date` | Date (OpenAPI `date-time`) |
+| `dateOnly` | Terreno DateOnly type |
+| `objectId` | ObjectId with optional `ref` |
+| `embedded` | Subdocument or array of subdocuments |
+| `mixed` | Schema.Types.Mixed |
+| `map` | Map type (`item` is the `of` kind; omitted `of` is `mixed`) |
+
+Each field includes `required`, optional `description`, `isArray`, nested `item` / `fields`, and `system` for `_id`, `__v`, `created`, `updated`, `deleted`.
+
+`describeModelForRouter(model, options)` adds `writableOnCreate` and `writableOnUpdate` using the same rules as MCP system-field exclusions and router validation / field views.
+
+`getOpenApiSpecForModel` builds HTTP body schemas from `ModelDescription`; populate merging for referenced models is unchanged.
+
+See [Schema metadata explanation](../explanation/schema-metadata.md).
+
 ## Middleware
 
 ### openApiEtagMiddleware
@@ -937,8 +1361,110 @@ setupServer({
 - Optional/configurable functionality
 - Clean separation of concerns
 
+## In-app notifications
+
+Owner-scoped inbox and channel preferences via `NotificationsApp` (`ConsentApp` pattern).
+This is separate from inbound webhooks and outbound Slack/Chat/Zoom notifiers below.
+
+### Register
+
+```typescript
+import {NotificationsApp, getNotificationService, notificationsBeforeSend} from "@terreno/api";
+
+new TerrenoApp({userModel: User}).register(
+  new NotificationsApp({
+    getComms: getCommsService, // optional; duck-typed, no @terreno/comms import in api
+    retainDays: 0,
+    userModel: User,
+  })
+);
+```
+
+### Collections
+
+| Model | Route | Sync | Client create |
+|---|---|---|---|
+| `Notification` | `/notifications` | owner | **No** (`create: []`) |
+| `NotificationPreference` | `/notification-preferences` | owner | Yes (lazy defaults) |
+
+`Notification` fields: `ownerId`, `title`, `body`, `href?`, `kind?`, `readAt?` (null = unread),
+`archivedAt?` (null = active inbox).
+Index: `{ownerId: 1, created: -1}`.
+
+`NotificationPreference` fields: `ownerId` (unique among non-deleted rows), `inapp`, `mail`,
+`push`, `sms` (default `true`). Missing preference row = all channels on. Preference updates
+accept only the four channel booleans; `ownerId` is immutable. Soft-deleting a preference
+row does not block a later create for the same owner.
+
+`notify()` comms fan-out isolates mail, SMS, and push: a rejection from one provider is
+logged and does not skip later channels.
+
+### `notify(input)`
+
+Server-only seam. Writes the inbox when `inapp` is on, then optionally calls
+`getComms().sendMail` / `sendSms` / `sendPushToUser` when that channel is on and a
+destination exists. Comms errors after the inbox write are logged and do not fail `notify()`.
+
+### HTTP
+
+| Method | Path | Notes |
+|---|---|---|
+| GET/PATCH/DELETE | `/notifications/:id` + list | Owner-scoped; **create disabled** |
+| POST | `/notifications/mark-all-read` | Sets `readAt` on caller's unread rows |
+| CRUD | `/notification-preferences` | Owner-scoped sync |
+
+PATCH on notifications: `readAt` (ISO date or `null` to unread) and `archivedAt` (ISO date
+or `null`). Other keys are stripped. Dismiss sets `archivedAt` via syncdb update so the
+row stays in the snapshot. DELETE remains a retention tombstone (`isDeletedPlugin`), not
+the inbox archive path.
+
+The example backend uses todo router lifecycle hooks to call `notify()`: create emits
+`Todo added`, the first incomplete-to-complete update emits `Todo completed`, and delete
+emits `Todo deleted`.
+
+### `notificationsBeforeSend`
+
+Duck-typed hook for `CommsApp({beforeSend})`. Cancels when the user's preference for that
+channel is `false`. Never cancels `verification`.
+
+### Retention
+
+`retainDays` default `0` (no sweep). When `retainDays > 0`, `sweepExpired()` tombstones rows
+with `created` older than N days. No Mongo TTL index.
+
+How-to: [In-app notifications](../how-to/in-app-notifications.md).
+
 ## Webhooks & Notifications
 
+JSON and `application/x-www-form-urlencoded` parsers on `TerrenoApp` copy the original
+bytes onto `req.rawBody` (`Buffer`) so inbound webhook signatures can be verified
+without re-serializing `req.body`.
+
+Register inbound routes on `WebhooksApp`. Helpers: `hmacSignature`, `stripeSignature`,
+`twilioSignature`, `sendgridEventSignature`. Timestamped HMAC, Stripe, and SendGrid
+reject timestamps outside a 300s window by default. Idempotency is `memory` or `mongo`
+(`webhookReceipts`). Paths are not added to `/openapi.json` and do not use JWT.
+
+```typescript
+import {hmacSignature, TerrenoApp, WebhooksApp} from "@terreno/api";
+
+const webhooks = new WebhooksApp({idempotency: {store: "mongo"}});
+webhooks.route({
+  path: "/webhooks/example",
+  source: "example",
+  verify: hmacSignature({secret: process.env.WEBHOOK_SECRET!, header: "X-Webhook-Signature"}),
+  eventId: (req) => String((req.body as {id?: string})?.id ?? ""),
+  handler: async () => {
+    // process event
+  },
+});
+
+new TerrenoApp({userModel: User}).register(webhooks).start();
+```
+
+Call `webhooks.claim` / `webhooks.release` from a handler when one HTTP body contains
+nested ids (SendGrid `sg_event_id`). Operator guide: [Receive inbound webhooks](../how-to/inbound-webhooks.md).
+
 ### Slack Notifications
 
 ``````typescript
@@ -1121,8 +1647,41 @@ for (let i = 0; i < 3; i++) {
 }
 ``````
 
+## Migrations
+
+`runMigrations({migrations, dryRun, connection, mongoose})` applies pending versioned `up` functions in array order. Dry-run calls `up({dryRun: true})` and does **not** write history. Wet runs insert `{id, checksum, appliedAt}` into Mongo collection `terreno_migrations`. Already-applied ids are skipped; a checksum change after apply throws `Migration checksum mismatch` (409). Apply is serialized with a lock document `_id: "_lock"` in the same collection: wait, heartbeat, steal after **10 minutes**.
+
+`runDownMigrations({migrations, dryRun, connection, mongoose, steps})` rolls back the last `steps` applied files (default 1 via the CLI). Dry-run calls `down({dryRun: true})` and leaves history in place. Wet deletes the history row after `down`. Missing `down` throws `Migration has no down` (400) and does not change history.
+
+Files are `migrations/<YYYYMMDDHHmmss>-<slug>.ts`. `checkMigrationFiles({dir})` (alias `loadMigrations`) loads them in filename order without connecting to Mongo; the exported `id` must match the filename stem. Optional `down` is allowed. Duplicate ids and invalid names fail with 400 `APIError`. A missing directory fails with 404 `Migration directory not found`. Paths on Bun's compile-time virtual FS (`$bunfs`) are remapped with `resolveMigrationDir` to `MIGRATIONS_DIR` or `<cwd>/migrations`. `exerciseReversibleMigrations({dir, connect})` applies every file on a connected database, then rolls back in reverse until a file without `down` stops the chain (that id is recorded; earlier files stay applied).
+
+`assertMigrationsAllowed({isProduction, allowEnv, force, dryRun})` gates wet apply. Dry-run is always allowed. Production wet requires `ALLOW_MIGRATIONS=true` and `--force` (or a later boot/admin Apply equivalent).
+
+`buildSchemaCatalog({models})` snapshots Mongoose paths, required/unique flags, and indexes. `diffSchemaCatalog({before, after})` marks optional fields and non-unique index adds as safe, and required fields, unique indexes, same-type rename heuristics, removed paths, and same-path type changes as unsafe (fail-closed generate stubs). Mixed diffs still throw, and keep safe index calls as comments in the stub.
+
+The `@terreno/api` bin `terreno-migrate` runs `check`, `generate`, `status`, `up`, and `down`. See [Run MongoDB migrations](../how-to/run-mongodb-migrations.md).
+
 ## Script Helpers
 
+### runSeeds and runSeedCli
+
+Define ordered `SeedStep` entries and run them in the default `sync` mode or in
+`reset` mode. The `SeedContext` provides:
+
+- `upsert(model, key, values)` — creates, updates, or reports unchanged data. Nested values ignore generated `_id`s. `Map` payloads compare as plain objects. Soft-deleted matches are restored instead of duplicated. Duplicate key matches keep the first document and remove the extras.
+- `deleteMany(model, filter?)` — reset helper with dry-run support
+- `mode`, `dryRun`, and structured `changes`
+
+`runSeedCli` adds `--dry-run`, `--reset`, repeatable `--only`, `--force`, and
+`--help`. It returns an exit code instead of terminating the process; seed CLIs
+should `process.exit` after `disconnect` so leftover Better Auth handles cannot
+keep the event loop open. Production resets require both `--force` and an
+approving `allowProductionReset` option.
+See [Seed a database](../how-to/seed-a-database.md).
+
+`seedBetterAuthUser` provisions a credential account and reconciles the
+application user model without requiring a running HTTP server.
+
 ### wrapScript
 
 Error handling wrapper for scripts and cron jobs.
@@ -1133,7 +1692,7 @@ import {wrapScript} from "@terreno/api";
 wrapScript(async () => {
   // Your script logic
   await processData();
-  console.log("Script completed successfully");
+  logger.info("Script completed successfully");
 });
 ``````
 
@@ -1170,6 +1729,13 @@ cronjob("0 * * * *", async () => {
 - `"0 0 * * *"` — Daily at midnight
 - `"0 */6 * * *"` — Every 6 hours
 
+**Process-local only:** `cronjob()` runs inside the current Node process. It does not
+persist work, retry across crashes, or share state between API and worker replicas. For
+durable queues, retries, dead-lettering, cron schedules stored in MongoDB, and admin
+visibility, use [`@terreno/jobs`](jobs.md) — see
+[Durable background jobs](../how-to/background-jobs.md). Use `wrapScript` (above) for
+one-shot CLI entrypoints, not queued work.
+
 ## Deprecations
 
 ### transformer (modelRouter option)
@@ -1227,6 +1793,7 @@ Complete reference of environment variables used by @terreno/api:
 | `PORT` | No | `3000` | HTTP server port |
 | `NODE_ENV` | No | `development` | Environment: `development`, `production`, `test` |
 | `MONGO_URI` or `MONGO_CONNECTION` | Yes | — | MongoDB connection string |
+| `ALLOW_MIGRATIONS` | No | unset | Set to `"true"` plus CLI `--force` for production wet `up`/`down` |
 | `ENABLE_SWAGGER` | No | — | Set to `"true"` to enable Swagger UI at `/docs` |
 | `WEBSOCKET_PORT` | No | `PORT + 1` | Socket.io server port (if using WebSockets) |
 
@@ -1257,8 +1824,11 @@ Complete reference of environment variables used by @terreno/api:
 | `GCP_PROJECT` | No | — | Google Cloud project ID (for Cloud Tasks, etc.) |
 | `GCP_LOCATION` | No | — | GCP region (e.g., "us-central1") |
 | `GCP_SERVICE_ACCOUNT_EMAIL` | No | — | Service account email for authentication |
-| `GCP_TASKS_NOTIFICATIONS_QUEUE` | No | — | Cloud Tasks queue name for notifications |
-| `GCP_TASK_PROCESSOR_QUEUE` | No | — | Cloud Tasks queue name for background jobs |
+| `GCP_TASKS_NOTIFICATIONS_QUEUE` | No | — | Legacy name in docs/tests only — **not** read by `@terreno/api` or `@terreno/jobs` |
+| `GCP_TASK_PROCESSOR_QUEUE` | No | — | Legacy name in docs/tests only — configure Cloud Tasks via `GcpCloudTasksRunner` options |
+| `GCP_TASKS_AUDIT_QUEUE` | No | — | Cloud Tasks queue name for off-process `AuditEvent` writes |
+| `AUDIT_TASKS_URL` | No | — | Worker URL Cloud Tasks POSTs audit writes to |
+| `AUDIT_TASKS_SECRET` | No | — | Shared secret for `X-Terreno-Audit-Secret` on the audit worker route |
 
 ### Other
 
@@ -1287,8 +1857,8 @@ SENTRY_DSN=https://...@sentry.io/...
 
 ## Learn more
 
+- [Enable the framework audit log](../how-to/audit-log.md)
 - [How to create a model](../how-to/create-a-model.md)
 - [Add GitHub OAuth](../how-to/add-github-oauth.md)
 - [Authentication architecture](../explanation/authentication.md)
-- [API package source](../../api/src/)
-- [AI assistant rules](./.cursor/rules/api/)
+- [API package source](https://github.com/flourishhealth/terreno/tree/master/api/src)