@terreno/mcp 57.0.0 → 57.2.0

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

@@ -0,0 +1,431 @@
+# 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).
+
+## 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 session cookie (web) or bearer session token (native)
+6. Session middleware populates `req.user` for subsequent requests
+
+**Key properties:**
+- Session-based (cookies / bearer session) vs. stateless JWT
+- 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` URL with tokens as query params
+
+**Account Linking:**
+- Authenticated users can link their GitHub account via `GET /auth/github/link`
+- 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)
+
+### 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
+- Contains user ID and permissions in payload
+
+**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
+}
+``````
+
+### Custom Permissions
+
+Create custom permission functions:
+
+``````typescript
+const IsPremiumUser = (user, obj, method) => {
+  return user?.subscription === "premium";
+};
+
+modelRouter(Model, {
+  permissions: {
+    create: [Permissions.IsAuthenticated, IsPremiumUser],
+  },
+});
+``````
+
+## 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
+- Implement rate limiting on auth endpoints
+- 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 (use httpOnly cookies in production)
+- Log tokens to console
+- Send tokens in URL query parameters
+- 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 webhook signatures instead of JWT:
+
+``````typescript
+import crypto from "crypto";
+
+router.post("/webhook", asyncHandler(async (req, res) => {
+  const signature = req.headers["x-signature"];
+  const payload = JSON.stringify(req.body);
+  const expected = crypto
+    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
+    .update(payload)
+    .digest("hex");
+  
+  if (signature !== expected) {
+    throw new APIError({status: 401, title: "Invalid signature"});
+  }
+  
+  // Process webhook
+}));
+``````
+
+## Learn More
+
+- [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.1.0/explanation/deployment-architecture-gcp.md

@@ -0,0 +1,65 @@
+# GCP deployment architecture
+
+Reference topology for hosting a Terreno full-stack app on Google Cloud Platform.
+
+This page is conceptual — commands live in the [how-to guides](../how-to/deploy-to-gcp.md).
+
+## Topology
+
+```mermaid
+flowchart TD
+  U["User<br/>iOS / Android / Web"]
+  CDN["Cloud CDN + GCS bucket<br/>expo export -p web output"]
+  CR["Cloud Run<br/>@terreno/api backend"]
+  SM["Secret Manager<br/>auth secrets, MONGO_URI"]
+  AT["MongoDB Atlas<br/>replica set (change streams)"]
+  GCS["GCS bucket<br/>user file uploads"]
+  AR["Artifact Registry<br/>backend image"]
+  U -->|"web"| CDN
+  U -->|"native app"| CR
+  CDN -->|"API calls"| CR
+  CR --> SM
+  CR --> AT
+  CR --> GCS
+  AR --> CR
+```
+
+## Component responsibilities
+
+| Component | Role |
+|-----------|------|
+| **Artifact Registry** | Stores versioned backend container images built from `example-backend/Dockerfile` |
+| **Cloud Run** | Runs the long-lived `@terreno/api` process (HTTP + Socket.io) |
+| **Secret Manager** | Holds `MONGO_URI`, JWT secrets, and other credentials — mounted as env vars |
+| **MongoDB Atlas** | Primary database; must be a replica set for change streams (realtime, feature flags) |
+| **GCS (web bucket)** | Serves static web export; CDN caches at the edge |
+| **GCS (uploads bucket)** | Private object storage for user uploads via `@terreno/api` file plugins |
+
+## Why Cloud Run (not App Engine or GKE)
+
+| Option | Tradeoff |
+|--------|----------|
+| **Cloud Run** | Pay-per-use, minimal ops, supports WebSockets with session affinity — fits Terreno's socket + HTTP model |
+| **App Engine** | Similar serverless model but less flexible for custom containers and long timeouts |
+| **GKE** | Full control but requires cluster management — overkill for a single Terreno backend |
+
+## Why Atlas (not self-hosted Mongo on GCP)
+
+| Option | Tradeoff |
+|--------|----------|
+| **MongoDB Atlas** | Managed replica sets, backups, and change streams out of the box |
+| **Self-hosted on Compute Engine** | You operate replica set elections, backups, and upgrades — documented as out of scope for launch |
+
+## Static web vs server-rendered
+
+| Approach | Tradeoff |
+|----------|----------|
+| **GCS + CDN (static export)** | Cheapest, simplest, works today with Expo `single`/`static` output — no SSR or API routes |
+| **Node/Bun server (SSR)** | Better SEO and API routes — requires Expo SDK ≥ 55; not available in the current `~54` catalog |
+
+Native iOS and Android apps call Cloud Run directly; only the web client uses the CDN origin.
+
+## Related
+
+- [Deployment baseline](deployment-baseline.md) — seven requirements every host must satisfy
+- [Deploy to GCP](../how-to/deploy-to-gcp.md) — step-by-step guides

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

@@ -0,0 +1,78 @@
+# Deployment baseline
+
+Every Terreno production deployment needs the same seven foundations. Provider guides ([Deploy to GCP](../how-to/deploy-to-gcp.md), future Vercel guide) 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 | **Current default** |
+| `static` | Per-route HTML files | No | No | Any static host | Available; better SEO |
+| `server` | `dist/client` + `dist/server` | Yes | Yes (alpha, SDK ≥ 55) | Node/Bun/edge runtime | Not yet — repo catalog is Expo `~54.0.29`; see [Web SSR and admin SPA](https://github.com/FlourishHealth/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/FlourishHealth/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/test`, etc.) must compile before the example backend bundles.
+
+CI builds the image on every PR that touches backend paths (`.github/workflows/example-backend-docker.yml`).

