@terreno/mcp 57.3.0 → 57.4.0

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

@@ -9,24 +9,32 @@ 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`
 - `AuthToken`, `AUTH_TOKEN_TTL` (hashed single-use password-reset / email-verification tokens)
 - Mongoose plugins: `findExactlyOne`, `findOneOrNone`, `upsertPlugin`, `DateOnly`, `emailVerificationPlugin`
@@ -77,7 +85,16 @@ 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
 
@@ -116,6 +133,41 @@ new TerrenoApp({
 
 `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)
 
 Callback-based pattern:
@@ -137,6 +189,40 @@ Both patterns create the same middleware stack (CORS, auth, logging, OpenAPI). H
 
 `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
 
 Opt a model into Model Context Protocol tools with `mcp` on `modelRouter`. `TerrenoApp` mounts `POST /mcp` when any model has `mcp` or a custom tool is registered.
@@ -322,6 +408,12 @@ Better Auth password and deletes those sessions when `BetterAuthApp` is register
 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
@@ -387,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.
@@ -574,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.
@@ -617,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";
@@ -1121,6 +1361,79 @@ 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
@@ -1334,6 +1647,20 @@ 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
@@ -1402,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)
@@ -1459,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) |
 
@@ -1489,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
 
@@ -1519,6 +1857,7 @@ 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)

package/src/docs/versioned/next/reference/comms.md

@@ -70,6 +70,39 @@ A throwing `beforeSend` is logged and treated as no-op (send continues). Adapter
 call `recordDeliveryEvent()` / `recordOptOut()` to update the log and fire
 `onDeliveryEvent` / `onOptOut`.
 
+### Notification preferences hook
+
+When you register `NotificationsApp`, compose `notificationsBeforeSend` from `@terreno/api`
+into `CommsApp({beforeSend})` so outbound mail, SMS, and push respect per-user channel
+toggles. Missing `NotificationPreference` rows default to all channels on. The
+`verification` channel is never cancelled by this hook.
+
+```typescript
+import {notificationsBeforeSend} from "@terreno/api";
+
+new CommsApp({
+  beforeSend: async (context) => {
+    const pref = await notificationsBeforeSend({
+      channel: context.channel,
+      userId: context.userId,
+    });
+    if (pref?.cancel) {
+      return {cancel: true};
+    }
+    return existingBeforeSend?.(context);
+  },
+});
+```
+
+`getNotificationService().notify()` fans out to comms independently. Register this hook and
+pass `{userId}` as the second argument to direct `sendMail` / `sendSms` calls so they honor
+preferences; `sendPushToUser` already supplies its user id.
+
+```typescript
+await getCommsService().sendMail(message, {userId});
+await getCommsService().sendSms(message, {userId});
+```
+
 Each send stores one `CommsMessage` row with `attempts[]`. Rendered payloads are retained
 for `retainPayloadDays` (default 30, `0` disables) after `redactPayload`. Mail payloads
 keep `to`, `from`, `subject`, `text`, `html`, `replyTo`, `templateId`, and

package/src/docs/versioned/next/reference/create-terreno-app.md

@@ -0,0 +1,44 @@
+# create-terreno-app
+
+Unscoped npm CLI that writes a deployable Terreno backend + Expo frontend to disk.
+
+Operator walkthrough (Mongo replica set, seed, SDK, web, deploy): [Create a Terreno app](../how-to/create-a-terreno-app.md). First-run tutorial: [Getting started](../tutorials/getting-started.md).
+
+## Install
+
+```bash
+bunx create-terreno-app my-app --display-name "My App"
+```
+
+npm (note the `--` before flags):
+
+```bash
+npm create terreno-app my-app -- --display-name "My App"
+```
+
+The published package name is `create-terreno-app`. Generated `@terreno/*`
+dependencies pin `^<create-terreno-app version>`.
+
+## CLI
+
+```bash
+bunx create-terreno-app <appName> --display-name <string> [--description <string>] [--mcp-server-url <url>] [--yes]
+```
+
+| Flag | Required | Default |
+| --- | --- | --- |
+| `appName` (positional) | yes | kebab-case (`^[a-z][a-z0-9-]*$`) |
+| `--display-name` | unless `--yes` | derived from `appName` when `--yes` |
+| `--description` | no | empty |
+| `--mcp-server-url` | no | hosted Terreno MCP URL |
+| `--yes` | no | off |
+
+Writes `<cwd>/<appName>/`. Refuses a non-empty target except `.git` / `.gitignore`. Does not run `bun install`, Mongo, or seed.
+
+Printed next steps install, seed, then start the backend. SDK and web run in a second terminal while the backend is up.
+
+The generated Profile tab uses `@terreno/ui` `TapToEdit` with `PATCH /auth/me`. Fonts come from `@terreno/ui`. `app.json` leaves icon/splash/favicon unset. `metro.config.js` pins `jspdf` so Metro can bundle admin PDF export. `tsconfig.json` has no `baseUrl` (TypeScript 6). Auth routes use `<Stack.Protected>`.
+
+## Library
+
+`generateAllFiles` returns the file list; `writeScaffold` writes it to disk. The CLI is the only supported way to scaffold an app. MCP `terreno_bootstrap_ai_rules` can add editor rules after the CLI runs.

package/src/docs/versioned/next/reference/environment-variables.md

@@ -69,6 +69,8 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `FRONTEND_URL` | example-backend CORS and `authOptions.publicAppUrl` | ❌ | `http://localhost:8082` | No | server |
 | `API_URL` | microservice split | ❌ | — | No | server |
 | `DISABLE_LOG_ALL_REQUESTS` | `@terreno/api` logging | ❌ | — | No | server |
+| `ALLOW_MIGRATIONS` | `@terreno/api` `terreno-migrate` | ❌ | unset | No | server |
+| `MIGRATIONS_DIR` | example-backend Dockerfile / `resolveMigrationDir` | ❌ | `<cwd>/migrations` when `dir` is `$bunfs` | No | server |
 
 ## Client / build-time
 
@@ -237,6 +239,24 @@ secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
 | `TERRENO_MCP_EVAL` | MCP eval | ❌ | — | No | tooling |
 | `TERRENO_PROJECT_ROOT` | MCP local | ❌ | — | No | tooling |
 
+## Background jobs
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `JOBS_START_WORKER` | example-backend (`jobsStartWorker.ts`) | ❌ | `true` (unset) | No | server |
+
+`@terreno/jobs` itself does **not** read environment variables — pass `JobsApp` and runner
+options explicitly. `JOBS_START_WORKER` only gates whether the example API process calls
+`jobsApp.startWorker()` after listen. Set `false` when running the standalone
+`bun run jobs:worker` process against the same MongoDB.
+
+`JOB_TRACE_LOGS` is an optional app convention for verbose worker logging (see
+[API logging & tracing](api.md#logging--tracing)); not read by the jobs package.
+
+Legacy names `GCP_TASKS_NOTIFICATIONS_QUEUE` and `GCP_TASK_PROCESSOR_QUEUE` appear in
+example-backend **test** setup only. They are not read by `@terreno/jobs`. Use
+`GcpCloudTasksRunner` constructor config instead. See [Jobs reference](jobs.md).
+
 ## Example backend (app-specific)
 
 | Variable | Read by | Required | Default | Secret | Scope |
@@ -244,6 +264,14 @@ secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
 | `OTEL_SERVICE_NAME` | OpenTelemetry (example-backend) | ❌ | `example-backend` | No | server |
 | `PR_NUMBER` | PR preview deploy | ❌ | — | No | server |
 | `PR_SERVICE_URL` | PR preview deploy | ❌ | — | No | server |
+| `JOBS_RUNNER` | example-backend | ❌ | `mongo` | No | server |
+| `JOBS_START_WORKER` | example-backend | ❌ | `true` with Mongo | No | server |
+| `GCP_TASKS_PROJECT` | example-backend Cloud Tasks runner | ✅ when `JOBS_RUNNER=gcp-cloud-tasks` | — | No | server |
+| `GCP_TASKS_LOCATION` | example-backend Cloud Tasks runner | ✅ when `JOBS_RUNNER=gcp-cloud-tasks` | — | No | server |
+| `GCP_TASKS_QUEUE` | example-backend Cloud Tasks runner | ✅ when `JOBS_RUNNER=gcp-cloud-tasks` | — | No | server |
+| `GCP_TASKS_PUBLIC_URL` | example-backend Cloud Tasks runner | ✅ when `JOBS_RUNNER=gcp-cloud-tasks` | — | No | server |
+| `GCP_TASKS_OIDC_AUDIENCE` | example-backend Cloud Tasks runner | ❌ | `{publicUrl}/jobs/execute`; deployed Cloud Run uses the canonical tasks-service root URL so tagged PR callbacks pass platform IAM | No | server |
+| `GCP_TASKS_SERVICE_ACCOUNT_EMAIL` | example-backend Cloud Tasks runner | ✅ when `JOBS_RUNNER=gcp-cloud-tasks` | — | No | server |
 | `DEFAULT_PAGE_SIZE` | Configuration model | ❌ | `20` | No | server |
 | `CRON_SECRET_KEY` | tests | ❌ | — | Yes | tooling |
 | `WIDGET_CLIENT_SECRET` | widgets | ❌ | — | Yes | server |
@@ -278,3 +306,4 @@ secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
 - [Build for web](../how-to/build-for-web.md)
 - [Configure Better Auth](../how-to/configure-better-auth.md)
 - [Rate limiting](../how-to/rate-limiting.md)
+- [Durable background jobs](../how-to/background-jobs.md)