@terreno/mcp 57.20.0 → 57.21.0

package/dist/docs/versioned/57.20.0/reference/environment-variables.md

@@ -0,0 +1,352 @@
+# Environment Variables Reference
+
+Comprehensive guide to environment variables used across Terreno packages and example applications.
+
+> **Build-time client variables:** `EXPO_PUBLIC_*` variables are inlined into the JavaScript bundle at **build** time. They are not secrets and cannot be changed without rebuilding the web or native export. Set `EXPO_PUBLIC_API_URL` before `bun run export`, not on the hosting platform after deploy.
+
+## Table columns
+
+| Column | Meaning |
+|--------|---------|
+| **Read by** | Package or app that reads the variable |
+| **Required** | Must be set for production use |
+| **Secret** | Treat as credential — never commit or expose in client bundles |
+| **Scope** | `server` = backend runtime; `client` = build-time (inlined); `tooling` = CI/scripts/tests only |
+
+## Database
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `MONGO_URI` | `@terreno/api`, example-backend | ✅ prod | `mongodb://localhost:27017` | Yes | server |
+| `MONGODB_URI` | tests, scripts | ❌ | — | Yes | tooling |
+| `TEST_MONGO_URI` | example-backend tests | ❌ | `mongodb://localhost:27017/test` | Yes | tooling |
+| `TERRENO_TEST_MONGODB_URI` | `@terreno/test` | ❌ | auto | Yes | tooling |
+| `TERRENO_TEST_USE_MEMORY_MONGO` | `@terreno/test` | ❌ | — | No | tooling |
+| `TERRENO_TEST_USE_REPLSET` | `@terreno/test` | ❌ | — | No | tooling |
+| `TERRENO_TEST_MONGO_LAUNCH_TIMEOUT_MS` | `@terreno/test` | ❌ | `60000` | No | tooling |
+| `TERRENO_TEST_USE_FIXTURE_CACHE` | `@terreno/test` | ❌ | — | No | tooling |
+| `TERRENO_TEST_CACHE_DIR` | `@terreno/test` | ❌ | — | No | tooling |
+| `BUN_TEST_DISABLE_DB` | test harness | ❌ | — | No | tooling |
+| `DEBUG_MONGO_PRELOAD` | tests | ❌ | — | No | tooling |
+| `DEBUG_TEST_TRANSACTION` | tests | ❌ | — | No | tooling |
+
+## Auth — JWT
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `AUTH_PROVIDER` | `@terreno/api` | ❌ | `jwt` | No | server |
+| `TOKEN_SECRET` | `@terreno/api` | ✅ if JWT | — | Yes | server |
+| `TOKEN_ISSUER` | `@terreno/api` | ✅ if JWT | — | No | server |
+| `REFRESH_TOKEN_SECRET` | `@terreno/api` | ✅ if JWT | — | Yes | server |
+| `SESSION_SECRET` | `@terreno/api` | ✅ if JWT | — | Yes | server |
+| `TOKEN_EXPIRES_IN` | `@terreno/api` | ❌ | `15m` | No | server |
+| `REFRESH_TOKEN_EXPIRES_IN` | `@terreno/api` | ❌ | `30d` | No | server |
+| `SIGNUP_DISABLED` | `@terreno/api` | ❌ | `false` | No | server |
+
+## Auth — Better Auth
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `BETTER_AUTH_SECRET` | `@terreno/api`, example-backend | ✅ if Better Auth | example-backend outside production: a published dev-only value. With `NODE_ENV=production`, example-backend refuses to start when it is unset or equals that value | Yes | server |
+| `BETTER_AUTH_URL` | `@terreno/api` | ✅ if Better Auth | — | No | server |
+| `GOOGLE_CLIENT_ID` | `@terreno/api` | ❌ | — | No | server |
+| `GOOGLE_CLIENT_SECRET` | `@terreno/api` | ❌ | — | Yes | server |
+| `APPLE_CLIENT_ID` | `@terreno/api` | ❌ | — | No | server |
+| `APPLE_CLIENT_SECRET` | `@terreno/api` | ❌ | — | Yes | server |
+| `GITHUB_CLIENT_ID` | `@terreno/api` | ❌ | — | No | server |
+| `GITHUB_CLIENT_SECRET` | `@terreno/api` | ❌ | — | Yes | server |
+| `GITHUB_CALLBACK_URL` | `@terreno/api` | ❌ | — | No | server |
+| `AUTH_ACCOUNT_LINKING` | example-backend `accountLinking.mode`: `verified-email`, `explicit`, or `never` ([details](../how-to/configure-better-auth.md#auth-features-in-example-backend)) | ❌ | `verified-email` | No | server |
+| `AUTH_SIGN_UP` | example-backend `signUp.mode`: `open` or `closed` ([details](../how-to/configure-better-auth.md#auth-features-in-example-backend)) | ❌ | `open` | No | server |
+| `PASSKEY_RP_ID` | example-backend `passkey.rpID`: the `FRONTEND_URL` host or a parent domain of it ([details](../how-to/configure-better-auth.md#auth-features-in-example-backend)) | ❌ | the `FRONTEND_URL` host | No | server |
+
+## Server configuration
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `PORT` | `@terreno/api` (`terrenoApp.ts`) | ❌ | `9000` | No | server |
+| `NODE_ENV` | various | ❌ | `development` | No | server |
+| `HOST` | servers | ❌ | all interfaces | No | server |
+| `ENABLE_SWAGGER` | `@terreno/api` | ❌ | `false` | No | server |
+| `APP_ENV` | example-backend | ❌ | `development` | No | server |
+| `BACKEND_URL` | scripts, deploy | ❌ | — | No | server |
+| `FRONTEND_URL` | example-backend `publicAppUrl` (auth mail links), the first passkey origin, and the default `PASSKEY_RP_ID` (its host). In production a loopback value turns passkeys off ([Auth features in example-backend](../how-to/configure-better-auth.md#auth-features-in-example-backend)) | ❌ (✅ for passkeys on a deploy) | `http://localhost:8082` | No | server |
+| `CORS_ORIGINS` | example-backend (`utils/betterAuthConfig.ts`) | ✅ for deployed web origins | localhost:8082 origins only | No | server |
+| `CROSS_DOMAIN_AUTH_COOKIES` | example-backend Better Auth config | ❌ | `false` | No | server |
+| `API_URL` | microservice split | ❌ | — | No | server |
+| `DISABLE_LOG_ALL_REQUESTS` | `@terreno/api` logging | ❌ | — | No | server |
+| `TERRENO_BROWSER_LOGS` | `@terreno/api` `TerrenoApp` (`POST /__terreno/browser-logs`) | ❌ | on only when `NODE_ENV=development`. `false`/`0` turns it off. `true`/`1` turns it on in any non-production environment. Ignored when `NODE_ENV=production`: the route is never registered and returns 404. See [Development browser-log ingestion](api.md#development-browser-log-ingestion). | 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 |
+
+`CORS_ORIGINS` is comma-separated. An entry may contain `*` (for example `https://*.preview.example.com`); use it only on a domain you control, never on a shared namespace like `vercel.app`. For `corsOrigin`, `*` becomes a `RegExp` that matches letters, digits, and hyphens but never a dot. Better Auth `trustedOrigins` receives the raw pattern and applies its own, broader wildcard matching. Never use `corsOrigin: true` in production; see [Deploy to Vercel](../how-to/deploy-to-vercel.md#cors). Set `CROSS_DOMAIN_AUTH_COOKIES=true` when the web app and API are on different sites.
+
+## Client / build-time
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `EXPO_PUBLIC_API_URL` | `@terreno/rtk` | ✅ prod web | dev auto-detect | No | **client** |
+| `EXPO_PUBLIC_DEV_API_PORT` | `@terreno/rtk` | ❌ | `4000` | No | **client** |
+| `EXPO_PUBLIC_BUILD_NUMBER` | example-frontend | ❌ | — | No | **client** |
+| `OPENAPI_URL` | example-frontend `sdk` script | ❌ | `http://localhost:4000/openapi.json` | No | tooling |
+
+### `app.json` `extra` (not `process.env`)
+
+Configured in `expo.extra` and read via `expo-constants`:
+
+| Key | Read by | Notes |
+|-----|---------|-------|
+| `BASE_URL` | `@terreno/rtk` | Production fallback when `EXPO_PUBLIC_API_URL` unset; use `__SAME_ORIGIN__` for same-origin admin SPA |
+| `DEV_API_PORT` | `@terreno/rtk` | Override dev API port (mirrors `EXPO_PUBLIC_DEV_API_PORT`) |
+| `AUTH_DEBUG` | `@terreno/rtk` | `"true"` enables auth debug logs |
+| `WEBSOCKETS_DEBUG` | `@terreno/rtk` | `"true"` enables socket debug logs |
+| `SOCKET_TRANSPORTS` | example-frontend (`store/socketTransports.ts`) | Comma-separated Socket.IO transports passed to `useSocketConnection({transports})` and `createSyncDb({socketTransports})`. Unset keeps `polling,websocket`; the Vercel build sets `websocket` |
+| `APP_ENV` | `@terreno/rtk` | Logged at startup |
+
+Resolution order for API base URL (`rtk/src/constants.ts`):
+
+1. `EXPO_PUBLIC_API_URL` (production and dev)
+2. `extra.BASE_URL` (production only, when env unset)
+3. Dev fallbacks: `hostUri`, experience URL, `localhost`
+
+`EXPO_PUBLIC_API_URL` is inlined only into app source. Code under `node_modules`, including `@terreno/rtk`, does not see the inlined value in a production export and falls back to `extra.BASE_URL`, so set both for production web builds. `example-frontend/scripts/vercelBuild.ts` writes `extra.BASE_URL` from `EXPO_PUBLIC_API_URL` before `expo export`.
+
+### Per-environment values on hosting platforms
+
+Hosting platforms scope variables per environment. Vercel has **Production**, **Preview**, and **Development** scopes; set `EXPO_PUBLIC_API_URL` in each so each build points at its own backend. Because the value is inlined at build time, promoting a preview build to production keeps the preview backend URL. Rebuild for production instead. See [Deploy to Vercel](../how-to/deploy-to-vercel.md#configure-each-environment) and the [multi-environment checklist](../explanation/deployment-baseline.md#multi-environment-checklist).
+
+## Development tooling
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `TERRENO_PROJECT_ROOT` | `terreno-mcp-local`, `terreno` CLI | ❌ | nearest Terreno project root | No | tooling |
+| `TERRENO_METRO_URL` | `terreno-mcp-local` | ❌ | frontend script port or `http://localhost:8082` | No | tooling |
+| `TERRENO_MCP_EVAL` | `terreno-mcp-local` | ❌ | disabled | No | tooling |
+| `TERRENO_WEB_URL` | `terreno` CLI | ❌ | `http://localhost:8082` | No | tooling |
+| `BUN_CHROME_PATH` | Bun WebView | ❌ | browser auto-discovery | No | tooling |
+| `TERRENO_OPENAPI` | `terreno` CLI | ❌ | — | No | tooling |
+| `TERRENO_API_URL` | `terreno` CLI | ❌ | OpenAPI `servers[0].url` | No | tooling |
+| `TERRENO_TOKEN` | `terreno` CLI | ❌ | — | Yes | tooling |
+
+## AI
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `GEMINI_API_KEY` | `@terreno/ai` | ❌ | — | Yes | server |
+| `OPENAI_API_KEY` | `@terreno/ai` | ❌ | — | Yes | server |
+| `GOOGLE_VERTEX_PROJECT` | `@terreno/ai` | ❌ | — | No | server |
+| `GOOGLE_VERTEX_LOCATION` | `@terreno/ai` | ❌ | `global` | No | server |
+| `GOOGLE_VERTEX_ALLOWED_MODELS` | `@terreno/ai` | ❌ | all | No | server |
+| `CLAUDE_KEY` | tooling | ❌ | — | Yes | tooling |
+| `LANGFUSE_SECRET_KEY` | `@terreno/ai` | ❌ | — | Yes | server |
+| `LANGFUSE_PUBLIC_KEY` | `@terreno/ai` | ❌ | — | No | server |
+| `LANGFUSE_BASE_URL` | `@terreno/ai` | ❌ | — | No | server |
+| `LANGFUSE_ORGANIZATION` | `@terreno/ai` | ❌ | — | No | server |
+| `LANGFUSE_PROJECT` | `@terreno/ai` | ❌ | — | No | server |
+| `LANGFUSE_PROJECT_ID` | `@terreno/ai` | ❌ | — | No | server |
+
+## Storage (GCS)
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `GCS_BUCKET` | example-backend, admin | ❌ | — | No | server |
+| `GCS_FOLDER_PREFIX` | example-backend `DocumentStorageApp` (`folderPrefix`) | ❌ | — | No | server |
+| `GCS_PROJECT_ID` | GCS clients | ❌ | — | No | server |
+| `GCS_SERVICE_ACCOUNT_KEY` | GCS clients | ❌ | — | Yes | server |
+
+Example-backend Cloud Run deploys set `GCS_BUCKET` (default `flourish-terreno-example-documents`). Preview deploys also set `GCS_FOLDER_PREFIX=pr-<number>/`.
+
+## Feature flags
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `FEATURE_FLAGS_DEBUG` | `@terreno/feature-flags` | ❌ | — | No | server |
+
+## Communications
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `COMMS_ENABLED` | example-backend | ❌ | `true` | No | server |
+| `COMMS_DEFAULT_FROM` | example-backend / `@terreno/comms` | ❌ | — | No | server |
+| `COMMS_DEFAULT_FROM_NAME` | example-backend | ❌ | — | No | server |
+| `SENDGRID_API_KEY` | `@terreno/comms/adapters/sendgrid` | ❌ | — | Yes | server |
+| `SENDGRID_WEBHOOK_VERIFICATION_KEY` | `@terreno/comms/adapters/sendgrid` | ❌ | — | Yes | server |
+| `SENDGRID_SANDBOX_MODE` | example-backend | ❌ | — | No | server |
+| `TWILIO_ACCOUNT_SID` | `@terreno/comms/adapters/twilioSms`, `@terreno/comms/adapters/twilioVerify` | ❌ | — | Yes | server |
+| `TWILIO_AUTH_TOKEN` | `@terreno/comms/adapters/twilioSms`, `@terreno/comms/adapters/twilioVerify` | ❌ | — | Yes | server |
+| `TWILIO_MESSAGING_SERVICE_SID` | `@terreno/comms/adapters/twilioSms` | ❌ | — | No | server |
+| `TWILIO_FROM_NUMBER` | `@terreno/comms/adapters/twilioSms` | ❌ | — | No | server |
+| `TWILIO_VERIFY_SERVICE_SID` | `@terreno/comms/adapters/twilioVerify` | ❌ | — | No | server |
+| `EXPO_ACCESS_TOKEN` | `@terreno/comms/adapters/expoPush` | ❌ | — | Yes | server |
+| `PUBLIC_API_URL` | `@terreno/comms` Twilio webhooks | ❌ | — | No | server |
+| `COMMS_WEBHOOK_PUBLIC_URL` | `@terreno/comms` Twilio webhooks | ❌ | — | No | server |
+
+Set `COMMS_ENABLED=false` to omit the example backend's communications plugin and routes.
+When `SENDGRID_API_KEY` is set, the example backend registers `SendGridMailProvider`
+(optional peer `@sendgrid/mail`). Without a key, non-production environments keep the
+console mail provider; production leaves mail unconfigured until a provider is wired.
+`SENDGRID_SANDBOX_MODE=true` forces SendGrid sandbox mode for non-test runtimes.
+`SENDGRID_WEBHOOK_VERIFICATION_KEY` (or constructor `webhookVerificationKey`) is the
+SendGrid Event Webhook ECDSA public key. Missing it skips `POST /comms/webhooks/sendgrid`.
+`PUBLIC_API_URL` or `COMMS_WEBHOOK_PUBLIC_URL` is the public HTTPS origin used to sign
+Twilio callbacks (no trailing slash). Missing it skips Twilio webhook routes.
+Sender identity must be verified in SendGrid before real delivery works.
+When `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` are set with
+`TWILIO_MESSAGING_SERVICE_SID` or `TWILIO_FROM_NUMBER`, the example backend registers
+`TwilioSmsProvider` (optional peer `twilio`). A sender var without those credentials
+throws at startup. Shared account credentials without a sender do not enable SMS — they
+can still enable Verify when `TWILIO_VERIFY_SERVICE_SID` is set. Without an SMS sender,
+non-production keeps the console SMS provider; production omits SMS until a sender is wired.
+When `TWILIO_VERIFY_SERVICE_SID` is set with `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN`,
+the example backend registers `TwilioVerifyProvider`. A verify service SID without those
+credentials throws at startup. Without `TWILIO_VERIFY_SERVICE_SID`, non-production keeps
+the console verification provider; production omits verification until a provider is wired.
+`EXPO_ACCESS_TOKEN` is optional; the example backend always registers
+`ExpoPushProvider` when comms is enabled, with a statically imported `Expo`
+client so the compiled Cloud Run binary includes `expo-server-sdk`. Without a
+token, Expo still accepts sends at a lower rate limit. The example backend also
+depends on `twilio` and injects a statically imported client into
+`TwilioSmsProvider` / `TwilioVerifyProvider` when those env vars are complete,
+so the compiled binary includes the SDK. Non-production also mounts `POST /comms/dev/testPush`
+for authenticated test sends.
+
+## Observability
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `SENTRY_DSN` | `@terreno/api`, frontends | ❌ | — | No | server / client |
+| `SENTRY_ENVIRONMENT` | Sentry SDK | ❌ | — | No | server |
+| `SENTRY_TRACES_SAMPLE_RATE` | Sentry SDK | ❌ | — | No | server |
+| `USE_SENTRY_LOGGING` | `@terreno/api` | ❌ | `false` | No | server |
+| `SLOW_REQUEST_THRESHOLD_MS` | `@terreno/api` | ❌ | `5000` | No | server |
+| `SLOW_DB_QUERY_THRESHOLD_MS` | `@terreno/api` | ❌ | `100` | No | server |
+| `TERRENO_LOG_FILE` | `@terreno/api` logger | ❌ | on unless `NODE_ENV=production`. An on/off switch, not a path: `false`/`0` turns it off, and `true`/`1` turns it on even in production. Writes JSONL to `<cwd>/.terreno/logs/app.log`. | No | server |
+| `TRACE_SAMPLING_RATE` | example-backend OTEL | ❌ | `0.1` | No | server |
+| `MEMORY_SAMPLE_INTERVAL_MS` | example-backend | ❌ | `60000` | No | server |
+| `JOB_TRACE_LOGS` | workers | ❌ | — | No | server |
+
+## Caching
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `VALKEY_URL` | `@terreno/api` realtime adapter **and** `rateLimit.store: "redis"` | ❌ | — | Yes | server |
+| `REDIS_URL` | `@terreno/api` fallback after `VALKEY_URL` (realtime + Redis rate-limit store) | ❌ | — | Yes | server |
+
+There is **no** `RATE_LIMIT_ENABLED` (or similar) read by `@terreno/api`. Apps that want an env toggle pass `rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined` themselves. See [Rate limiting](../how-to/rate-limiting.md).
+
+## Webhooks & notifications
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `SLACK_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
+| `SLACK_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
+| `SLACK_BOT_TOKEN` | `@terreno/api` Slack Web API (`lookupSlackUserIdByEmail`, private channels, invites, `chat.postMessage`) | ❌ | — | Yes | server |
+| `GOOGLE_CHAT_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
+| `GOOGLE_CHAT_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
+| `ZOOM_CHAT_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
+| `ZOOM_WEBHOOK_URL` | scripts | ❌ | — | Yes | server |
+| `WEBHOOK_SECRET` | example-backend HMAC demo | ❌ | — | Yes | server |
+
+`WEBHOOK_SECRET` is read only by the example HMAC route (`POST /webhooks/example`).
+`@terreno/api` `WebhooksApp` does not read it. Twilio/SendGrid inbound paths use adapter
+secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
+[Receive inbound webhooks](../how-to/inbound-webhooks.md).
+
+## Admin SPA
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `ADMIN_SPA_ENABLED` | example-backend | ❌ | — | No | server |
+| `ANNOUNCEMENTS_UPLOAD_TOKEN` | example-backend `AnnouncementsApp` | ❌ | example deploy: `terreno-example-announcement-upload` | Yes outside the example app | server |
+| `ADMIN_SPA_DIST_DIR` | example-backend Dockerfile | ❌ | — | No | server |
+| `ADMIN_SPA_DEV_PROXY` | admin-spa plugin | ❌ | — | No | server |
+| `ADMIN_SPA_BACKEND_URL` | admin-spa tests | ❌ | — | No | tooling |
+| `ADMIN_SPA_E2E_EMAIL` | e2e | ❌ | — | No | tooling |
+| `ADMIN_SPA_E2E_PASSWORD` | e2e | ❌ | — | Yes | tooling |
+
+## MCP server
+
+| Variable | Read by | Required | Default | Secret | Scope |
+|----------|---------|----------|---------|--------|-------|
+| `MCP_SERVER_URL` | MCP clients | ❌ | — | No | tooling |
+| `TERRENO_MCP_DOCS_DIR` | `@terreno/mcp` | ❌ | — | No | tooling |
+| `TERRENO_MCP_EVAL` | MCP eval | ❌ | — | No | tooling |
+| `TERRENO_PROJECT_ROOT` | MCP local | ❌ | — | No | tooling |
+| `TERRENO_MCP_RATE_LIMIT_MAX` | `@terreno/mcp` hosted server | ❌ | `120` (`0` disables) | No | server |
+| `TERRENO_MCP_RATE_LIMIT_WINDOW_MS` | `@terreno/mcp` hosted server | ❌ | `60000` | No | server |
+| `TERRENO_MCP_TRUST_PROXY_HOPS` | `@terreno/mcp` hosted server | ❌ | `1` when `K_SERVICE` is set (Cloud Run), else `0` | No | server |
+
+## 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 |
+|----------|---------|----------|---------|--------|-------|
+| `OTEL_SERVICE_NAME` | OpenTelemetry (example-backend) | ❌ | `example-backend` | No | server |
+| `SEED_DEFAULTS` | example-backend boot | ❌ | — | 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 |
+| `API_KEY` | integrations | ❌ | — | Yes | server |
+
+`SEED_DEFAULTS=true` runs the example seed (default users, all with the published password
+`testpassword123`) when the server starts. A process with `NODE_ENV=production` logs a warning and
+skips it, so no deployed revision, PR previews included, holds those accounts.
+
+## Testing & CI (tooling only)
+
+| Variable | Read by | Scope |
+|----------|---------|-------|
+| `CI` | CI scripts | tooling |
+| `JEST_WORKER_ID` | test runners | tooling |
+| `SHOW_ALL_TEST_LOGS` | tests | tooling |
+| `KEEP_COVERAGE` | tests | tooling |
+| `DRY_RUN` | scripts | tooling |
+| `APPIUM_CI`, `APPIUM_DEV_SERVER_URL`, `APPIUM_QUICK_LOOP`, `APPIUM_REQUIRE_NON_DEV_CLIENT`, `APPIUM_SPEC_FILE_RETRIES`, `APPIUM_SPECS` | Appium e2e | tooling |
+| `ANDROID_APP_PATH`, `ANDROID_DEVICE_NAME` | mobile e2e | tooling |
+| `IOS_APP_PATH`, `IOS_DEVICE_NAME`, `IOS_DEVICE_UDID`, `IOS_PLATFORM_VERSION` | mobile e2e | tooling |
+| `EXPO_OS` | Expo tooling | tooling |
+| `DEMO_URL`, `DOCS_URL` | link checkers | tooling |
+| `DEBUG_BILLING` | debug | tooling |
+| `TZ` | tests | tooling |
+| `X` | debug flag | tooling |
+
+## Example `.env` files
+
+- [`example-backend/.env.example`](https://github.com/TerrenoLabs/terreno/blob/master/example-backend/.env.example)
+- [`example-frontend/.env.example`](https://github.com/TerrenoLabs/terreno/blob/master/example-frontend/.env.example)
+
+## Related documentation
+
+- [Deployment baseline](../explanation/deployment-baseline.md)
+- [Build for web](../how-to/build-for-web.md)
+- [Deploy to Vercel](../how-to/deploy-to-vercel.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)

package/dist/docs/versioned/57.20.0/reference/feature-flags.md

@@ -0,0 +1,304 @@
+# @terreno/feature-flags
+
+Feature flags and A/B testing plugin for `@terreno/api`. Provides a Mongoose model, admin CRUD endpoints, user-facing evaluation, and deterministic hashing for gradual rollouts and variant assignment.
+
+## Install
+
+```bash
+bun add @terreno/feature-flags
+```
+
+Peer dependency: `mongoose >= 8.0.0`.
+
+## Quick Start
+
+### Backend
+
+Register `FeatureFlagsApp` as a `TerrenoPlugin` and add the pre-configured admin model config to your `AdminApp`:
+
+```typescript
+import {TerrenoApp} from "@terreno/api";
+import {AdminApp} from "@terreno/admin-backend";
+import {FeatureFlagsApp, featureFlagAdminConfig} from "@terreno/feature-flags";
+import {User} from "./models/user";
+
+const segments = {
+  "pro-users": (user) => user.plan === "pro",
+  "beta-testers": (user) => user.betaTester === true,
+};
+
+new TerrenoApp({userModel: User})
+  .register(new FeatureFlagsApp({segments}))
+  .register(
+    new AdminApp({
+      models: [featureFlagAdminConfig],
+    })
+  )
+  .start();
+```
+
+`featureFlagAdminConfig` is a ready-to-use admin model config that sets up the display name, list fields, route path, and model reference — no manual configuration needed. Downstream consumers can import it directly and pass it to `AdminApp`.
+
+### Frontend
+
+Use the `useFeatureFlags` hook from `@terreno/rtk` to evaluate flags for the current user:
+
+```typescript
+import {useFeatureFlags} from "@terreno/rtk";
+import {terrenoApi} from "@/store/sdk";
+
+const MyComponent = () => {
+  const {getFlag, getVariant, isLoading} = useFeatureFlags(terrenoApi);
+
+  if (isLoading) return <Spinner />;
+
+  const showNewFeature = getFlag("new-feature"); // boolean
+  const variant = getVariant("checkout-experiment"); // string | null
+
+  return showNewFeature ? <NewFeature /> : <OldFeature />;
+};
+```
+
+New code can also use OpenFeature React hooks (`useBooleanFlagValue`, `useStringFlagValue`, `FeatureFlag`, …) after wiring `useTerrenoFeatureFlags` and `<OpenFeatureProvider domain="feature-flags">` — see `@terreno/rtk` and [how-to: add feature flags](../how-to/add-feature-flags.md).
+
+## OpenFeature integration
+
+`FeatureFlagsApp` registers an OpenFeature **server** provider (`MongoFeatureFlagProvider`) on a dedicated domain (default `"feature-flags"`) so the global default provider is unchanged. The authenticated bulk endpoint **`GET {basePath}/flagConfiguration`** returns a `FlagConfiguration`-compatible map (suitable for `TypedInMemoryProvider` on the client). Disabled **boolean** flags are included and resolve to `off`, so a client can tell a turned-off flag from one that was never created. Disabled variant flags and archived flags are omitted. The legacy **`GET {basePath}/evaluate`** response shape is unchanged but is **deprecated**: responses include `Deprecation: true` and a `Sunset` HTTP-date header (~90 days). Prefer `useTerrenoFeatureFlags` / `useFeatureFlags` from `@terreno/rtk`, or migrate direct HTTP callers to `/flagConfiguration`.
+
+### `defaultVariant` on `FeatureFlag`
+
+Stored OpenFeature default variant key: for boolean flags `"on"` or `"off"`; for variant flags one of `variants[].key`. On save, if omitted, the schema sets boolean → `"off"` and variant → first variant key. `/flagConfiguration` builds each entry’s `defaultVariant` and `variants` from the **resolved** value for the current user (so client-side OpenFeature reads the correct branch without re-running targeting).
+
+### `MongoFeatureFlagProvider`
+
+Server-side OpenFeature `Provider` that resolves flags via `findOneOrNone` and existing `evaluateFlag()` logic. Unsupported evaluation types: **`resolveNumberEvaluation` / `resolveObjectEvaluation` always return `FLAG_NOT_FOUND`** with the caller’s default.
+
+### Type-safe flag keys (optional)
+
+Consumers may augment `@openfeature/core` with `BooleanFlagKey` / `StringFlagKey` unions. Those types are **compile-time hints only**; keys created in the admin UI can drift until types are updated.
+
+### Live updates (optional)
+
+Pass `liveUpdates: { socketIoServer: io | () => io }` to broadcast on Mongoose change streams. **Requires MongoDB as a replica set** (single-node replset is fine). Emits a socket event (default `featureFlagsChanged`, payload `{ key }`) and `PROVIDER_CONFIGURATION_CHANGED` on the server provider. All authenticated subscribers receive the same event name; payload is only the flag key (same keys are already exposed per user via `/flagConfiguration`).
+
+## Exports
+
+### Classes
+
+| Export | Description |
+|--------|-------------|
+| `FeatureFlagsApp` | `TerrenoPlugin` that registers admin CRUD, `/flagConfiguration`, and `/evaluate` |
+| `MongoFeatureFlagProvider` | OpenFeature server `Provider` backed by Mongo evaluation |
+
+### Models
+
+| Export | Description |
+|--------|-------------|
+| `FeatureFlag` | Mongoose model for feature flag documents |
+
+### Constants
+
+| Export | Description |
+|--------|-------------|
+| `featureFlagAdminConfig` | Pre-configured `AdminModelConfig` for use with `AdminApp` |
+
+### Functions
+
+| Export | Description |
+|--------|-------------|
+| `buildFlagDefinition` | Build one `FlagDefinition` for `/flagConfiguration` |
+| `effectiveDefaultVariantForFlag` | Resolve `defaultVariant` including legacy docs |
+| `evaluateFlag` | Evaluate a single flag for a user |
+| `evaluateAllFlags` | Evaluate all enabled, non-archived flags for a user |
+| `deterministicHash` | Hash a string to 0–99 for consistent assignment |
+
+### Types
+
+| Export | Description |
+|--------|-------------|
+| `FeatureFlagDocument` | Mongoose document type for a feature flag |
+| `FeatureFlagModel` | Mongoose model type with custom statics |
+| `FeatureFlagRule` | Targeting rule shape (field-based or segment-based) |
+| `FeatureFlagVariant` | Variant key + weight for A/B tests |
+| `FeatureFlagType` | `"boolean" \| "variant"` |
+| `FeatureFlagsOptions` | Constructor options for `FeatureFlagsApp` |
+| `SegmentFunction` | `(user: unknown) => boolean` |
+| `EvaluationResult` | `Record<string, boolean \| string \| null>` |
+| `FlagDefinition` | One flag entry for `/flagConfiguration` |
+| `FlagConfigurationResponse` | `{ data: Record<string, FlagDefinition> }` |
+| `FeatureFlagsLiveUpdatesOptions` | Socket.io + optional custom event name |
+| `FeatureFlagsSocketEmitter` | Minimal `emit` shape for live updates |
+
+## FeatureFlagsApp Options
+
+```typescript
+interface FeatureFlagsOptions {
+  basePath?: string;                                // Default: "/feature-flags"
+  segments?: Record<string, SegmentFunction>;       // Named segment functions
+  permissions?: ModelRouterOptions["permissions"];   // Override default IsAdmin on CRUD
+  segmentsPermission?: (user: unknown) => boolean;  // Override admin check on /segments
+  liveUpdates?: FeatureFlagsLiveUpdatesOptions;     // Optional: change stream → socket.io
+  openFeatureDomain?: string;                       // Default: "feature-flags"
+}
+```
+
+## Generated Routes
+
+All routes are mounted under the configured `basePath` (default: `/feature-flags`).
+
+### Admin Routes (default: `IsAdmin`)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `{basePath}/flags/` | Create a feature flag |
+| `GET` | `{basePath}/flags/` | List flags (paginated, sortable) |
+| `GET` | `{basePath}/flags/:id` | Get a single flag |
+| `PATCH` | `{basePath}/flags/:id` | Update a flag |
+| `DELETE` | `{basePath}/flags/:id` | Soft-delete a flag |
+| `GET` | `{basePath}/segments` | List registered segment names |
+
+### User Routes (`IsAuthenticated`)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `{basePath}/flagConfiguration` | OpenFeature static configuration for enabled, non-archived flags (authenticated) |
+| `GET` | `{basePath}/evaluate` | **Deprecated** — legacy `Record<key, boolean \| string \| null>` for the current user |
+
+### Response Shapes
+
+**`GET /feature-flags/flagConfiguration`** (enabled flags only; disabled/archived keys are omitted):
+
+```json
+{
+  "data": {
+    "todo-summary-card": {
+      "variants": {"off": false, "on": true},
+      "defaultVariant": "on",
+      "disabled": false
+    },
+    "profile-layout": {
+      "variants": {"compact": "compact", "detailed": "detailed"},
+      "defaultVariant": "compact",
+      "disabled": false
+    }
+  }
+}
+```
+
+**`GET /feature-flags/evaluate`** (deprecated headers on response):
+
+```json
+{
+  "data": {
+    "new-checkout-flow": true,
+    "checkout-experiment": "variant-a",
+    "dark-mode": false
+  }
+}
+```
+
+**`GET /feature-flags/segments`**:
+```json
+{
+  "data": ["pro-users", "beta-testers"]
+}
+```
+
+## Flag Types
+
+### Boolean Flags (`type: "boolean"`)
+
+Return `true` or `false`. Use `rolloutPercentage` for gradual rollouts.
+
+- `enabled: false` → always `false`
+- `enabled: true`, no matching rules → deterministic hash compared against `rolloutPercentage`
+- Matching rule → returns the rule's `enabled` value
+
+### Variant Flags (`type: "variant"`)
+
+Return a string variant key. Use the `variants` array with weighted distribution.
+
+- `enabled: false` → returns `null`
+- `enabled: true`, no matching rules → deterministic hash mapped to variant by cumulative weights
+- Matching rule → returns the rule's `variant` value
+
+## Targeting Rules
+
+Rules are evaluated in order — first match wins. Each rule is either field-based or segment-based.
+
+### Field Rules
+
+Match against a user field with an operator:
+
+```json
+{
+  "field": "email",
+  "operator": "contains",
+  "value": "@mycompany.com",
+  "enabled": true
+}
+```
+
+Supported operators: `eq`, `neq`, `in`, `nin`, `gt`, `lt`, `contains`. Dot notation is supported for nested fields (e.g. `address.zip`).
+
+### Segment Rules
+
+Match against a named segment function registered at startup:
+
+```json
+{
+  "segment": "pro-users",
+  "enabled": true
+}
+```
+
+## Admin Integration
+
+The `featureFlagAdminConfig` export provides everything `AdminApp` needs:
+
+```typescript
+import {featureFlagAdminConfig} from "@terreno/feature-flags";
+
+// Use directly in AdminApp
+new AdminApp({
+  models: [featureFlagAdminConfig, ...otherModels],
+});
+```
+
+This is equivalent to manually configuring:
+
+```typescript
+import {FeatureFlag} from "@terreno/feature-flags";
+
+{
+  displayName: "Feature Flags",
+  listFields: ["key", "name", "type", "enabled", "archived", "defaultVariant", "created"],
+  model: FeatureFlag,
+  routePath: "/feature-flags",
+}
+```
+
+The admin panel auto-generates forms from the FeatureFlag model schema, including fields for rules, variants, rollout percentage, and archiving.
+
+## Segments
+
+Segments are named functions that classify users. Register them when constructing `FeatureFlagsApp`:
+
+```typescript
+const segments = {
+  "admin-users": (user) => user.admin === true,
+  "oauth-users": (user) => Boolean(user.oauthProvider),
+  "high-usage": (user) => user.totalActions > 1000,
+  "internal-team": (user) => user.email?.endsWith("@mycompany.com"),
+};
+
+new FeatureFlagsApp({segments});
+```
+
+Segment names can be referenced in flag rules via the admin UI.
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FEATURE_FLAGS_DEBUG` | Set to `"true"` to write evaluation diagnostics at `debug` level: flag key, rule field, operator, and result. User attribute values are never logged | Disabled |