@terreno/mcp 57.19.2 → 57.21.0

package/src/docs/versioned/57.20.0/explanation/model-router-actions.md

@@ -0,0 +1,206 @@
+# modelRouter actions
+
+`modelRouter` can register **actions** — named operations at collection or instance scope — alongside standard CRUD. Actions reuse the same permission model, error envelope, and OpenAPI pipeline as CRUD routes, without hand-wiring `endpoints`, `asyncHandler`, and doc loading.
+
+CRUD **create, update, and delete** (not named actions) share one write pipeline: REST, Sync, and MCP all call `executeCreate` / `executeUpdate` / `executeDelete` in `api/src/sync/executors.ts`. MCP tools map arguments and `APIError` titles onto the MCP result envelope after the executor returns. RBAC User-role stripping runs in those executors **after** `transform` / `preCreate` / `preUpdate`. Stripping applies to the user model: a model compiled as `"User"`, or the `userModel` passed to `createAccess` under whatever name it was compiled. Pass `userModel` to `createAccess` when your user model has another name. Invalid document `_id` values (`CastError` on path `_id`, BSON invalid ObjectId) load as 404 `Document not found`; `CastError` on populate paths is a GET error, not a missing document.
+
+## When to use actions
+
+Use `collectionActions` / `instanceActions` for every application GET or POST that is not
+plain document CRUD. Do **not** register `app.get`, `app.post`, `router.get`, or
+`router.post` for those endpoints.
+
+Use actions when an endpoint performs an operation that is not a plain create/read/update/delete on the model document:
+
+- **Collection scope** (`POST /todos/bulkComplete`) — operate on many documents or the collection as a whole.
+- **Instance scope** (`POST /todos/:id/markComplete`) — operate on one loaded document.
+
+Leave Express `app.get` / `app.post` only for:
+
+- Inbound webhooks (`WebhooksApp`)
+- Static SPA / file serving
+- Framework auth, health, and version-check plugins
+- SSE or other streaming handlers that write the response themselves
+- Tests and harnesses
+
+PATCH and DELETE are CRUD (or a POST action that performs the same work). Do not add a
+hand-rolled DELETE next to a modelRouter.
+
+Use [custom routes with `createOpenApiBuilder`](./modular-api-design.md) only when the
+URL cannot be `/{actionName}` or `/:id/{actionName}` **and** the exceptions above do not
+apply.
+
+## Example
+
+```typescript
+import {modelRouter, Permissions, z} from "@terreno/api";
+import {Todo} from "../models/todo";
+
+export const todoRouter = modelRouter("/todos", Todo, {
+  permissions: {
+    create: [Permissions.IsAuthenticated],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+    delete: [Permissions.IsOwner],
+  },
+  instanceActions: {
+    markComplete: {
+      method: "POST",
+      permissions: [Permissions.IsOwner],
+      handler: async ({doc}) => {
+        doc.completed = true;
+        await doc.save();
+        return doc;
+      },
+      summary: "Mark a todo complete",
+    },
+  },
+  collectionActions: {
+    bulkComplete: {
+      method: "POST",
+      permissions: [Permissions.IsAuthenticated],
+      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
+      response: z.object({matched: z.number(), modified: z.number()}).strict(),
+      handler: async ({body, user}) => {
+        // updateMany using body.ids and user._id
+      },
+      summary: "Mark multiple todos complete",
+    },
+  },
+});
+```
+
+Use `.strict()` on Zod object schemas when you want unknown JSON keys rejected at runtime. Zod’s default object behavior strips unknown keys.
+
+## Handler context
+
+Handlers receive a single context object:
+
+| Field | Instance | Collection |
+|-------|----------|------------|
+| `req`, `res`, `user` | yes | yes |
+| `doc` | loaded document | — |
+| `body` | parsed body (see below) | parsed body |
+| `query` | parsed query | parsed query |
+
+Return a plain value from the handler; the framework responds with `{data: <value>}` and status `200` (or `action.status` if set). If the handler writes the response itself (`res.json`, streaming), return without relying on auto-wrap — the framework skips wrapping when `res.headersSent` is true.
+
+Set `unwrapResponse: true` to send the return value itself as the body, with `action.status`, instead of `{data: <value>}`. An `undefined` return sends an empty body (useful with `status: 204`). Use it when converting an existing `router.post` route whose clients expect the bare shape. OpenAPI documents the `response` schema without the `data` wrapper for these actions. `unwrapResponse` affects REST only; MCP always returns the value as the tool's JSON text.
+
+## Permissions
+
+Each action requires a non-empty `permissions` array (same `PermissionMethod` types as CRUD). An empty array disables the action and returns **405**, matching CRUD.
+
+HTTP method and scope map to a CRUD permission check:
+
+| Scope | GET | POST |
+|-------|-----|------|
+| Instance | `read` | `update` |
+| Collection | `list` | `create` |
+
+**405** — denied before a document is loaded (or on any collection action denial).  
+**403** — denied after the instance document is loaded (e.g. `IsOwner` with a document that fails the check).  
+**401** — unauthenticated when a permission requires auth (from existing auth middleware).
+
+With RBAC `access` on the router, an action without its own `access` inherits the router's resource and the mapped CRUD action. When the action's resource (inherited or set with `access`) matches the router's resource, the router's `access.scope` check and `access.also[method]` permissions also run, before and after the document loads, exactly as they do for the mapped CRUD method. A user whose role grants `todo:update` but who fails the router scope for a document gets **403** on that document's instance actions, the same as on `PATCH`. An action whose `access` names another resource skips the router's `scope` and `also`.
+
+`authenticateMiddleware` honors the router’s `allowAnonymous` option, same as CRUD. An action may set `allowAnonymous: true` to accept unauthenticated requests without making the router's CRUD routes or other actions anonymous. Keep a non-empty permission such as `Permissions.IsAny` and authenticate any service token in the handler.
+
+## Validation
+
+Optional `body` and `query` Zod schemas validate input. On failure the API returns **400** with `title: "Validation failed"` and field errors in `meta.fields`.
+
+Parsed values are passed only through `ctx.body` / `ctx.query`. Express 5 does not allow reassigning `req.query`; do not mutate `req.body` in middleware.
+
+When no `body` or `query` schema is configured, the raw `req.body` / `req.query` are passed through (for manual validation in the handler).
+
+## Document loading (instance actions)
+
+Instance actions load the document by `id` before the handler runs. Missing documents return **404**, including soft-delete metadata when applicable.
+
+`queryFilter` is **not** applied to this load (same as CRUD permission middleware). List filters may hide a document that still exists; post-load permission checks are responsible for access control.
+
+`req.obj` is set to the loaded document for parity with CRUD update/delete handlers.
+
+## OpenAPI and SDK codegen
+
+When `openApi` is configured on the router (automatic with `TerrenoApp` and `setupServer`), each action is documented on first route registration. Operations use:
+
+- **Tag** — model collection name by default; override with `action.tag`.
+- **operationId** — `{tag}_{actionName}` (e.g. `todos_markComplete`) for stable RTK Query hook names after SDK regeneration.
+
+Request/response schemas are derived from Zod when `body`, `query`, or `response` are set. Successful responses are documented as `{data: ...}` to match the wire format.
+
+## MCP tools
+
+Set `mcp: {name, description?}` on an action to also expose it as an MCP tool on `/mcp`, so a frontend calling the action over REST and an agent calling it over MCP share one implementation:
+
+```typescript
+instanceActions: {
+  promote: {
+    body: z.object({note: z.string().optional()}).strict(),
+    handler: async ({body, doc}) => promoteDraft(doc, body.note),
+    mcp: {description: "Promote a draft to published", name: "drafts_promote"},
+    method: "POST",
+    permissions: [Permissions.IsOwner],
+  },
+},
+```
+
+The tool behaves like the REST route:
+
+- **Input.** An instance action takes `{id, ...body}` (POST) or `{id, ...query}` (GET). A collection action takes the body or query alone. `body` / `query` must be a `z.object()`, and an instance action's schema cannot define `id` (a collection action's can, and gets it). With no schema, the tool accepts any arguments, as REST forwards the raw body.
+- **Validation.** The MCP server validates arguments against that schema before the handler runs, so the handler gets the same parsed `ctx.body` / `ctx.query` as REST.
+- **Permissions.** The same `runActionPermissions` chain runs before and after the document loads, including RBAC `access`. It never falls back to the router's CRUD permissions. A refused call returns an `isError` result with the error title (`Access denied`), where REST returns 403 or 405.
+- **Authentication.** A call without a user is refused unless the action or router sets `allowAnonymous`.
+- **Handler.** `req` comes from `createMCPRequest` (`req.isMCPRequest === true`, `req.params.id` set for instance actions). `res` throws `Action used res during an MCP call` when touched, so an action that writes to `res` directly cannot opt in.
+- **Result.** The return value becomes the tool's JSON text. A thrown `APIError` becomes an `isError` result with its title; validation errors add their field messages.
+
+Action tools are collected from every registered router when `/mcp` mounts, alongside CRUD and `registerMCPTool` tools. A disabled action (`permissions: []`) is not exposed. Tool names must be unique across all tools; a collision fails at boot.
+
+## Collision detection
+
+At router build time, Terreno rejects:
+
+- Empty action names or names that do not match `/^[A-Za-z][A-Za-z0-9_-]+$/`
+- Instance action names that match a Mongoose array field path (which would collide with `POST /:id/:field` array routes)
+
+Actions are registered before user `endpoints` callbacks, so they take precedence if paths overlap.
+
+## Migrating from `endpoints`
+
+Before (hand-rolled):
+
+```typescript
+endpoints: (router) => {
+  router.post("/generate", [authenticateMiddleware()], asyncHandler(async (req, res) => {
+    // manual admin check, validation, OpenAPI omitted
+    return res.json({data: result});
+  }));
+},
+```
+
+After:
+
+```typescript
+collectionActions: {
+  generate: {
+    method: "POST",
+    permissions: [Permissions.IsAuthenticated],
+    handler: async ({body, user}) => { /* ... */ return result; },
+  },
+},
+```
+
+Remove duplicate `asyncHandler`, `authenticateMiddleware`, and manual `{data: ...}` wrapping unless you need a custom response shape.
+
+## Dependencies
+
+`@terreno/api` lists **`zod` as a peer dependency** (^4.3.x). Applications that define action schemas must install `zod` in the backend project. Import `z` from `@terreno/api` (re-exported after OpenAPI extension) so action Zod schemas work with automatic OpenAPI generation.
+
+`@asteasolutions/zod-to-openapi` is bundled with `@terreno/api` for OpenAPI schema generation.
+
+## Concurrency
+
+Action handlers run the same as other Express handlers — no transactions or locking. Use application-level guards (version fields, idempotency keys) if you need to prevent double-submit races.