package/dist/docs/versioned/57.1.0/explanation/local-first-data.md

@@ -0,0 +1,52 @@
+# Local-first data in Terreno
+
+Terreno's default frontend data path is **local-first**: the on-device store is what your UI reads and writes, and the server reconciles changes asynchronously. This is a different mental model from request/response fetching with RTK Query.
+
+## What local-first means here
+
+In `@terreno/syncdb`, a TinyBase `MergeableStore` on the device is the **UI source of truth**. When a user taps "save," the mutation applies to local state immediately and lands in a durable outbox. The client then pushes the change to `@terreno/api` over the sync protocol (socket deltas with HTTP snapshot catch-up). The server remains the **authority** for permissions, validation, and conflict resolution — but the UI does not wait on the network for every write.
+
+There is no server-first mode and no opt-in flag: if you use syncdb, you adopt this model for every synced collection.
+
+## Mental model shift
+
+| Server-first (RTK Query) | Local-first (syncdb) |
+|--------------------------|----------------------|
+| UI reads from cache filled by HTTP | UI reads from the local store |
+| Writes call the API, then invalidate/refetch | Writes apply locally, then reconcile |
+| Loading spinners track request lifecycle | Sync status tracks outbox + connectivity |
+| Optimistic updates are manual and fragile | Optimistic state is the default path |
+| Conflicts are rare / ignored | Conflicts are explicit and must be resolved |
+
+Think **apply locally, then reconcile** instead of **request, wait, update cache**.
+
+## What you stop doing
+
+1. **Manual optimistic updates** — `onQueryStarted` patches, temporary IDs, and rollback logic for writes.
+2. **Write-level loading spinners** — `isLoading` on mutations for "saving…" UX; the row updates instantly.
+3. **Refetch orchestration** — `invalidatesTags`, `refetch()`, and list/detail cache coordination after mutations.
+4. **Treating the network as the read path** — list screens blocked on `isLoading` for every navigation.
+
+RTK Query remains appropriate for **non-synced** endpoints: `/auth/me`, admin RPC, AI routes, and anything that should stay request/response.
+
+## What you start doing
+
+1. **Conflict resolution UI** — When the server rejects a mutation (409 / `sync:nack`), the user must choose a strategy (`useServer` or `keepMine`). Use `ConflictSheet` from `@terreno/ui` or build your own with `useConflicts`.
+2. **Sync-status UX** — Surface offline state, queued mutations, and drain progress with `useSyncStatus` (and optionally `SyncStatusBanner`).
+3. **Encryption at rest (web)** — Web persistence uses AES-GCM via the default `createServerKeyProvider`; understand key fetch and `onDecryptFailure` for support flows.
+4. **Key lifecycle on logout** — Call `syncDb.stop()` and consider `wipeLocalData` when the authenticated user changes so one account does not read another's local store.
+5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server.
+
+## Tradeoffs
+
+**Gains:** instant UI, offline writes with a durable outbox, simpler screen code, and one write path on the server (sync and REST share `modelRouter`).
+
+**Costs:** larger conceptual surface (conflicts, sync status, local storage), mandatory replica-set MongoDB for realtime, and migration work for existing RTK Query screens.
+
+Server-first fetching is simpler when you only need online CRUD with no offline requirement — but Terreno's blessed path for collection data is local-first.
+
+## Related docs
+
+- [syncdb reference](../reference/syncdb.md) — API ground truth
+- [Migrate from RTK to syncdb](../how-to/migrate-rtk-to-syncdb.md) — step-by-step migration
+- [Authentication architecture](authentication.md) — Better Auth + socket sessions