@terreno/mcp 57.21.0 → 57.22.0

package/dist/docs/versioned/57.21.0/explanation/schema-metadata.md

@@ -0,0 +1,65 @@
+# Schema metadata (`describeModel`)
+
+Terreno walks each Mongoose schema **once** and builds a `ModelDescription` field graph. OpenAPI, admin config, and MCP tools are **views** of that graph — they do not re-walk `schema.paths` independently.
+
+## Why one descriptor
+
+Before `describeModel`, three surfaces each interpreted Mongoose differently:
+
+- **OpenAPI** — `mongoose-to-swagger` in `getOpenApiSpecForModel`
+- **Admin** — OpenAPI property walk plus Mongoose ref patching in `extractFieldMeta`
+- **MCP** — `schema.paths` + `SchemaType.instance` switch in `schemaGenerator`
+
+That drifted on refs, enums, nested arrays, and system fields. A single descriptor keeps field facts in one place.
+
+## Core API
+
+```typescript
+import {describeModel, describeModelForRouter} from "@terreno/api";
+
+const description = describeModel(Todo);
+// description.fields[path].kind, .required, .description, .enum, .ref, .isArray, .item, .system
+
+const routerDescription = describeModelForRouter(Todo, {
+  validation: {excludeFromCreate: ["ownerId"]},
+  fieldView: {read: "*", write: ["title", "completed"]},
+});
+// adds writableOnCreate / writableOnUpdate per field
+```
+
+## Field kinds
+
+| Kind | Mongoose source | Notes |
+|------|-----------------|-------|
+| `string` | String | Includes enum strings |
+| `number` | Number | |
+| `boolean` | Boolean | |
+| `date` | Date | ISO date-time in OpenAPI |
+| `dateOnly` | DateOnly | Custom Terreno type |
+| `objectId` | ObjectId | Carries `ref` model name |
+| `embedded` | Subdocument / array of subdocuments | Nested `fields` |
+| `mixed` | Mixed | Accepts any value in OpenAPI |
+| `map` | Map | `item` follows Map `of` (omitted `of` is `mixed`); OpenAPI `additionalProperties` |
+
+System paths (`_id`, `__v`, `created`, `updated`, `deleted`) are marked with `system: true`.
+
+`required` is true only when the field is required on every document. A conditional
+`required` (a function, such as "required when `provisional` is true") leaves it false, so
+OpenAPI and generated SDKs type the field as optional; Mongoose still enforces the condition
+on save.
+
+## Views (not canonical)
+
+| Surface | Function | Notes |
+|---------|----------|-------|
+| OpenAPI | `modelDescriptionToOpenApiSpec` | Used by `getOpenApiSpecForModel`; populate still merges referenced models |
+| Admin `/admin/config` | `modelDescriptionToAdminFields` | Widget choice stays in admin-backend |
+| MCP Zod | `fieldDescriptionToZodType` | Create/update tools omit system fields |
+
+Populate paths remain a `getOpenApiSpecForModel` concern; the descriptor records `ref` on the local path only.
+
+## Related
+
+- [API reference — describeModel](../reference/api.md#describemodel)
+- [How to create a model](../how-to/create-a-model.md)
+- [Admin backend reference](../reference/admin-backend.md)

package/dist/docs/versioned/57.21.0/how-to/README.md

@@ -0,0 +1,86 @@
+# How-to Guides
+
+Problem-oriented, practical steps. Use these when you know what you want to do.
+
+## Deployment
+
+- [Deployment baseline](../explanation/deployment-baseline.md) — seven requirements every host must satisfy
+- [Build for web](build-for-web.md) — export static web bundle with correct API URL
+- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — index for GCP guides
+- [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) — container + Secret Manager + Cloud Run
+- [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) — static hosting with SPA routing
+- [Deploy to Vercel](deploy-to-vercel.md) — web on Vercel, backend on Cloud Run or Vercel Functions; previews, CORS, CI
+- [Run WebSockets on Vercel Functions](vercel-function-websockets.md) — Socket.IO and syncdb on Vercel's WebSocket beta: transports, reconnects, state
+
+## Contents
+
+- [Create a Terreno app](create-a-terreno-app.md) — Scaffold a full-stack app with `create-terreno-app` (Bun or npm)
+- [Update dependencies](update-dependencies.md) — Daily rolling PR, exercise test, Expo fingerprint freeze
+- [CircleCI](circleci.md) — Dual-run CI on CircleCI (package CI / policy / e2e; deploys later)
+- [Release automation](release-automation.md) — Let agents merge release notes and roadmap updates; publish only merged notes
+- [Set up tests in a Terreno app](set-up-app-tests.md) — Bun backend and frontend tests, Playwright web E2E, Maestro on iOS/Android
+- [Run tests locally](run-tests-locally.md) — Map every CircleCI test job to a Cursor Cloud / laptop command
+- [GitHub Actions CI](github-actions-ci.md) — Cut PR runtime: docs previews, compile-once e2e, pinned Bun
+- [Add feature flags](add-feature-flags.md) — Add feature flags, A/B testing, and OpenFeature migration
+- [Rate limiting](rate-limiting.md) — Opt-in HTTP limiter on `TerrenoApp` (memory or Redis)
+- [Receive inbound webhooks](inbound-webhooks.md) — HMAC, Stripe, Twilio, and SendGrid signatures on `WebhooksApp`
+- [Durable background jobs](background-jobs.md) — `@terreno/jobs`: enqueue, workers, schedules, Cloud Tasks / Vercel Queues
+- [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
+- [Enable the framework audit log](audit-log.md) — `AuditApp`, per-router `audit`, append-only events
+- [Sign consent on a user's behalf](sign-consent-on-behalf.md) — Provisional consent signatures: RBAC grant, signer screen, status checks, void, print
+- [Seed a database](seed-a-database.md) — Idempotent sync, dry runs, and guarded reset-and-reseed
+- [Run MongoDB migrations](run-mongodb-migrations.md) — Versioned `up`/`down` files, `terreno-migrate`, production gate
+- [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
+- [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
+- [Set up social login](set-up-social-login.md) — Register Google, GitHub, and Apple once on the stable deploy, proxy previews through it, and move stable onto one domain
+- [Password reset and email verification](password-reset.md) — JWT routes, comms templates, Better Auth hooks
+- [Recover a locked-out user](recover-locked-out-user.md) — Platform and org-admin recovery: 2FA, passkeys, providers, sessions, suspend
+- [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
+- [Expose Model Context Protocol tools](expose-mcp-tools.md) — Turn `modelRouter` models into MCP tools an LLM can call
+- [Set up Terreno MCP](set-up-terreno-mcp.md) — Connect Cursor or Claude Code to the hosted docs/codegen server and the local runtime server
+- [Debug with MCP](debug-with-mcp.md) — Follow a failure from symptom to verified fix with the local MCP tools
+- [Connect an MCP client with a service token](connect-mcp-service-token.md) — Mint a personal `mcp_` key for Perplexity and other remote clients
+- [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md) — Let Claude.ai and ChatGPT connect to `/mcp` through OAuth 2.1 with your own consent screen
+- [Manage MCP from the admin panel](manage-mcp-in-admin.md) — Service tokens, OAuth clients and connections, request log, tool on/off switches, and sign-out-everywhere
+- [Expose an MCP server safely](expose-mcp-server-safely.md) — Put `/mcp` on the internet with OAuth, service tokens, a named Cloudflare Tunnel, and Access on the console
+- [Install agent skills](install-agent-skills.md) — `npx skills`, the Cursor plugin, the Codex plugin, or the Claude Code plugin
+- [Develop an AI feature](ai-feature-development.md) — Dataset → prompt → evaluators → experiment → production label → live traces (SOP)
+- [Observe LLM calls](observe-llm-calls.md) — Register ObservabilityApp, primaries, price map, sampleRate
+- [Build a durable workflow](build-a-durable-workflow.md) — Phased harness task with an agent, a human sign-off, and a once-only side effect (`clinic.intakeSummary`)
+- [Run the harness on multiple instances](run-harness-on-multiple-instances.md) — `JobsRunner`: harness phases as `@terreno/jobs` jobs on every instance
+- [Ship a new task version](ship-a-new-task-version.md) — Change a durable harness task without stranding in-flight runs
+- [GitHub issue lifecycle](github-issue-lifecycle.md) — Create pick-ready issues, Pick ⇄ Roast, or unattended `status:ready-for-dev` pickup
+- [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
+- [Upgrade banner](upgrade-banner.md) — Soft warning and hard-block app update UX
+- [Upgrade Terreno](upgrade-terreno.md) — Lockstep `@terreno/*` bumps, note range, order, rollback
+- [Automate Terreno upgrades](automate-terreno-upgrades.md) — Hourly workflow that launches one upgrade agent when a week-old release is out and no upgrade is open
+- [Track upstream Expo](track-upstream-expo.md) — Morning probe for SDK betas; `release-X.Y.Z` loop log + native fingerprint deps
+- [Build a list/detail screen](build-list-detail-screens.md) — `ListDetailLayout` route group: list on a phone, list + detail panes on a tablet, selection in the URL
+- [Show loading skeletons](show-loading-skeletons.md) — `loading`, `loadingComponent`, and `loadingAnimation` on Box, Card, charts, and Page; `withLoading` for custom components
+- [Compose charts in a dashboard grid](charts-and-dashboards.md) — `LineChart` / `BarChart` / `AreaChart` / `DonutChart` inside `Card`s in `DashboardGrid` (ops-dashboard scorecards and spans: [dashboard-chart-parity](../implementationPlans/dashboard-chart-parity.md))
+- [Compare rendered chart snapshots](compare-chart-rendered-snapshots.md) — PNG goldens for the chart visual gallery, not JSON snapshots
+- [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
+- [Use syncdb correctly](use-syncdb-correctly.md) — Serial snapshot startup, outbox-halting 403s, phantom creates, conflicts, and other library behavior apps must handle
+- [Generate a REST CLI from OpenAPI](generate-a-rest-cli.md) — Scaffold `terreno generate rest-cli` for an app API
+- [In-app notifications](in-app-notifications.md) — Register `NotificationsApp`, syncdb inbox, and UI bell
+- [Add organizations](add-organizations.md) — Opt into Membership-backed tenancy, RBAC, admin, and seeded examples
+- [Add a GPT chat mascot](add-gpt-chat-mascot.md) — Optional consumer-owned character on empty `GPTChat`
+- [Add agent asks to a chat](agent-ui-asks.md) — Turn on `asks`, show and answer them in `GPTChat`, try the keyless demo agent, and answer asks from an Apple Watch or another small client
+- [Validate a block document locally](agent-ui-blocks.md) — `terreno-blocks validate` for a whole-reply YAML document
+- [Add a stepper callback](agent-ui-blocks.md#add-a-stepper-callback) — `scaleStepperHostAction` or your own `handles: "stepper"` action; checklist ticks, copy buttons, the `richBlocks: false` opt-out, and the `blocks:smoke` model check are on the same page
+- [Give the agent photos](agent-ui-blocks.md#give-the-agent-photos) — Generate a stored photo library once and let the agent cite it with `findPhotos`
+
+## Admin
+
+- [Build admin screens](build-admin-screens.md) — Screens, sidebar nav, `routeBase`, custom screens
+- [Add a model to the admin](admin-add-model.md) — `modelRouter({admin: ...})` setup
+- [Import pre-built admins](admin-import-prebuilt.md) — Plugin `adminContribution()` wiring
+- [Add a custom admin field widget](admin-custom-widget.md) — Custom field widgets
+- [Customize the admin home](admin-custom-home.md) — Home slots and built-in widgets
+
+## Coming Soon
+
+- Add custom permissions
+- Implement file uploads
+- Configure email notifications
+- Customize AI workflows

package/dist/docs/versioned/57.21.0/how-to/add-github-oauth.md

@@ -0,0 +1,349 @@
+# Add GitHub OAuth Authentication
+
+Add GitHub OAuth login to your @terreno/api backend. Users can authenticate with their GitHub account, and optionally link GitHub to existing password-based accounts.
+
+## Prerequisites
+
+- Existing @terreno/api backend with `setupServer()` configured
+- User model with authentication set up
+- GitHub OAuth application (see [Creating a GitHub OAuth App](#creating-a-github-oauth-app))
+
+## Step 1: Install Dependencies
+
+GitHub OAuth support uses `passport-github2`, which is already included as a dependency in @terreno/api.
+
+## Step 2: Add GitHub Fields to User Model
+
+Apply the `githubUserPlugin` to your user schema to add GitHub authentication fields:
+
+``````typescript
+import {githubUserPlugin} from "@terreno/api";
+import mongoose from "mongoose";
+
+const userSchema = new mongoose.Schema({
+  email: {
+    description: "User's email address",
+    type: String,
+    unique: true,
+    required: true,
+  },
+  name: {
+    description: "User's display name",
+    type: String,
+  },
+  admin: {
+    description: "Whether the user has admin privileges",
+    type: Boolean,
+    default: false,
+  },
+});
+
+// Add GitHub authentication fields
+userSchema.plugin(githubUserPlugin);
+
+export const User = mongoose.model("User", userSchema);
+``````
+
+The plugin adds these fields:
+- `githubId` — GitHub user ID (unique, indexed)
+- `githubUsername` — GitHub username
+- `githubProfileUrl` — GitHub profile URL
+- `githubAvatarUrl` — GitHub avatar image URL
+
+## Step 3: Configure GitHub OAuth
+
+Add GitHub authentication configuration to your `setupServer()` call:
+
+``````typescript
+import {setupServer} from "@terreno/api";
+import {User} from "./models/user";
+
+setupServer({
+  userModel: User,
+  addRoutes: (router, options) => {
+    // Your route setup
+  },
+  githubAuth: {
+    clientId: process.env.GITHUB_CLIENT_ID!,
+    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    callbackURL: process.env.GITHUB_CALLBACK_URL || "http://localhost:4000/auth/github/callback",
+    scope: ["user:email"], // Optional, defaults to ["user:email"]
+    allowAccountLinking: true, // Optional
+    allowedReturnTo: ["https://app.yourapp.com", "yourapp://auth"], // Optional, needed for returnTo
+  },
+});
+``````
+
+### Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `clientId` | string | Yes | GitHub OAuth Client ID |
+| `clientSecret` | string | Yes | GitHub OAuth Client Secret |
+| `callbackURL` | string | Yes | OAuth callback URL (must match GitHub app settings) |
+| `scope` | string[] | No | OAuth scopes (default: `["user:email"]`) |
+| `allowAccountLinking` | boolean | No | `true` lets `GET /auth/github/link` attach GitHub to the signed-in user. When omitted, the link route is mounted but linking returns 400, and a GitHub login whose email matches an existing account links to it. `false` turns off both. |
+| `allowedReturnTo` | string[] | No | Exact http(s) origins (`https://app.yourapp.com`) or custom-scheme authorities (`yourapp://auth`) that `returnTo` may point to. Unset means `returnTo` is ignored. |
+| `findOrCreateUser` | function | No | Custom user creation/lookup handler |
+
+## Step 4: Set Environment Variables
+
+Add these to your `.env` file:
+
+``````bash
+GITHUB_CLIENT_ID=your_github_client_id
+GITHUB_CLIENT_SECRET=your_github_client_secret
+GITHUB_CALLBACK_URL=http://localhost:4000/auth/github/callback
+``````
+
+**Important:** Never commit secrets to version control. Use different values for development, staging, and production.
+
+## Step 5: Test the Integration
+
+The following routes are automatically added when `githubAuth` is configured:
+
+### Login with GitHub
+
+``````http
+GET /auth/github
+``````
+
+Redirects users to GitHub for authentication. The redirect carries an OAuth `state` value, and
+the response sets a short-lived (10 minute), signed, HttpOnly, `SameSite=Lax` cookie named
+`terreno_github_oauth_state` that holds the same value. The callback accepts the GitHub response
+only from the browser that holds that cookie, and each cookie works once. The cookie is signed
+with `SESSION_SECRET` (or `TOKEN_SECRET` when `SESSION_SECRET` is unset).
+
+Optional query parameter:
+- `returnTo` — URL to redirect to after successful authentication. Its origin (or custom-scheme
+  authority) must be listed in `allowedReturnTo`; any other value returns 400. When
+  `allowedReturnTo` is unset, `returnTo` is ignored and the callback returns JSON. Tokens are
+  delivered in the URL fragment (`#token=...&refreshToken=...&userId=...`), never the query
+  string. `returnTo` is kept in `req.session` between the two requests, so it needs a
+  persistent session middleware (for example `express-session`) mounted through
+  `beforeJsonSetup` or `addMiddleware`; TerrenoApp ships none.
+
+### OAuth Callback
+
+``````http
+GET /auth/github/callback
+``````
+
+Handles the GitHub OAuth callback. Without an allowlisted `returnTo`, returns JSON with tokens:
+
+``````json
+{
+  "data": {
+    "token": "eyJhbGc...",
+    "refreshToken": "eyJhbGc...",
+    "userId": "507f1f77bcf86cd799439011"
+  }
+}
+``````
+
+### Link GitHub Account (Requires Auth)
+
+``````http
+GET /auth/github/link
+Authorization: Bearer <jwt-token>
+``````
+
+Links GitHub to the authenticated user's existing account. Redirects to GitHub, then back to
+the callback. The user ID from the bearer token is recorded in the signed state cookie, and the
+callback links GitHub only to that user. A session cookie or token that happens to be on the
+callback request is never used as the link target. Open this route in the same browser that will
+return to the callback, so the state cookie is present there. Requires
+`allowAccountLinking: true`.
+
+### Unlink GitHub Account (Requires Auth)
+
+``````http
+DELETE /auth/github/unlink
+Authorization: Bearer <jwt-token>
+``````
+
+Removes GitHub authentication from the user's account. Returns:
+
+``````json
+{
+  "data": {
+    "message": "GitHub account unlinked successfully"
+  }
+}
+``````
+
+**Note:** Users must have a password set before unlinking GitHub.
+
+## Authentication Flow
+
+### New User Registration
+
+1. User clicks "Sign in with GitHub"
+2. Frontend redirects to `GET /auth/github?returnTo=<frontend-url>`
+3. User authorizes on GitHub
+4. Backend receives callback, creates new user with GitHub profile data
+5. Backend generates JWT tokens
+6. Backend checks `returnTo` against `allowedReturnTo` again and redirects there with tokens in the URL fragment
+7. Frontend stores tokens and logs user in
+
+### Existing User Login
+
+If a user with the same GitHub ID already exists, they are logged in automatically.
+
+### Account Linking
+
+1. User logs in with email/password
+2. User clicks "Link GitHub Account"
+3. Frontend makes authenticated request to `GET /auth/github/link`
+4. User authorizes on GitHub
+5. Backend links GitHub ID to existing user account
+6. User can now log in with either method
+
+## Custom User Creation
+
+For advanced use cases, provide a custom `findOrCreateUser` function:
+
+``````typescript
+setupServer({
+  githubAuth: {
+    clientId: process.env.GITHUB_CLIENT_ID!,
+    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    callbackURL: process.env.GITHUB_CALLBACK_URL!,
+    findOrCreateUser: async (profile, accessToken, refreshToken, existingUser) => {
+      // Custom logic for finding or creating users
+      // - profile: GitHub profile data
+      // - accessToken: GitHub access token
+      // - refreshToken: GitHub refresh token (if available)
+      // - existingUser: The user who started GET /auth/github/link (from the verified
+      //   OAuth state), otherwise undefined
+      
+      if (existingUser) {
+        // Link GitHub to existing user
+        existingUser.githubId = profile.id;
+        existingUser.githubUsername = profile.username;
+        await existingUser.save();
+        return existingUser;
+      }
+      
+      // Find or create user based on GitHub ID or email
+      let user = await User.findOne({githubId: profile.id});
+      if (!user && profile.emails?.[0]?.value) {
+        user = await User.findOne({email: profile.emails[0].value});
+      }
+      
+      if (!user) {
+        user = await User.create({
+          githubId: profile.id,
+          githubUsername: profile.username,
+          email: profile.emails?.[0]?.value,
+          name: profile.displayName,
+        });
+      }
+      
+      return user;
+    },
+  },
+});
+``````
+
+## Frontend Integration
+
+### React Native / Expo
+
+Use `expo-auth-session` for OAuth flow:
+
+``````typescript
+import * as AuthSession from "expo-auth-session";
+
+const redirectUri = AuthSession.makeRedirectUri();
+
+const handleGitHubLogin = async () => {
+  const result = await AuthSession.startAsync({
+    authUrl: `https://api.yourapp.com/auth/github?returnTo=${redirectUri}`,
+  });
+  
+  if (result.type === "success") {
+    // Tokens arrive in the fragment; expo-auth-session merges fragment values into params
+    const {token, refreshToken, userId} = result.params;
+    // Store tokens and log in user
+  }
+};
+``````
+
+### Web
+
+Simple redirect flow:
+
+``````typescript
+const handleGitHubLogin = () => {
+  window.location.href = `https://api.yourapp.com/auth/github?returnTo=${window.location.origin}/auth/callback`;
+};
+
+// On callback page (/auth/callback). Tokens are in the fragment, not the query string.
+const fragment = new URLSearchParams(window.location.hash.slice(1));
+const token = fragment.get("token");
+const refreshToken = fragment.get("refreshToken");
+const userId = fragment.get("userId");
+// Clear the fragment, store tokens, and redirect to app
+window.history.replaceState(null, "", window.location.pathname);
+``````
+
+## Creating a GitHub OAuth App
+
+1. Go to GitHub Settings → Developer settings → OAuth Apps
+2. Click "New OAuth App"
+3. Fill in:
+   - **Application name**: Your App Name
+   - **Homepage URL**: `http://localhost:4000` (dev) or your production URL
+   - **Authorization callback URL**: `http://localhost:4000/auth/github/callback`
+4. Click "Register application"
+5. Copy the Client ID
+6. Generate a new Client Secret and copy it
+7. Add both to your `.env` file
+
+**Production:** Create a separate OAuth app for production with your production callback URL.
+
+## Security Considerations
+
+- **Never expose client secrets** — They should only exist on the backend
+- **State is enforced** — The callback rejects a response without a valid, unexpired state cookie from the same browser (redirect to `/auth/github/failure`), which blocks login CSRF and cross-site account linking
+- **Use HTTPS in production** — GitHub OAuth requires HTTPS for production callbacks
+- **Redirect allowlist** — List only your own app origins in `allowedReturnTo`. Matching is exact on origin (or custom-scheme authority); subdomains and other ports are not included
+- **Scope minimization** — Only request GitHub scopes your app actually needs
+- **Token storage** — Store tokens securely on the frontend (SecureStore on mobile, httpOnly cookies on web)
+
+## Troubleshooting
+
+### "GitHub authentication failed"
+
+- Verify `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` are correct
+- Check that callback URL in GitHub app settings matches `GITHUB_CALLBACK_URL`
+- Ensure user grants all requested permissions
+
+### "This GitHub account is already linked to another user"
+
+A different user has already linked this GitHub account. Users must unlink it first or use a different GitHub account.
+
+### Callback redirects to `/auth/github/failure` right away
+
+The OAuth state did not verify. The flow must start (`/auth/github` or `/auth/github/link`) and
+finish (`/auth/github/callback`) in the same browser within 10 minutes, and the API host that
+serves `callbackURL` must be the host that set the cookie. Check that `SESSION_SECRET` is the
+same on every instance.
+
+### "Account linking is disabled"
+
+Set `allowAccountLinking: true` in `githubAuth` configuration.
+
+### Tokens not included in callback
+
+Tokens are in the URL fragment (`window.location.hash`), not the query string. If the callback
+returns JSON instead of redirecting, check that `allowedReturnTo` lists the `returnTo` origin and
+that a session middleware keeps `req.session` between `/auth/github` and the callback. A 400
+"returnTo is not an allowed redirect target" means the origin is not listed.
+
+## Learn More
+
+- [Authentication architecture](../explanation/authentication.md)
+- [API reference](../reference/api.md)
+- [GitHub OAuth documentation](https://docs.github.com/en/developers/apps/building-oauth-apps)

package/dist/docs/versioned/57.21.0/how-to/admin-add-model.md

@@ -0,0 +1,55 @@
+# Add a model to the admin
+
+Generic table/form routes are already in the host app. Do not add an Expo file per
+model. For screens and nav, see [Build admin screens](build-admin-screens.md).
+
+Add `admin` directly to the model's existing `modelRouter` options:
+
+```ts
+export const userRouter = modelRouter("/users", User, {
+  admin: {
+    displayName: "Users",
+    listFields: ["email", "name", "admin", "created"],
+    searchFields: ["email", "name"],
+    sortableFields: ["email", "name", "created"],
+    filters: [{field: "admin", kind: "boolean", label: "Admin user"}],
+  },
+  permissions: {
+    create: [Permissions.IsAdmin],
+    delete: [Permissions.IsAdmin],
+    list: [Permissions.IsAdmin],
+    read: [Permissions.IsAdmin],
+    update: [Permissions.IsAdmin],
+  },
+});
+```
+
+Register that router with `TerrenoApp`, then register `AdminApp`. The model appears in
+`GET /admin/config` and at `/admin/User` without a duplicate `AdminApp.models` entry.
+
+If the same Mongoose model is mounted at two `routePath`s (different filters or list
+columns), `/admin/config` keeps `name` as the model name for the registered entry and
+suffixes the others with the route slug (for example `Food-archived-foods`) so each list
+is reachable.
+
+Common fields:
+
+- `listFields`: columns and fields exposed to admin CRUD.
+- `searchFields`: string fields matched by the list search box (`q`) as a
+  case-insensitive partial (`$regex`) query.
+- `sortableFields`: the only columns with sorting enabled.
+- `filters`: typed list filters rendered on `DataTable` column headers (web) or the
+  mobile **Filters** sheet. `text` filters are case-insensitive contains (`$regex`);
+  `choice` filters support multi-select (`$in`); `ref` stays a single ObjectId. The
+  backend accepts only escaped literal regex patterns and rejects extra nested operators.
+  Optional choice fields (Mongoose path not `required`) automatically expose an **Empty**
+  filter option; set `allowEmpty: false` on the filter config to hide it, or
+  `allowEmpty: true` on required fields when you intentionally want unset matching.
+  Empty filters can be combined with toolbar search or concrete choices. The wire
+  sentinel is consumed before Mongo receives the query.
+- `fieldsets`: grouped form sections.
+- `readonlyFields` / `hiddenFields`: display-only or omitted form fields.
+- `adminPermissions`: optional per-action (`list`, `read`, `create`, `update`, `delete`)
+  permission methods. They run in addition to the admin check (`admin:access` plus the model's
+  RBAC action, or `IsAdmin`), so they can only restrict access. An empty array disables that
+  action, including `list` and `read`.