package/src/docs/versioned/57.20.0/explanation/modular-api-design.md

@@ -0,0 +1,236 @@
+# Modular API Design
+
+**Status**: 🚧 Planned for v2.0.0
+
+## The Problem
+
+As Terreno has grown, the `setupServer()` function has become increasingly difficult to extend and customize. When setting up new backends, several pain points emerge:
+
+1. **Configuration scattered across environment variables and options** — Some settings come from env vars (tokens, secrets), others from the options object, making it unclear what needs to be configured
+
+2. **All-or-nothing middleware** — Built-in middleware (CORS, body parsing, auth) can't be disabled or customized without editing the framework code
+
+3. **Limited extensibility** — Adding features like an admin panel requires touching multiple places in the middleware stack, making installation instructions tedious and error-prone
+
+4. **No lifecycle hooks** — Can't inject custom logic at precise points in server initialization or request handling
+
+5. **Rigid architecture** — Hard to build modular "apps" (like Django apps) that can be installed with a single call
+
+## The Solution: TerrenoApp
+
+The new `TerrenoApp` class addresses these issues with a **fluent builder API** inspired by Django and modern Node.js frameworks:
+
+``````typescript
+const app = TerrenoApp.create({
+  auth: {
+    userModel: User,
+    token: {secret: process.env.TOKEN_SECRET!, issuer: "myapp"},
+  },
+  middleware: {
+    cors: {enabled: true, origin: ["https://myapp.com"]},
+    helmet: {enabled: true},
+    rateLimit: {enabled: true, max: 100},
+  },
+  health: {
+    enabled: true,
+    check: async () => ({healthy: true, uptime: process.uptime()}),
+  },
+})
+  .addModelRouter("/todos", Todo, {list: [IsAuthenticated]})
+  .addRoute("/webhooks", webhookRouter)
+  .enableWebSocket({path: "/ws"})
+  .start();
+``````
+
+### Key Improvements
+
+#### 1. Configuration over Environment Variables
+
+All settings are explicit options, not env vars. This makes configuration:
+- **Discoverable**: TypeScript autocomplete shows all available options
+- **Testable**: Easy to swap configurations between environments
+- **Documented**: JSDoc on each option explains its purpose
+
+Environment variables can still be used, but they're passed in explicitly:
+
+``````typescript
+auth: {
+  token: {
+    secret: process.env.TOKEN_SECRET!,  // Explicit, not implicit
+    issuer: process.env.TOKEN_ISSUER!,
+  },
+}
+``````
+
+#### 2. Toggleable Middleware
+
+Every piece of built-in middleware can be enabled, disabled, or customized:
+
+``````typescript
+middleware: {
+  cors: false,                    // Disable entirely
+  json: {limit: "10mb"},          // Customize
+  helmet: {enabled: true},        // Enable with defaults
+  rateLimit: {                    // Enable with custom config
+    windowMs: 15 * 60 * 1000,
+    max: 100,
+  },
+}
+``````
+
+#### 3. Comprehensive Hooks
+
+Hooks allow custom logic at every stage:
+
+``````typescript
+hooks: {
+  onAppCreated: (app) => {
+    // Just after Express app created
+  },
+  onAuthReady: (app) => {
+    // After auth middleware configured, before routes
+  },
+  onRoutesReady: (app) => {
+    // After all routes added, before error handlers
+  },
+  onReady: (app) => {
+    // App fully configured, before listening
+  },
+  onListening: (server, port) => {
+    // Server started
+  },
+  onRequest: (req, res) => {
+    // On every incoming request
+  },
+  onError: (error, req, res) => {
+    // On every error
+  },
+  onShutdown: async () => {
+    // On graceful shutdown
+  },
+}
+``````
+
+These hooks enable advanced use cases like:
+- Custom admin-only auth checks inserted after built-in auth
+- Request-level metrics and tracing
+- Cleanup tasks on shutdown (close DB connections, flush logs)
+
+#### 4. Fluent API
+
+Instead of a single large options object, configuration happens through chained method calls:
+
+``````typescript
+TerrenoApp.create({auth, middleware})
+  .addModelRouter("/users", User, permissions)
+  .addModelRouter("/posts", Post, permissions)
+  .addRoute("/webhooks", webhookRouter)
+  .addMiddleware(customMiddleware, {path: "/admin"})
+  .enableWebSocket({path: "/ws"})
+  .start();
+``````
+
+This is:
+- **More readable**: Each line is a clear intent
+- **More flexible**: Add routes and middleware in any order
+- **Easier to extend**: New methods can be added without breaking existing code
+
+#### 5. Foundation for Modular Apps
+
+The new architecture enables installable "apps" (like Django's app system):
+
+``````typescript
+import {adminApp} from "@terreno/admin";
+
+TerrenoApp.create({auth})
+  .install(adminApp({
+    models: [User, Post, Todo],
+    permissions: [IsAdmin],
+  }))
+  .start();
+``````
+
+This would be nearly impossible with `setupServer()` because installing an app requires:
+- Adding routes at a specific point in the stack
+- Registering middleware
+- Adding hooks for initialization
+- Merging OpenAPI specs
+
+With TerrenoApp, an "app" is just a function that receives the `TerrenoApp` instance and calls its methods.
+
+#### 6. One collection catalog for surfaces
+
+`modelRouter` registers each collection once in an in-memory **collection catalog** keyed by route path (for example `/todos`). The record holds the Mongoose model, `ModelRouterOptions`, and which surfaces are active (`mcp`, `realtime`, `sync`). TerrenoApp option enrichment calls `replaceCollectionOptions` once per path after RBAC injects `accessControl`.
+
+MCP, realtime, and sync read **views** of that catalog — they do not keep separate option arrays. `registerMCPModel`, `registerRealtime`, `registerSync`, and the `update*RegistryOptions` helpers remain as wrappers for tests and legacy callers. `clearMCPRegistry`, `clearRealtimeRegistry`, and `clearSyncRegistry` clear the **whole** catalog so tests cannot leave a stale MCP entry after a sync-only clear.
+
+Custom MCP tools stay on a separate list; they are not collections. Sync schema validation and index enqueue still run when a collection first opts into `sync`.
+
+## Design Principles
+
+### 1. Explicit over Implicit
+
+Settings are passed in, not read from global state (env vars). This makes dependencies clear and testing easier.
+
+### 2. Composable over Monolithic
+
+Features are added via method calls, not configured via a mega-options object. This allows fine-grained control.
+
+### 3. Progressive Disclosure
+
+Simple cases are simple:
+
+``````typescript
+TerrenoApp.create({auth: {userModel: User, token: {...}}})
+  .addModelRouter("/todos", Todo, {list: [IsAuthenticated]})
+  .start();
+``````
+
+Complex cases are possible:
+
+``````typescript
+TerrenoApp.create({auth, middleware, health, logging, hooks})
+  .addModelRouter("/todos", Todo, {...})
+  .addRoute("/webhooks", webhookRouter, {openapi: {...}})
+  .addMiddleware(customMiddleware, {position: "afterAuth"})
+  .addErrorHandlingMiddleware(sentryErrorHandler)
+  .enableWebSocket({path: "/ws", authenticate, onConnection, onMessage})
+  .start();
+``````
+
+### 4. Backward Compatibility (Initially)
+
+The implementation plan originally aimed for backward compatibility with `setupServer()`, but the final design makes this a **breaking change**. This is intentional:
+
+- Allows cleaner architecture without maintaining two code paths
+- Forces migration to better patterns
+- Provides opportunity to fix long-standing API warts
+
+Migration will be supported with:
+- Detailed migration guide
+- Deprecation warnings in v2.0.0-beta
+- `setupServer()` available but deprecated in v2.0.0
+- Removal in v3.0.0, giving users time to migrate
+
+## Implementation Status
+
+**Current**: Planning phase (implementation plan merged)
+
+**Next steps**:
+1. ✅ Write implementation plan
+2. ✅ Gather community feedback
+3. 🚧 Implement core TerrenoApp class with tests
+4. 🚧 Update example-backend to demonstrate new API
+5. 🚧 Write migration guide with real examples
+6. 🚧 Publish v2.0.0-beta for testing
+7. 🚧 Address feedback and publish v2.0.0
+
+## Learn More
+
+- 📖 [Implementation plan](../implementationPlans/ModularAPI.md) — Full technical specification
+- 💬 [GitHub PR #149](https://github.com/TerrenoLabs/terreno/pull/149) — Discussion and feedback
+
+## Related
+
+- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
+- [Authentication architecture](authentication.md) — How JWT and OAuth work in Terreno

package/src/docs/versioned/57.20.0/explanation/organizations.md

@@ -0,0 +1,125 @@
+# How organization tenancy works
+
+Terreno treats organizations as an optional framework primitive. Existing
+single-tenant apps do not pay a migration or authorization cost; multi-tenant
+apps opt in at the access, application, model, and admin layers. New apps
+generated by `create-terreno-app` opt in by default.
+
+## Identity and authorization layers
+
+Platform and tenant authority are separate:
+
+| Authority | Storage | Scope |
+| --- | --- | --- |
+| `superadmin` | `User.roles` | Every framework permission |
+| `operator` | `User.roles` | Organization directory and every organization |
+| `org-admin` | `Membership.roleName` | One organization |
+| `member` | `Membership.roleName` | One organization; app permissions decide actions |
+
+`user.admin` does not imply operator access. `org-admin` is deliberately not a
+global RBAC role: putting it on `User.roles` grants nothing. During an
+organization request, `createAccess({organizations: true})` adds the current
+active Membership grants to the normal role permissions.
+
+## Request context
+
+Tenant routes resolve `X-Organization-Id` after authentication. An operator or
+superadmin may enter any organization but must choose one. An org-admin with
+exactly one administered organization may omit the header; Terreno infers it.
+Ambiguous or unauthorized context fails before model queries run.
+
+The resolved organization and membership are stored in AsyncLocalStorage as
+well as `req.organization` / `req.membership`. This lets `OrgQueryFilter` add
+the server-owned organization id without trusting a client query parameter.
+
+## Isolation boundaries
+
+Tenant isolation uses multiple checks rather than one convention:
+
+1. `orgContextMiddleware({required: true})` rejects missing or unauthorized context.
+2. `OrgQueryFilter` ANDs the selected organization into list and search queries.
+3. `Permissions.IsOrganizationMember` rejects cross-org object reads and writes.
+4. Create hooks overwrite client-supplied organization ids.
+5. `orgScopedPlugin` rejects any post-create change to `organizationId` (REST, admin, sync, direct save).
+6. Sync scopes resolve active Membership rows and partition streams by organization.
+
+`AdminApp({organizations: true})` applies these boundaries automatically to
+admin models whose schema contains `organizationId`. Models without that path
+remain platform-scoped.
+
+Adding, changing, or removing a membership through `POST` / `PATCH` / `DELETE
+/orgs/:id/members` clears that user's cached permissions, so a new org-admin can open the
+admin page (and a demoted or removed one loses it) on their next request instead of after
+the permission cache's 30-second TTL. Disabling (`PATCH /orgs/:id` with `disabled: true`) or
+deleting (`DELETE /orgs/:id`) an organization suspends all of its memberships and clears the
+cached permissions of every member the same way.
+
+## Disabled organizations
+
+When `Organization.disabled` is `true`, tenant context and membership mutations
+stop, but operators can still manage the organization record itself:
+
+| Surface | Disabled org behavior |
+| --- | --- |
+| `orgContextMiddleware` / inferred org context | 403 `Organization is disabled` |
+| `GET /orgs/mine` | Disabled orgs omitted from the switcher list |
+| `GET /orgs` (operator directory) | Disabled orgs still listed |
+| `GET` / `PATCH /orgs/:id` | Allowed (operators use `PATCH` with `disabled: false` to re-enable) |
+| `POST` / `PATCH` / `DELETE /orgs/:id/members` | 403 while disabled |
+| Soft-deleted orgs | Still 404 everywhere |
+
+Disabling or deleting an organization suspends its memberships. Re-enabling does
+not automatically reactivate them.
+
+## Member recovery
+
+When the app registers `AccountSecurityApp`, an org-admin can help a locked-out member without
+platform staff. `OrgsApp` mounts the same recovery handlers the platform uses at
+`/orgs/:orgId/members/:userId/security/*`, behind an org authorizer.
+
+- **Reach.** An org-admin may act on any active member of their org, even one who also belongs
+  to other orgs (D2). A suspended member, or a user outside the org, answers `404`, so the routes
+  do not reveal who exists elsewhere.
+- **Guards.** Platform staff (`superadmin`, `operator`) and `admin: true` users are never reachable
+  through an org (D3). Neither is anyone who holds a permission the org-admin lacks, nor the
+  org-admin themselves (D9). Disabled orgs answer `403`.
+- **Disable means suspend.** One org must not lock a user out of every other org, so the org
+  path has no account disable. It offers `suspend-membership` instead, which suspends the
+  membership in that org only (Q8). The user still signs in and keeps their other orgs.
+  `User.disabled` and `issue-sign-in-link` stay platform-only.
+- **Attach-then-act.** An org-admin can attach any existing user by email
+  (`POST /orgs/:id/members`). Every org-admin action is audited with the org's id and emails the
+  user, so they learn about it ([notifications](../reference/account-security.md#notifications);
+  the org is named only with `notifications.includeOrgName`). Apps that want more can set
+  `orgRecovery.minMembershipDays` to refuse members who joined too recently.
+- **Platform staff** holding `user:manageSecurity` pass the org checks. The target must still be
+  an active member of the org in the path. Their reach check is the platform one: both sides are
+  resolved outside the organization, so an org-only grant does not put the member out of reach.
+
+See [Recover a locked-out user](../how-to/recover-locked-out-user.md) for who can do what, and
+the [account security reference](../reference/account-security.md#org-admin-routes) for every
+response.
+
+## Why organizations are optional
+
+Automatically registering routes, roles, or Mongoose models would change
+existing apps merely because they upgraded `@terreno/api`. Instead:
+
+- `createAccess` omits Membership grants and the `operator` seed unless
+  `organizations: true`;
+- `TerrenoApp` does not mount `/orgs` unless organizations are enabled;
+- `AdminApp` does not scope models unless organizations are enabled;
+- Organization and Membership Mongoose models register lazily on first use.
+  Apps add fields to `Organization.settings` with `createOrganizationSettingsSchema`
+  and `registerOrganizationSettings`, not by replacing the Organization model.
+
+This keeps upgrades backward compatible while letting bootstrap generate
+multi-tenant-ready apps.
+
+## Related
+
+- [Add organizations](../how-to/add-organizations.md)
+- [Recover a locked-out user](../how-to/recover-locked-out-user.md)
+- [API reference](../reference/api.md#organizations)
+- [Admin backend reference](../reference/admin-backend.md#organization-scoping)
+- [Admin frontend reference](../reference/admin-frontend.md#orgdirectoryscreen)