@terreno/mcp 58.0.0 → 58.0.2

package/dist/docs/versioned/57.18.0/explanation/authentication.md

@@ -1,497 +0,0 @@
-# Authentication Architecture
-
-Understanding how authentication works in @terreno/api — Better Auth sessions for new apps, with JWT/Passport documented for legacy consumers.
-
-## Overview
-
-**Better Auth is the default path** for new Terreno apps. It provides session-based authentication with MongoDB storage, built-in social OAuth (Google, GitHub, Apple), and clean integration with `@terreno/syncdb` (`betterAuthAdapter`, `RealtimeApp` socket sessions).
-
-Set `AUTH_PROVIDER=better-auth` and register `BetterAuthApp` on the server. On the client, use `createBetterAuthClient` + `generateBetterAuthSlice` from `@terreno/rtk` for session Redux state, then wire `betterAuthAdapter` into `createSyncDb`.
-
-**JWT/Passport (legacy)** remains supported through the current major release line for existing deployments. It uses stateless tokens, Passport strategies (email/password, GitHub OAuth, anonymous), and manual token refresh via `@terreno/rtk`. New projects should not start on JWT unless they have a specific requirement (custom token contracts, non-cookie clients, or a phased migration).
-
-Both systems can run in parallel during migration (`AUTH_PROVIDER` selects the primary path; legacy JWT routes stay available).
-
-**MCP service tokens** are a third, opt-in credential. They authenticate the consumer app's `POST /mcp` only. They are not Better Auth sessions, not JWTs, and not a REST personal-access-token. Enable them with `mcpServiceTokens` on `TerrenoApp`. Operator steps: [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md). **MCP OAuth access tokens** are the fourth, for remote clients that need an OAuth flow; enable them with `mcpOAuth` ([Enable MCP OAuth](../how-to/enable-mcp-oauth.md)).
-
-## When to choose which
-
-| Choose Better Auth | Stay on JWT (legacy) |
-|--------------------|----------------------|
-| New app or greenfield screen | Existing production JWT deployment |
-| Social login (Google, GitHub, Apple) | Custom JWT payload requirements |
-| `@terreno/syncdb` local-first data | Non-cookie API clients only |
-| Socket sessions via `RealtimeApp` | Gradual migration in progress |
-
-**Setup:** [Configure Better Auth](../how-to/configure-better-auth.md). **Data layer:** migrate auth before or with syncdb — see [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) §7.
-
-## Authentication Strategies
-
-### Better Auth (default)
-
-Modern session-based authentication with built-in social OAuth support.
-
-**Flow:**
-1. Configure Better Auth with `AUTH_PROVIDER=better-auth` and register `BetterAuthApp`
-2. User chooses social provider (Google, GitHub, Apple) or email/password
-3. Backend redirects to OAuth provider or validates credentials
-4. Better Auth creates session in MongoDB
-5. Frontend receives a session cookie (web, default), a bearer session token (native), or, on web with `webAuth: "bearer"`, a bearer token from the `set-auth-token` header. Bearer on web is the option when the web app and the API are on different sites, where browsers block the third-party session cookie. See [Frontend and API on different sites](../how-to/configure-better-auth.md#frontend-and-api-on-different-sites)
-6. On the first authenticated request or socket handshake, Terreno looks up the app `User` by `betterAuthId` and creates it if missing (`syncBetterAuthUser`). An email alone does not prove someone owns an existing account, so an existing app `User` with the same email is linked only after Better Auth verifies that email, and never when the row already belongs to another Better Auth account. Linking removes a legacy password the row never proved with a verified email. `RealtimeApp` uses the registered `BetterAuthApp` instance for socket sessions without extra wiring
-7. `req.user` is that app document for subsequent `modelRouter` permissions. A session whose app `User` has `disabled: true` no longer authenticates: `req.user` stays unset, so protected routes answer 401 and disabling an account ends its live sessions. Better Auth's own routes, such as sign-out, still work
-
-Email/password create omits `oauthProvider`. Apps that never use social login can keep `strict: "throw"` without declaring that field. OAuth create sets `oauthProvider` and the User schema must declare it.
-
-**Key properties:**
-- Session-based (cookies / bearer session) vs. stateless JWT
-- A session cookie is sent with requests other sites start, so a cookie-authenticated write counts only when it comes from a trusted origin. Bearer tokens are never sent automatically, so they need no such check
-- Built-in OAuth providers with PKCE
-- `betterAuthAdapter` for syncdb socket auth
-- `sync:auth-expired` socket event when the session is no longer valid
-
-**Endpoints (when enabled):**
-- `POST /api/auth/signup/email` — Email/password signup
-- `POST /api/auth/signin/email` — Email/password signin
-- `GET /api/auth/signin/{provider}` — Initiate OAuth flow (google, github, apple)
-- `GET /api/auth/callback/{provider}` — OAuth callback handler
-- `POST /api/auth/signout` — Sign out session
-- `GET /api/auth/session` — Get current session
-
-**Learn more:** [Configure Better Auth](../how-to/configure-better-auth.md)
-
-### Email/Password (JWT / Local Strategy — legacy)
-
-Traditional username/password authentication using `passport-local-mongoose`.
-
-**Flow:**
-1. User signs up with email and password
-2. Password is hashed with pbkdf2 (via passport-local-mongoose)
-3. User logs in with credentials
-4. Backend validates password and issues JWT tokens
-5. Frontend includes JWT in `Authorization` header for subsequent requests
-
-**Endpoints:**
-- `POST /auth/signup` — Create new user account
-- `POST /auth/login` — Authenticate and receive tokens
-
-### GitHub OAuth Strategy (JWT — legacy)
-
-OAuth 2.0 authentication with GitHub.
-
-**Flow:**
-1. User clicks "Sign in with GitHub"
-2. Frontend redirects to `GET /auth/github?returnTo=<url>`
-3. Backend redirects to GitHub authorization page
-4. User grants permissions on GitHub
-5. GitHub redirects back to `GET /auth/github/callback`
-6. Backend verifies authorization code with GitHub
-7. Backend finds/creates user, issues JWT tokens
-8. Backend redirects to `returnTo` with tokens in the URL fragment, only when `returnTo` matches
-   `githubAuth.allowedReturnTo`; otherwise it returns the tokens as JSON
-
-Every flow carries an OAuth `state` value bound to the starting browser by a signed, HttpOnly,
-short-lived cookie. The callback rejects a response without matching state.
-
-**Account Linking:**
-- Authenticated users can link their GitHub account via `GET /auth/github/link`. The bearer
-  user's ID is recorded in the signed state, and the callback links only to that user, never to
-  a session or token present on the callback request
-- Multiple authentication methods can be attached to one user account
-- Users must have a password set before unlinking GitHub
-
-**Learn more:** [How to add GitHub OAuth](../how-to/add-github-oauth.md)
-
-### MCP service tokens (opt-in, `/mcp` only)
-
-Personal `mcp_` keys for remote MCP clients (Perplexity, Cursor JSON config) that cannot hold a session cookie. `TerrenoApp` must set `mcpServiceTokens`. Users mint keys from `POST /mcp/service-tokens` or **Profile → MCP connections**. The plaintext secret is returned **once**; the database stores SHA-256 `tokenHash`.
-
-`extractUserFromHeaders` on `/mcp` tries a `mcp_` Bearer first, then Better Auth, then JWT. A match loads the owning `User` and updates `lastUsedAt`. Revoked, expired, or disabled-user keys resolve to no user, and so does a key minted before the user's last password reset or session revocation (`tokenEpoch` changed since it was issued). MCP OAuth grants end the same way. The same Bearer is ignored on REST, sync, admin, and on the mint/list/revoke routes (a key cannot mint another key).
-
-This is not OAuth 2.1; interactive clients use MCP OAuth below. It is also not the hosted `@terreno/mcp` codegen server ([MCP server reference](../reference/mcp-server.md)).
-
-**Learn more:** [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md)
-
-### MCP OAuth (opt-in, `/mcp` only)
-
-Claude.ai connectors and ChatGPT apps cannot paste a static key; they run OAuth 2.1 discovery, get a client id (pre-created by the app, or through dynamic client registration), and run the authorization-code flow with PKCE. With `mcpOAuth` on `TerrenoApp`, Terreno is that authorization server for a JWT app. Terreno is backend-only, so the app hosts the consent screen and approves or denies with the signed-in user's JWT. The client then gets opaque, short-lived `mcpat_` access tokens and rotating `mcprt_` refresh tokens, stored as hashes. On `/mcp`, `extractAuthFromHeaders` resolves `mcpat_` alongside the other credentials, and a request with none gets a `401` RFC 9728 challenge that starts discovery. OAuth access tokens are ignored on REST, like service tokens.
-
-Every part of it is opt-in. Without `mcpOAuth.enabled` there are no OAuth routes, discovery documents, or challenge. Dynamic client registration is a second flag (`dynamicClientRegistration`) because an open registration endpoint lets anyone create a client, which leaves the consent screen as the only defense against a phishing client. With it off, the app creates its clients as `McpOAuthClient` documents.
-
-Revocation works on token families: every pair rotated from one approval shares a `familyId`. Revoking a family writes a tombstone before revoking its pairs, and issuing into a tombstoned family fails, checked again after the new pair is written. That closes the races where a refresh or code exchange that already passed its single-use check would otherwise issue a live pair after a concurrent reuse revoked the family.
-
-**Learn more:** [Enable MCP OAuth for a JWT app](../how-to/enable-mcp-oauth.md)
-
-### Which credential authenticated the request
-
-`getCurrentRequestContext()?.credential` is `"jwt"`, `"better-auth-session"`, `"mcp-service-token"`, or `"oauth"`. Service tokens and OAuth tokens are delegated: an agent holds them on the user's behalf. Permission code that grants broad access (an admin bypass, cross-tenant reads) should check the credential and keep that access to the user's own session. See [Request credential](../reference/api.md#request-credential).
-
-### Anonymous Strategy (JWT — legacy)
-
-Allows limited access without authentication.
-
-**Use case:** Public read access to certain resources while requiring authentication for writes.
-
-``````typescript
-import {Permissions} from "@terreno/api";
-
-modelRouter(Model, {
-  permissions: {
-    list: [Permissions.IsAuthenticatedOrReadOnly],
-    read: [Permissions.IsAuthenticatedOrReadOnly],
-    create: [Permissions.IsAuthenticated],
-  },
-});
-``````
-
-## JWT Token System (legacy)
-
-> JWT/Passport auth is **legacy**. It remains supported through the current major line but is not the recommended path for new apps. Prefer Better Auth above.
-
-### Token Types
-
-**Access Token (short-lived)**
-- Default expiration: 15 minutes (`TOKEN_EXPIRES_IN`)
-- Used for API requests
-- Included in `Authorization: Bearer <token>` header (or the `jwt` cookie). Other
-  `Authorization` schemes are never read as a JWT
-- Contains user ID and permissions in payload
-- Rejected with 401 once the user is `disabled`. Login, refresh, password reset, and GitHub
-  sign-in also stop issuing tokens to a disabled user, so disabling an account ends its access
-
-**Refresh Token (long-lived)**
-- Default expiration: 30 days (`REFRESH_TOKEN_EXPIRES_IN`)
-- Used only to obtain new access tokens
-- Stored securely on client
-- Cannot be used for API requests
-
-### Token Payload
-
-Access tokens contain:
-
-``````json
-{
-  "sub": "507f1f77bcf86cd799439011",  // User ID
-  "admin": false,                      // Admin status
-  "iat": 1709000000,                   // Issued at (timestamp)
-  "exp": 1709000900,                   // Expires at (timestamp)
-  "iss": "your-app-name"               // Issuer (from TOKEN_ISSUER env var)
-}
-``````
-
-Customize the payload with `authOptions.generateJWTPayload`:
-
-``````typescript
-setupServer({
-  authOptions: {
-    generateJWTPayload: (user) => ({
-      sub: user._id,
-      admin: user.admin,
-      role: user.role,  // Custom field
-    }),
-  },
-});
-``````
-
-### Token Refresh Flow
-
-1. Access token expires (after 15 minutes)
-2. API request returns `401 Unauthorized`
-3. Frontend middleware detects 401
-4. Frontend calls `POST /auth/refresh_token` with refresh token
-5. Backend validates refresh token
-6. Backend issues new access token and refresh token
-7. Frontend retries original request with new token
-
-This is handled automatically by @terreno/rtk's `emptyApi` configuration.
-
-## Frontend Integration
-
-### Redux Store Setup (with @terreno/rtk)
-
-``````typescript
-import {generateAuthSlice} from "@terreno/rtk";
-import {configureStore} from "@reduxjs/toolkit";
-import {openapi} from "./openApiSdk";
-
-const {authReducer, middleware, logout} = generateAuthSlice(openapi);
-
-export const store = configureStore({
-  reducer: {
-    auth: authReducer,
-    [openapi.reducerPath]: openapi.reducer,
-  },
-  middleware: (getDefault) =>
-    getDefault().concat(openapi.middleware, ...middleware),
-});
-``````
-
-**What this provides:**
-- Automatic token storage (SecureStore on mobile, AsyncStorage on web)
-- Token refresh middleware
-- Login/logout state management
-- Auth header injection for all API requests
-
-### Token Storage
-
-**Mobile (iOS/Android):**
-- Uses `expo-secure-store` for encrypted storage
-- Tokens stored in device keychain
-
-**Web:**
-- Uses `@react-native-async-storage/async-storage`
-- Falls back to localStorage
-- SSR-safe (checks `typeof window`)
-
-**Storage keys:**
-- `AUTH_TOKEN` — Access token
-- `REFRESH_TOKEN` — Refresh token
-
-## Permission System
-
-Permissions control access to modelRouter endpoints.
-
-### Built-in Permissions
-
-| Permission | Description |
-|-----------|-------------|
-| `IsAny` | Always allows (public access) |
-| `IsAuthenticated` | Requires valid JWT (non-anonymous) |
-| `IsAdmin` | Requires `user.admin === true` |
-| `IsOwner` | Requires admin or `obj.ownerId === user.id` |
-| `IsAuthenticatedOrReadOnly` | Auth required for writes, anyone can read |
-| `IsOwnerOrReadOnly` | Owner or admin for writes, anyone can read |
-
-### Permission Evaluation
-
-Permissions are evaluated as an **AND** operation — all permissions in the array must return `true`:
-
-``````typescript
-permissions: {
-  update: [Permissions.IsAuthenticated, Permissions.IsOwner],
-  // Both conditions must be true
-}
-``````
-
-### Owner scope on writes
-
-Object permissions such as `IsOwner` first run against the document as it was loaded. On
-create and update, modelRouter also checks the document as it will be written. A user cannot
-create a record that names another user as `ownerId`, or move their own record to another
-user, even when the router has no `preUpdate` that strips `ownerId`. RBAC routers get the same
-check from their role scopes and `access.scope`. Admins can still reassign owners. See
-[modelRouter write scope](../reference/api.md#modelrouter-write-scope).
-
-### Custom Permissions
-
-Create custom permission functions:
-
-``````typescript
-const IsPremiumUser = (user, obj, method) => {
-  return user?.subscription === "premium";
-};
-
-modelRouter(Model, {
-  permissions: {
-    create: [Permissions.IsAuthenticated, IsPremiumUser],
-  },
-});
-``````
-
-### Why changing the email needs the current password
-
-The account email is where password-reset links go. If a session alone could change it, anyone
-holding a stolen or borrowed session could move the recovery address to a mailbox they control,
-request a reset, and keep the account after the session ends. So `PATCH /auth/me` asks for the
-current password before it changes the mailbox, and then tells the old address that the change
-happened. The notice holds no link or token, so forwarding it or leaving it in an inbox exposes
-nothing that acts on the account.
-
-The check uses whichever password the user has: the passport-local-mongoose hash, or, for a
-Better Auth user with no passport hash, the Better Auth credential. A user who signed up only
-through a social provider has no password to confirm, so they must set one through the reset
-flow first. Wrong attempts share the passport lockout with login rather than a separate counter.
-The new email is not held as pending and existing sessions are not ended; the notice to the old
-address is the signal that lets the owner react. Status codes and messages are in the
-[API reference](../reference/api.md#changing-the-email-on-patch-authme).
-
-## Security Best Practices
-
-### Backend
-
-✅ **Do:**
-- Use environment variables for secrets (`TOKEN_SECRET`, `REFRESH_TOKEN_SECRET`)
-- Set strong, unique secrets in production (at least 32 characters)
-- Use HTTPS in production
-- Validate token issuer (`TOKEN_ISSUER`)
-- Set appropriate token expiration times
-- Enable `TerrenoApp` `rateLimit` so login/signup/refresh use the stricter `auth` bucket (20 / 15 min). See [Rate limiting](../how-to/rate-limiting.md).
-- Keep login/signup/refresh reachable when the client still sends an expired access JWT. Those three routes skip JWT verification; `/auth/me` and other APIs still 401.
-- Log authentication failures
-
-❌ **Don't:**
-- Commit secrets to version control
-- Use the same secret for tokens and refresh tokens
-- Store sensitive data in JWT payload (it's base64, not encrypted)
-- Allow infinite token lifetimes
-
-### Frontend
-
-✅ **Do:**
-- Use SecureStore on mobile for token storage
-- Clear tokens on logout
-- Handle token expiration gracefully
-- Show user feedback during auth flows
-- Validate tokens before making authenticated requests
-
-❌ **Don't:**
-- Store tokens in localStorage on web when frontend and API share a site (use httpOnly cookies). When they are on different sites, Better Auth's `webAuth: "bearer"` mode is the supported way to keep a web token: it accepts the XSS and shared-device risk of web storage, and `bearerStorage: window.sessionStorage` narrows the second. See [Frontend and API on different sites](../how-to/configure-better-auth.md#frontend-and-api-on-different-sites)
-- Log tokens to console
-- Send tokens in URL query parameters (MCP service tokens included)
-- Ignore token refresh failures
-
-## Environment Variables
-
-Required for authentication:
-
-``````bash
-# JWT Configuration
-TOKEN_SECRET=your-secret-key-min-32-chars
-TOKEN_ISSUER=your-app-name
-REFRESH_TOKEN_SECRET=different-secret-key-min-32-chars
-SESSION_SECRET=session-secret-min-32-chars
-
-# Optional: Custom expiration times
-TOKEN_EXPIRES_IN=15m
-REFRESH_TOKEN_EXPIRES_IN=30d
-
-# GitHub OAuth (if using)
-GITHUB_CLIENT_ID=your_github_client_id
-GITHUB_CLIENT_SECRET=your_github_client_secret
-GITHUB_CALLBACK_URL=http://localhost:4000/auth/github/callback
-
-# Optional: Disable user registration
-SIGNUP_DISABLED=false
-``````
-
-## Authentication Middleware
-
-### Protecting Routes
-
-Use `authenticateMiddleware()` to require authentication:
-
-``````typescript
-import {authenticateMiddleware, asyncHandler} from "@terreno/api";
-
-router.get("/protected", [
-  authenticateMiddleware(),
-  asyncHandler(async (req, res) => {
-    // req.user is populated with authenticated user
-    const userId = req.user?._id;
-    return res.json({userId});
-  }),
-]);
-``````
-
-### Anonymous Access
-
-Allow unauthenticated requests but populate `req.user` if token is present:
-
-``````typescript
-router.get("/public", [
-  authenticateMiddleware({anonymous: true}),
-  asyncHandler(async (req, res) => {
-    // req.user is populated if token provided, undefined otherwise
-    const isLoggedIn = !!req.user;
-    return res.json({isLoggedIn});
-  }),
-]);
-``````
-
-## Troubleshooting
-
-### "Invalid token"
-
-- Token has expired — frontend should refresh
-- Token signature invalid — check `TOKEN_SECRET` matches
-- Token issuer mismatch — verify `TOKEN_ISSUER` is correct
-
-### "No auth token provided"
-
-- Missing `Authorization` header
-- Header format incorrect (should be `Bearer <token>`)
-
-### Token refresh fails
-
-- Refresh token expired — user must log in again
-- `REFRESH_TOKEN_SECRET` mismatch between token creation and validation
-- Refresh token revoked (user logged out)
-
-### User logged out unexpectedly
-
-- Access token expired and refresh failed
-- Backend `TOKEN_SECRET` changed (invalidates all tokens)
-- Token storage cleared (app reinstall, cache clear)
-
-## Advanced Topics
-
-### Custom User Fields in Token
-
-Add custom fields to JWT payload:
-
-``````typescript
-setupServer({
-  authOptions: {
-    generateJWTPayload: (user) => ({
-      sub: user._id,
-      admin: user.admin,
-      organizationId: user.organizationId,
-      roles: user.roles,
-    }),
-  },
-});
-``````
-
-### Multi-Tenant Authentication
-
-Scope users to organizations:
-
-``````typescript
-const queryFilter = (user, _query) => ({
-  organizationId: user?.organizationId,
-});
-
-modelRouter(Model, {
-  permissions: {list: [Permissions.IsAuthenticated]},
-  queryFilter,
-});
-``````
-
-### Webhook Authentication
-
-Verify signatures on `WebhooksApp` using `req.rawBody`. Do not `JSON.stringify(req.body)`
-and do not put webhook POSTs in OpenAPI.
-
-```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 () => undefined,
-});
-
-new TerrenoApp({userModel: User}).register(webhooks).start();
-```
-
-See [Receive inbound webhooks](../how-to/inbound-webhooks.md).
-
-## Learn More
-
-- [Receive inbound webhooks](../how-to/inbound-webhooks.md)
-- [Add GitHub OAuth](../how-to/add-github-oauth.md)
-- [Create a model](../how-to/create-a-model.md)
-- [API reference](../reference/api.md)
-- [@terreno/rtk reference (legacy)](../reference/legacy/rtk.md)

package/dist/docs/versioned/57.18.0/explanation/dependency-management.md

@@ -1,104 +0,0 @@
-# Dependency Management
-
-Terreno pins shared versions in the Bun catalog, lands routine JavaScript updates
-through an agent skill that proves each bump with a test, limits Dependabot to
-security fixes, and keeps Expo native fingerprints frozen until a release.
-
-## Layers
-
-| Layer | Job |
-| --- | --- |
-| **Bun catalog** | One version for every dependency shared by two or more workspace packages (`catalog:` in manifests) |
-| **`update-dependencies` skill** | The only path for routine version upgrades. Daily rolling PR on `chore/update-dependencies`: cooldown, exercise test, local gate, one push per run, fingerprint freeze, ledger of landed/failed |
-| **Dependabot** | Security updates only for bun + GitHub Actions. Native/Expo catalog names are ignored so auto-merge cannot change the fingerprint |
-| **Release + `upgrading-expo`** | Expo SDK, React Native, and other native-module bumps |
-
-Operator steps: [Update dependencies](../how-to/update-dependencies.md). Catalog rule: workspace `package.json` files use `"catalog:"` for shared pins.
-
-## Bun catalogs
-
-Shared versions live in the root `package.json` `catalog` field.
-
-```json
-{
-  "catalog": {
-    "react": "19.1.0",
-    "react-native": "0.81.5"
-  }
-}
-```
-
-```json
-{
-  "dependencies": {
-    "react": "catalog:",
-    "react-native": "catalog:"
-  }
-}
-```
-
-Change a shared version in the catalog once. Do not pin a second copy in a workspace package. Exceptions (`@types/node`, `path-to-regexp`, `@opentelemetry/sdk-node`) are listed in `.rulesync/rules/01-dependency-catalog.md`.
-
-## Agent updates vs Dependabot
-
-Dependabot version updates group many packages and merge when CI is green. That misses Terreno constraints, so Dependabot now opens security PRs only:
-
-1. **Exercise.** CI can pass without any test importing the bumped module. The skill requires a named test file that imports the package and that passed **after** the bump. If none exists, write a tracer-bullet test first.
-2. **Fingerprint.** Expo `runtimeVersion.policy: "fingerprint"` ties OTA runtime and EAS dev builds to native hashes of `example-frontend` and `demo`. Native module bumps belong in a release, not a weekday dependency PR.
-
-3. **CI is not the test runner.** A red grouped Dependabot PR invites an agent to push fix after fix to the Dependabot branch. Each push starts a full CircleCI pipeline that is attributed to, and emails, whoever owns the pushing token. The skill runs the CI mirror (`bun run prepush`) locally, pushes once per run, never edits CI config to make a bump pass, and stops after two red CI rounds.
-
-`scripts/planning/fingerprintRisk.ts` (`isFingerprintSkip`) is the skip matcher. After every allowed bump the skill still recomputes hashes; a changed hash is reverted even if the matcher allowed the name.
-
-## Cooldown
-
-Non-security npm versions wait **7 days** after publish before a bump (`npm view <name> time`). Most malicious publishes are yanked inside a day. CVE/advisory bumps skip the wait and still need an exercise test and a fingerprint freeze. Dependabot security updates are advisory bumps, so they have no cooldown.
-
-## Fingerprint freeze
-
-Do not bump from this path:
-
-- `expo`, `expo-*`, `react-native`, `react-native-*` except `react-native-web`
-- `@react-native/*` and related community native modules
-- `@expo/config-plugins`, `@sentry/react-native`, `@shopify/flash-list`, `@shopify/react-native-skia`
-- `eas.json` Bun version (it is a fingerprint input)
-
-Those wait for a Terreno release (`release` + `upgrading-expo` skills). Do not use the `fingerprint-acknowledged` label to sneak them through a dependency PR.
-
-JavaScript packages, GitHub Actions, and a few Expo JS-only names may update. Measure hashes for both apps anyway.
-
-## Dependabot configuration
-
-`.github/dependabot.yml` sets `open-pull-requests-limit: 0` on every block. That turns off version-update PRs; security updates ignore the limit and still honor `ignore`. Each block's group uses `applies-to: security-updates`, so fixes arrive grouped:
-
-| Group | Ecosystem |
-| --- | --- |
-| `github-actions` | `github-actions` at `/` |
-| `root` | `bun` at `/` (root catalog and root tools) |
-| `backend` | `bun` under api, ai, backends, … |
-| `frontend` | `bun` under ui, rtk, demo, apps, … |
-
-Frontend ignores catalog-managed names so those fixes land once, in the root catalog. Root ignores fingerprint-skip names, so a security fix for a native/Expo package never opens a PR; handle it by hand in a release. `dependabot-auto-merge.yml` approves patch and minor Dependabot PRs and enables squash auto-merge, so those security PRs merge when required checks pass. A semver-major security PR (or a group containing one) gets no approval or auto-merge and waits for a human. When one fails because the fix needs code changes, fold the bump into the rolling PR ([Update dependencies](../how-to/update-dependencies.md)); never push to the `dependabot/*` branch.
-
-## Daily rolling PR
-
-The skill runs every day against **one trusted** open PR: exact same-repository head `chore/update-dependencies`, base `master`, and `isCrossRepository: false`. The marker `<!-- terreno-update-dependencies -->` and title are display metadata, not trust signals. Forks that copy them are ignored.
-
-A later run merges current master into that branch without rewriting history, retries **Failed** rows, appends **Landed** / **Failed** / **Skipped**, and pushes to the same head. It does not open a second trusted PR while that one is open. After merge, the next day may open the next rolling PR.
-
-Each package is still proven alone (exercise test + fingerprint) before it stays on the branch. Failures are reverted and kept in the PR body so the next day does not rediscover them from scratch.
-
-## Best practices
-
-- One rolling PR; many proven commits on that branch.
-- Majors: exercise test + fingerprint freeze; no auto-merge.
-- Security: skip cooldown; do not skip tests or fingerprints.
-- Verify locally, push once; never change CI config to make a bump pass.
-- New feature dependencies belong in that feature's slice, not this maintenance path.
-
-## Related
-
-- [Update dependencies](../how-to/update-dependencies.md)
-- [Run tests locally](../how-to/run-tests-locally.md)
-- [Install agent skills](../how-to/install-agent-skills.md)
-- [Bun catalogs](https://bun.sh/docs/install/catalogs)

package/dist/docs/versioned/57.18.0/explanation/deployment-baseline.md

@@ -1,78 +0,0 @@
-# Deployment baseline
-
-Every Terreno production deployment needs the same seven foundations. Provider guides ([Deploy to GCP](../how-to/deploy-to-gcp.md), [Deploy to Vercel](../how-to/deploy-to-vercel.md)) map these to specific platforms; this page names them once.
-
-See also the [environment variables reference](../reference/environment-variables.md).
-
-## Seven baseline requirements
-
-| # | Requirement | Why Terreno needs it | When missing |
-|---|-------------|----------------------|--------------|
-| 1 | **MongoDB replica set** | Change streams power realtime and live feature-flag updates | Startup logs: `FeatureFlag.watch() failed — live updates require MongoDB as a replica set` (`feature-flags/src/featureFlagsApp.ts`) |
-| 2 | **Auth secrets** | JWT signing and sessions (or Better Auth encryption) | Login fails; tokens rejected |
-| 3 | **Long-lived backend process** | Socket.io connections are not request/response | Websockets drop on platforms with short request timeouts or aggressive scale-to-zero |
-| 4 | **Correct origins** | CORS and Better Auth `trustedOrigins` must include your web and native schemes | Browser: blocked by CORS; native: auth redirects fail |
-| 5 | **Build-time client config** | `EXPO_PUBLIC_*` values are inlined into the web bundle at build time | API calls go to `undefined` or localhost after deploy — see [Build for web](../how-to/build-for-web.md) |
-| 6 | **Health endpoint** | Load balancers and orchestrators need readiness probes | Platform marks the service unhealthy and stops routing traffic |
-| 7 | **Durable file storage** | Uploads must not live on ephemeral container disk | Files disappear on restart; use GCS/S3 and credentials |
-
-Requirements **1**, **3**, and **5** are the ones teams miss most often.
-
-### Symptom details
-
-**1 — Standalone MongoDB**
-
-Terreno's feature-flag plugin opens a change stream on startup. Without a replica set, live flag sync is disabled and logs:
-
-```text
-[feature-flags] FeatureFlag.watch() failed — live updates require MongoDB as a replica set (even single-node).
-```
-
-Use [MongoDB Atlas](https://www.mongodb.com/atlas) or a single-node replica set for development.
-
-**3 — Short-lived serverless timeouts**
-
-The RTK/socket client enables reconnection (`reconnection: true`, `reconnectionAttempts: 5` in `rtk/src/socket.ts`). When the backend drops idle connections (for example Cloud Run's default 300s request timeout), clients reconnect but realtime state may lag until the new socket attaches.
-
-**5 — Build-time API URL**
-
-If you set `EXPO_PUBLIC_API_URL` only at runtime on the static host, the bundle still contains whatever was present at `bun run export` time — often `http://localhost:4000`. The browser then fails network requests against localhost.
-
-## Web output modes
-
-Expo Router supports three web output modes. The choice determines hosting options.
-
-| Mode | Output | API routes | SSR | Hosting | Terreno status |
-|------|--------|-----------|-----|---------|----------------|
-| `single` | One `index.html` SPA | No | No | Any static host | Expo's default |
-| `static` | Per-route HTML files | No | No | Any static host | Used by `example-frontend` and `demo`; better SEO |
-| `server` | `dist/client` + `dist/server` | Yes | Yes (alpha, SDK ≥ 55) | Node/Bun/edge runtime | Available (repo catalog is Expo `~57.0.14`) but unused; see [Deploy to Vercel](../how-to/deploy-to-vercel.md#advanced-server-output) and [Web SSR and admin SPA](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md) |
-
-## Multi-environment checklist
-
-Staging and production differ in these values (each environment needs its **own web build** because of `EXPO_PUBLIC_API_URL`):
-
-| Item | Where to configure |
-|------|-------------------|
-| Secret values | Platform secret store / Secret Manager |
-| `MONGO_URI` | Separate cluster or database per environment |
-| `EXPO_PUBLIC_API_URL` | Set before `bun run export` — one build per environment |
-| `corsOrigin` | `setupServer({ corsOrigin })` in backend |
-| Better Auth `trustedOrigins` + `BETTER_AUTH_URL` | Better Auth config / env |
-| Feature-flag defaults | MongoDB documents or seed scripts |
-
-## Containerizing the backend
-
-The canonical Dockerfile is [`example-backend/Dockerfile`](https://github.com/TerrenoLabs/terreno/blob/master/example-backend/Dockerfile). It:
-
-1. Installs workspace dependencies and compiles packages in dependency order.
-2. Builds a Bun-compiled binary for production.
-3. Runs as a non-root user and exposes `/health` via `@terreno/api-health`.
-
-Three details consumers get wrong:
-
-- **`PORT`** — Cloud Run and other platforms assign the listen port via `PORT`. Terreno reads `process.env.PORT` in `api/src/terrenoApp.ts` (default `9000` if unset).
-- **Non-root** — Do not run the container as root in production.
-- **Compile order** — Workspace packages (`@terreno/api`, `@terreno/jobs`, `@terreno/test`, etc.) must compile before the example backend bundles. Compile `@terreno/jobs` before `@terreno/admin-backend` — admin-backend imports jobs. The image `exports` point at `dist/`, so skipping a workspace compile fails `bun build --compile` with an unresolved `@terreno/*` import.
-
-CI builds the image on every PR that touches backend paths (`.github/workflows/example-backend-docker.yml`).