@terreno/mcp 0.31.0 → 56.0.0-beta.0

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

@@ -2,223 +2,385 @@
 
 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_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` | ✅ if Better Auth | — | 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 |
-
-## 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 CORS | ❌ | auto | No | server |
-| `API_URL` | microservice split | ❌ | — | No | server |
-| `DISABLE_LOG_ALL_REQUESTS` | `@terreno/api` logging | ❌ | — | No | server |
-
-## 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 |
-| `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`
-
-## 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` | ❌ | — | 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_PROJECT_ID` | GCS clients | ❌ | — | No | server |
-| `GCS_SERVICE_ACCOUNT_KEY` | GCS clients | ❌ | — | Yes | server |
-
-## Feature flags
-
-| Variable | Read by | Required | Default | Secret | Scope |
-|----------|---------|----------|---------|--------|-------|
-| `FEATURE_FLAGS_DEBUG` | `@terreno/feature-flags` | ❌ | — | No | server |
-
-## 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` | logger | ❌ | — | 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` | ❌ | — | Yes | server |
-| `REDIS_URL` | various | ❌ | — | Yes | server |
-
-## Webhooks & notifications
-
-| Variable | Read by | Required | Default | Secret | Scope |
-|----------|---------|----------|---------|--------|-------|
-| `SLACK_WEBHOOKS` | `@terreno/api` | ❌ | — | Yes | server |
-| `SLACK_WEBHOOK_URL` | scripts | ❌ | — | 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` | webhooks | ❌ | — | Yes | server |
-
-## Admin SPA
-
-| Variable | Read by | Required | Default | Secret | Scope |
-|----------|---------|----------|---------|--------|-------|
-| `ADMIN_SPA_ENABLED` | example-backend | ❌ | — | No | 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 |
-
-## Example backend (app-specific)
-
-| Variable | Read by | Required | Default | Secret | Scope |
-|----------|---------|----------|---------|--------|-------|
-| `FLOURISH_SERVICE` | OpenTelemetry | ❌ | `flourish-backend` | No | server |
-| `PR_NUMBER` | PR preview deploy | ❌ | — | No | server |
-| `PR_SERVICE_URL` | PR preview deploy | ❌ | — | 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 |
-
-## 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/FlourishHealth/terreno/blob/master/example-backend/.env.example)
-- [`example-frontend/.env.example`](https://github.com/FlourishHealth/terreno/blob/master/example-frontend/.env.example)
-
-## Related documentation
-
-- [Deployment baseline](../explanation/deployment-baseline.md)
-- [Build for web](../how-to/build-for-web.md)
-- [Configure Better Auth](../how-to/configure-better-auth.md)
+## Table of Contents
+
+- [@terreno/api (Backend)](#terrenoapi-backend)
+- [@terreno/rtk (Frontend State)](#terrenortk-frontend-state)
+- [@terreno/ui (Components)](#terrenoui-components)
+- [Example Backend](#example-backend)
+- [Example Frontend](#example-frontend)
+
+---
+
+## @terreno/api (Backend)
+
+Environment variables used by the `@terreno/api` package.
+
+### Authentication
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `AUTH_PROVIDER` | ❌ | `jwt` | Authentication provider: `"jwt"` or `"better-auth"` |
+| `TOKEN_SECRET` | ✅ (if JWT) | - | Secret key for signing JWT access tokens |
+| `TOKEN_ISSUER` | ✅ (if JWT) | - | JWT issuer claim (e.g., `your-app.com`) |
+| `REFRESH_TOKEN_SECRET` | ✅ (if JWT) | - | Secret key for signing refresh tokens |
+| `SESSION_SECRET` | ✅ (if JWT) | - | Express session secret |
+| `TOKEN_EXPIRES_IN` | ❌ | `15m` | Access token expiration (e.g., `1h`, `30m`) |
+| `REFRESH_TOKEN_EXPIRES_IN` | ❌ | `30d` | Refresh token expiration (e.g., `7d`, `90d`) |
+| `SIGNUP_DISABLED` | ❌ | `false` | Disable user registration (invite-only mode) |
+
+### Better Auth (Optional)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BETTER_AUTH_SECRET` | ✅ (if Better Auth) | - | Secret key for Better Auth session encryption |
+| `BETTER_AUTH_URL` | ✅ (if Better Auth) | - | Base URL for Better Auth server (e.g., `https://api.example.com`) |
+| `GOOGLE_CLIENT_ID` | ❌ | - | Google OAuth client ID |
+| `GOOGLE_CLIENT_SECRET` | ❌ | - | Google OAuth client secret |
+| `APPLE_CLIENT_ID` | ❌ | - | Apple Sign In service ID |
+| `APPLE_CLIENT_SECRET` | ❌ | - | Apple Sign In private key |
+
+### GitHub OAuth (Optional)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GITHUB_CLIENT_ID` | ❌ | - | GitHub OAuth application client ID |
+| `GITHUB_CLIENT_SECRET` | ❌ | - | GitHub OAuth application client secret |
+| `GITHUB_CALLBACK_URL` | ❌ | - | OAuth callback URL (e.g., `https://api.example.com/auth/github/callback`) |
+
+### Server Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PORT` | ❌ | `3000` | HTTP server port |
+| `NODE_ENV` | ❌ | `development` | Node environment (`development`, `production`, `test`) |
+| `MONGO_URI` | ❌ | `mongodb://localhost:27017` | MongoDB connection string |
+| `ENABLE_SWAGGER` | ❌ | `false` | Enable Swagger UI at `/swagger` endpoint |
+
+### Logging & Monitoring
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SENTRY_DSN` | ❌ | - | Sentry DSN for error tracking |
+| `USE_SENTRY_LOGGING` | ❌ | `false` | Send logs to Sentry |
+| `LOG_REQUESTS` | ❌ | `false` | Log all HTTP requests |
+| `LOG_SLOW_REQUESTS` | ❌ | `false` | Log requests exceeding threshold |
+| `SLOW_REQUEST_THRESHOLD_MS` | ❌ | `5000` | Milliseconds to consider a request "slow" |
+| `SLOW_DB_QUERY_THRESHOLD_MS` | ❌ | `100` | Milliseconds to consider a DB query "slow" |
+
+### Webhooks & Notifications (Optional)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SLACK_WEBHOOKS` | ❌ | - | JSON object mapping names to Slack webhook URLs<br/>Example: `{"default": "https://hooks.slack.com/..."}` |
+| `GOOGLE_CHAT_WEBHOOKS` | ❌ | - | JSON object mapping names to Google Chat webhook URLs<br/>Example: `{"default": "https://chat.googleapis.com/..."}` |
+| `ZOOM_WEBHOOK` | ❌ | - | Zoom webhook URL for notifications |
+
+### Google Cloud Platform (Optional)
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GCP_PROJECT` | ❌ | - | Google Cloud project ID |
+| `GCP_LOCATION` | ❌ | - | GCP region (e.g., `us-central1`) |
+| `GCP_SERVICE_ACCOUNT_EMAIL` | ❌ | - | Service account email for authentication |
+| `GCP_TASKS_NOTIFICATIONS_QUEUE` | ❌ | - | Cloud Tasks queue name for notifications |
+| `GCP_TASK_PROCESSOR_QUEUE` | ❌ | - | Cloud Tasks queue name for background tasks |
+
+### Caching & Performance
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VALKEY_URL` | ❌ | - | Redis/Valkey connection URL (e.g., `redis://localhost:6379`) |
+
+### Other APIs
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GEMINI_API_KEY` | ❌ | - | Google Gemini API key for AI features |
+
+### Example .env File
+
+``````bash
+# Authentication Provider
+AUTH_PROVIDER=jwt  # or "better-auth"
+
+# Required for JWT authentication
+TOKEN_SECRET=your-secret-key-change-this-in-production
+TOKEN_ISSUER=your-app.com
+REFRESH_TOKEN_SECRET=your-refresh-secret-change-this-too
+SESSION_SECRET=your-session-secret-change-this-also
+
+# Required for Better Auth (if AUTH_PROVIDER=better-auth)
+# BETTER_AUTH_SECRET=your-better-auth-secret-min-32-chars
+# BETTER_AUTH_URL=http://localhost:4000
+
+# Optional - Social OAuth (Better Auth)
+# GOOGLE_CLIENT_ID=your-google-client-id
+# GOOGLE_CLIENT_SECRET=your-google-client-secret
+# GITHUB_CLIENT_ID=your-github-client-id
+# GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# Database
+MONGO_URI=mongodb://localhost:27017/your-app
+
+# Optional - Common in development
+PORT=3000
+NODE_ENV=development
+ENABLE_SWAGGER=true
+LOG_REQUESTS=true
+
+# Optional - Production monitoring
+SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
+USE_SENTRY_LOGGING=true
+``````
+
+---
+
+## @terreno/rtk (Frontend State)
+
+Environment variables used by the `@terreno/rtk` package and frontend applications.
+
+### Base URL Configuration
+
+The base URL is resolved in priority order:
+
+1. `Constants.expoConfig?.extra?.BASE_URL` (production/staging builds)
+2. `process.env.EXPO_PUBLIC_API_URL` (development web)
+3. `Constants.expoConfig?.hostUri` + the dev API port (dev simulator/device)
+4. `http://localhost:<dev API port>` (fallback)
+
+The dev API port defaults to `4000` and is overridable per app via `EXPO_PUBLIC_DEV_API_PORT`
+or `expoConfig.extra.DEV_API_PORT` (for example `3000` or `9000`).
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `EXPO_PUBLIC_API_URL` | ❌ | Auto-detected | Backend API base URL<br/>Web: `http://localhost:4000`<br/>Simulator: Auto-detected via `hostUri`<br/>Device: Use your computer's local IP |
+| `EXPO_PUBLIC_DEV_API_PORT` | ❌ | 4000 | Local dev API port for host/localhost resolution (also settable via `extra.DEV_API_PORT`) |
+
+### Debug Flags
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `AUTH_DEBUG` | ❌ | `false` | Enable authentication debug logging |
+| `WEBSOCKETS_DEBUG` | ❌ | `false` | Enable WebSocket debug logging |
+
+### Example app.json Configuration
+
+``````json
+{
+  "expo": {
+    "extra": {
+      "BASE_URL": "https://api.example.com",
+      "AUTH_DEBUG": "false",
+      "WEBSOCKETS_DEBUG": "false"
+    }
+  }
+}
+``````
+
+### Example .env for Web Development
+
+``````bash
+# Backend API URL
+EXPO_PUBLIC_API_URL=http://localhost:4000
+``````
+
+---
+
+## @terreno/ui (Components)
+
+The `@terreno/ui` package **does not require environment variables**. All configuration is done at runtime via the `TerrenoProvider` component.
+
+### Runtime Configuration
+
+``````typescript
+import {TerrenoProvider} from "@terreno/ui";
+
+<TerrenoProvider
+  initialTheme={{
+    primitives: {
+      primary500: "#0066CC",
+      accent500: "#FF6B35",
+    }
+  }}
+>
+  <App />
+</TerrenoProvider>
+``````
+
+---
+
+## Example Backend
+
+Environment variables specific to the example backend application (not part of @terreno/api).
+
+### Application Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APP_ENV` | ❌ | `development` | Application environment (`development`, `staging`, `production`) |
+| `BACKEND_SERVICE` | ❌ | `all` | Service type to run: `api`, `websockets`, `tasks`, or `all` |
+| `API_URL` | ❌ | - | API service URL (for microservice architecture) |
+| `TASKS_URL` | ❌ | - | Tasks service URL (for microservice architecture) |
+| `FLOURISH_SERVICE` | ❌ | `flourish-backend` | Service name for OpenTelemetry tracing |
+
+### WebSockets
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `WEBSOCKET_PORT` | ❌ | Same as `PORT` | WebSocket server port (if separate from HTTP) |
+| `FRONTEND_URL` | ❌ | Auto-detected | Frontend URL for CORS (e.g., `http://localhost:8082`) |
+
+### Pull Request Environments
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PR_NUMBER` | ❌ | - | Pull request number (set by CI/CD) |
+| `PR_SERVICE_URL` | ❌ | - | Cloud Run service URL base for PR environments |
+
+### Performance Monitoring
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MEMORY_SAMPLE_INTERVAL_MS` | ❌ | `60000` | Interval for memory usage sampling |
+| `TRACE_SAMPLING_RATE` | ❌ | `0.1` | OpenTelemetry trace sampling rate (0.0-1.0) |
+
+### Testing
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TEST_MONGO_URI` | ❌ | `mongodb://localhost:27017/test` | MongoDB URI for tests |
+| `CRON_SECRET_KEY` | ❌ | - | Secret key for testing cron endpoints |
+
+### Configuration Model System
+
+The example backend uses a **Configuration model** with a priority system:
+
+**Priority (highest to lowest)**:
+1. Runtime override via `Configuration.set()`
+2. Database cache (persisted values)
+3. Environment variable
+4. Default value
+
+``````typescript
+// Get configuration value
+const pageSize = await Configuration.get("DEFAULT_PAGE_SIZE"); // Returns 20
+
+// Set configuration value (persists to database)
+await Configuration.set("DEFAULT_PAGE_SIZE", 50);
+
+// Register new configuration
+Configuration.register("FEATURE_FLAG", {
+  defaultValue: false,
+  envVar: "FEATURE_FLAG",
+  description: "Enable new feature",
+  type: "boolean",
+});
+``````
+
+See [Configuration System](../explanation/configuration-system.md) for details.
+
+---
+
+## Example Frontend
+
+Environment variables specific to the example frontend application.
+
+### SDK Generation
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `OPENAPI_URL` | ❌ | `http://localhost:4000/openapi.json` | Backend OpenAPI spec URL for SDK generation |
+
+Used by `bun run sdk` to fetch the OpenAPI specification and generate RTK Query hooks.
+
+### Development
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `EXPO_PUBLIC_API_URL` | ❌ | Auto-detected | Backend API URL (see [@terreno/rtk](#terrenortk-frontend-state)) |
+
+### Example .env File
+
+``````bash
+# Backend API (optional - auto-detected if not set)
+EXPO_PUBLIC_API_URL=http://localhost:4000
+
+# SDK generation (optional)
+OPENAPI_URL=http://localhost:4000/openapi.json
+``````
+
+---
+
+## Best Practices
+
+### Security
+
+1. **Never commit `.env` files** - Add to `.gitignore`
+2. **Use strong secrets** - Generate with `openssl rand -base64 32`
+3. **Rotate secrets regularly** - Especially `TOKEN_SECRET` and `REFRESH_TOKEN_SECRET`
+4. **Different secrets per environment** - Don't reuse production secrets in development
+
+### Development
+
+1. **Use `.env.example`** - Check into version control with placeholder values
+2. **Document all variables** - Include description and default values
+3. **Validate required variables** - Fail fast if missing critical config
+4. **Auto-detect when possible** - Like `@terreno/rtk` does for `BASE_URL`
+
+### Production
+
+1. **Use environment variables** - Not hardcoded values or `.env` files
+2. **Set via platform** - Railway, Heroku, Cloud Run, etc.
+3. **Enable monitoring** - Set `SENTRY_DSN` and `USE_SENTRY_LOGGING`
+4. **Reduce logging** - Set `LOG_REQUESTS=false` to reduce noise
+
+---
+
+## Troubleshooting
+
+### "TOKEN_SECRET is not set"
+
+**Problem**: Required authentication variables missing.
+
+**Solution**: 
+```bash
+cp .env.example .env
+# Edit .env and set all required variables
+```
+
+### "Cannot connect to MongoDB"
+
+**Problem**: `MONGO_URI` incorrect or MongoDB not running.
+
+**Solutions**:
+- Ensure MongoDB is running: `docker run -d -p 27017:27017 mongo`
+- Check `MONGO_URI` in `.env`
+- Test connection: `mongosh mongodb://localhost:27017`
+
+### "Network request failed" (Frontend)
+
+**Problem**: Frontend can't reach backend.
+
+**Solutions**:
+- Ensure backend is running
+- Check `EXPO_PUBLIC_API_URL` matches backend port
+- For physical devices: Use your computer's local IP, not `localhost`
+- Verify CORS settings allow frontend origin
+
+### "Invalid token"
+
+**Problem**: Token secrets mismatch between frontend/backend.
+
+**Solution**: Ensure `TOKEN_SECRET` and `REFRESH_TOKEN_SECRET` are identical across deployments if using shared authentication.
+
+---
+
+## Related Documentation
+
+- [Getting Started Tutorial](../tutorials/getting-started.md)
+- [@terreno/api Reference](./api.md)
+- [@terreno/rtk Reference](./rtk.md)
+- [Configuration System](../explanation/configuration-system.md)
+- [Example Backend README](../../example-backend/README.md)
+- [Example Frontend README](../../example-frontend/README.md)