@terreno/mcp 57.0.0 → 57.1.0

package/src/docs/versioned/next/explanation/roadmap-process.md

@@ -22,10 +22,10 @@ Discussion (Ideas/RFC)
     ▼
 Issue: Status = Shaping ─────────────────────────────┐
                                                       │  IP approved → roadmap-item
-Blend writes IP + task list  ────────────────────────┤  (sets IP field, Shaping → Planned)
+Grow writes IP + task list   ────────────────────────┤  (sets IP field, Shaping → Planned)
 (docs/implementationPlans/ + docs/tasks/)             ▼
                                           Issue: Status = Planned
-                                                      │  Roast → Cupping → Pour
+                                                      │  Pick → Roast → Brew
                                                       ▼
                                           PR: Fixes #NNN
                                                       │  merge
@@ -34,17 +34,17 @@ Blend writes IP + task list  ─────────────────
 ```
 
 The planning pipeline (the `terreno-planning` plugin) drives the design-and-build half;
-the roadmap skills drive the public-tracking half. They meet at one handoff: **Blend
+the roadmap skills drive the public-tracking half. They meet at one handoff: **Grow
 writes the IP, and once it is Approved hands off to `roadmap-item`.**
 
 | Transition | Who owns it | Authoritative artifact |
 | ---------- | ----------- | ---------------------- |
 | Idea debated and shaped | Community + maintainers | GitHub Discussion |
 | Discussion → first tracking issue (`Shaping`) | `roadmap-promote` | GitHub Issue + Project |
-| Design, scope, acceptance criteria | `terreno-1-blend` / `ip` | `docs/implementationPlans/<slug>.md` |
-| Task breakdown for implementation | `terreno-1-blend` / `ip` | `docs/tasks/<slug>.md` |
+| Design, scope, acceptance criteria | `terreno-1-grow` | `docs/implementationPlans/<slug>.md` |
+| Task breakdown for implementation | `terreno-1-grow` | `docs/tasks/<slug>.md` |
 | Approved IP → issue `Planned` + `IP` field set | `roadmap-item` | GitHub Issue + Project |
-| Implement, verify, submit, review | `terreno-2-roast` … `terreno-5-dialin` | the PR |
+| Implement, verify, submit, review | `terreno-2-pick` … `terreno-5-taste` | the PR |
 | Sprint estimates, assignees, internal-only work | Linear | Linear |
 | Public rendered list | CI (`roadmap:generate`) | `ROADMAP.md` |
 
@@ -60,7 +60,7 @@ The `terreno-planning` plugin is meant to run in any Terreno repo, including one
 Discussions and no roadmap board (Flourish, most consumer apps). There, only the design-and-build
 half applies:
 
-- **Blend** still writes the IP + task list — that dual-file model is the source of truth
+- **Grow** still writes the IP + task list — that dual-file model is the source of truth
   everywhere. It detects the absence of `.github/roadmap-fields.yml` and the `roadmap-item`
   skill and **skips the roadmap handoff** instead of inventing issues or labels.
 - Sprint execution is tracked in Linear and linked from the IP header; it is never copied
@@ -236,9 +236,9 @@ is the variable the generator reads.
 
 ## Maintainer skills
 
-Four agent skills cover the recurring roadmap work. Each one researches, proposes, and then
+Five agent skills cover the recurring roadmap work. Each one researches, proposes, and then
 **stops for a maintainer to approve** before touching GitHub — roadmap decisions are the most
-human part of the process, so none of them mutate state on their own. All four are
+human part of the process, so none of them mutate state on their own. All five are
 `disable-model-invocation`, meaning an agent will not start them on its own initiative;
 you invoke them explicitly.
 
@@ -248,6 +248,19 @@ you invoke them explicitly.
 | `roadmap-promote` | Maintainers accepted an Ideas or RFC discussion and it needs a tracked issue that links back to the thread |
 | `roadmap-item` | An approved IP needs its public tracking issue, or an existing entry's scope changed |
 | `roadmap-review` | Recurring hygiene: status drift, stale items, untriaged backlog, promotion candidates, then regenerate `ROADMAP.md` |
+| `roadmap-frontier` | A destination is too large or uncertain for one IP/context and needs a map, a small unblocked frontier, and repeated Grow → Taste delivery loops |
+
+### Huge features: frontier maps
+
+A frontier map is one low-resolution roadmap issue with an observable destination,
+resolved-decision index, current frontier, fog, and explicit out-of-scope boundary. Child
+tickets hold the detail and native blocking relationships. Work only the **frontier**:
+open, unblocked, unclaimed tickets.
+
+Decision tickets resolve one question. Delivery tickets link one approved IP/task pair and
+run the complete planning pipeline. After each ticket, update the map, graduate clarified
+fog into precise tickets, and return to the frontier with a fresh agent context. The map
+closes only when the destination is reached and no in-scope fog or open child tickets remain.
 
 Sources live in `.rulesync/skills/`; run `bun run rules` after editing to regenerate the
 per-agent mirrors.

package/src/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -885,3 +885,42 @@ ad-hoc backfill scripts.
 - **Tasks:** *(not yet written)*
 - **RTK flag:** None
 - **Depends on:** —
+
+---
+
+# Shipped, umbrella, and declined IPs
+
+Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.
+Add each to the **Terreno Roadmap** project with the `IP` field set to the slug below.
+
+| IP slug | GitHub issue | Status |
+|---------|--------------|--------|
+| `admin-only` | https://github.com/FlourishHealth/terreno/issues/1075 | Shipped |
+| `admin-ui-v2-django-parity` | https://github.com/FlourishHealth/terreno/issues/1076 | Shipped |
+| `admin-script-runner` | https://github.com/FlourishHealth/terreno/issues/1077 | Shipped |
+| `consent-forms` | https://github.com/FlourishHealth/terreno/issues/1078 | Shipped |
+| `upgrade-banner` | https://github.com/FlourishHealth/terreno/issues/1079 | Shipped |
+| `apierror-standard-error-redesign` | https://github.com/FlourishHealth/terreno/issues/1080 | Shipped |
+| `syncdb-local-first` | https://github.com/FlourishHealth/terreno/issues/1081 | Shipped |
+| `feature-flags-openfeature` | https://github.com/FlourishHealth/terreno/issues/1082 | Shipped |
+| `design-blend-skill` | https://github.com/FlourishHealth/terreno/issues/1083 | Shipped |
+| `ModularAPI` | https://github.com/FlourishHealth/terreno/issues/1084 | Shipped |
+| `mcp-boost-parity` | https://github.com/FlourishHealth/terreno/issues/1085 | In progress |
+| `docs-site-and-versioning` | https://github.com/FlourishHealth/terreno/issues/1086 | Planned |
+| `syncdb-codegen` | https://github.com/FlourishHealth/terreno/issues/1087 | Planned |
+| `migrate-cicd-to-circleci` | https://github.com/FlourishHealth/terreno/issues/1088 | Planned |
+| `rbac-permissions` | https://github.com/FlourishHealth/terreno/issues/1089 | Planned |
+| `infra-mcp` | https://github.com/FlourishHealth/terreno/issues/1090 | Planned (blocked) |
+| `comms-admin-dashboard` | https://github.com/FlourishHealth/terreno/issues/1091 | Planned |
+| `model-router-mcp` | https://github.com/FlourishHealth/terreno/issues/1092 | Planned |
+| `terreno-langfuse-integration` | https://github.com/FlourishHealth/terreno/issues/1093 | Future |
+| `oss-launch-program` | https://github.com/FlourishHealth/terreno/issues/1094 | In progress |
+| `b2b-platform-program` | https://github.com/FlourishHealth/terreno/issues/1095 | Planned |
+| `offline-mode` | https://github.com/FlourishHealth/terreno/issues/1096 | Declined |
+| `model-router-actions` | https://github.com/FlourishHealth/terreno/issues/1097 | Declined |
+| `feature-flags` | https://github.com/FlourishHealth/terreno/issues/1098 | Declined |
+| `admin-improvements` | https://github.com/FlourishHealth/terreno/issues/1099 | Declined |
+
+Research and design sub-documents share the parent IP's issue: `admin-only-research` →
+#1075; `infra-mcp-research` → #1090; `migrate-cicd-to-circleci-research` → #1088;
+`syncdb-phase-c-design`, `terreno-syncdb-2`, and `syncdb-api-inventory` → #1081.

package/src/docs/versioned/next/how-to/README.md

@@ -12,10 +12,13 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 
 ## Contents
 
+- [CircleCI](circleci.md) — Dual-run CI on CircleCI (package CI / policy / e2e; deploys later)
 - [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
 - [Add GitHub OAuth authentication](add-github-oauth.md) — Enable GitHub login for your API
 - [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
 - [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
+- [Expose Model Context Protocol tools](expose-mcp-tools.md) — Turn `modelRouter` models into MCP tools an LLM can call
+- [Install agent skills](install-agent-skills.md) — Install Grow/Pick/Roast/Brew/Taste and domain skills with `npx skills`
 - [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
 - [Deploy to Google Cloud Platform](deploy-to-gcp.md) — Deploy demo and example apps to GCS with CDN
 - [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer

package/src/docs/versioned/next/how-to/admin-add-model.md

@@ -0,0 +1,41 @@
+# Add a model to the admin
+
+Add `admin` directly to the model's existing `modelRouter` options:
+
+```ts
+export const userRouter = modelRouter("/users", User, {
+  admin: {
+    displayName: "Users",
+    listFields: ["email", "name", "admin", "created"],
+    searchFields: ["email", "name"],
+    sortableFields: ["email", "name", "created"],
+    filters: [{field: "admin", kind: "boolean", label: "Admin user"}],
+  },
+  permissions: {
+    create: [Permissions.IsAdmin],
+    delete: [Permissions.IsAdmin],
+    list: [Permissions.IsAdmin],
+    read: [Permissions.IsAdmin],
+    update: [Permissions.IsAdmin],
+  },
+});
+```
+
+Register that router with `TerrenoApp`, then register `AdminApp`. The model appears in
+`GET /admin/config` and at `/admin/User` without a duplicate `AdminApp.models` entry.
+
+If the same Mongoose model is mounted at two `routePath`s (different filters or list
+columns), `/admin/config` keeps `name` as the model name for the registered entry and
+suffixes the others with the route slug (for example `Food-archived-foods`) so each list
+is reachable.
+
+Common fields:
+
+- `listFields`: columns and fields exposed to admin CRUD.
+- `searchFields`: string fields matched by the list search box (`q`) as a
+  case-insensitive partial (`$regex`) query.
+- `sortableFields`: the only columns with sorting enabled.
+- `filters`: typed filter drawer controls.
+- `fieldsets`: grouped form sections.
+- `readonlyFields` / `hiddenFields`: display-only or omitted form fields.
+- `adminPermissions`: optional admin-specific permission methods.

package/src/docs/versioned/next/how-to/admin-custom-home.md

@@ -0,0 +1,31 @@
+# Customize the admin home
+
+Configure home slots on `AdminApp`:
+
+```ts
+new AdminApp({
+  home: {
+    title: "Operations",
+    slots: {
+      contentTop: ["feature-flags-overrides"],
+      main: ["modelStats"],
+      navGlobal: ["scriptRunner"],
+      sidebar: ["versionConfig", "recentActivity"],
+    },
+  },
+});
+```
+
+Built-in IDs include `modelStats`, `modelsGrid`, `scriptRunner`, `versionConfig`, and
+`recentActivity`. Plugins add IDs such as `feature-flags-overrides`.
+
+For an app-specific widget, implement `AdminHomeWidgetProps` and register it:
+
+```tsx
+<AdminProvider widgets={{home: {operationsSummary: OperationsSummary}}} api={api}>
+  <AdminHome api={api} />
+</AdminProvider>
+```
+
+Then place `"operationsSummary"` in a home slot. Unknown IDs render a visible missing-widget
+placeholder in development instead of crashing the dashboard.

package/src/docs/versioned/next/how-to/admin-custom-widget.md

@@ -0,0 +1,42 @@
+# Add a custom admin field widget
+
+1. Name the widget in model admin metadata:
+
+```ts
+admin: {
+  displayName: "Articles",
+  listFields: ["title", "body"],
+  fieldOverrides: {body: {widget: "rich-text"}},
+}
+```
+
+2. Implement the field widget:
+
+```tsx
+const RichTextWidget: React.FC<AdminFieldWidgetProps> = ({
+  value,
+  onChange,
+  readOnly,
+}) => (
+  <RichTextEditor
+    disabled={Boolean(readOnly)}
+    onChange={onChange}
+    value={typeof value === "string" ? value : ""}
+  />
+);
+```
+
+3. Register it once around the admin routes:
+
+```tsx
+<AdminProvider
+  api={api}
+  apiBase="/admin"
+  routeBase="/admin"
+  widgets={{fields: {"rich-text": RichTextWidget}}}
+>
+  <AdminRoutes />
+</AdminProvider>
+```
+
+Host registrations override built-ins with the same ID.

package/src/docs/versioned/next/how-to/admin-import-prebuilt.md

@@ -0,0 +1,25 @@
+# Import pre-built admins
+
+Register first-party plugins on the same `TerrenoApp` as `AdminApp`:
+
+```ts
+const app = new TerrenoApp({userModel: User})
+  .register(new FeatureFlagsApp())
+  .register(new ConsentApp({auditTrail: true}))
+  .register(new DocumentStorageApp({bucketName: process.env.GCS_BUCKET ?? ""}))
+  .register(new AIAdminApp())
+  .register(new AdminApp({home: {slots: {main: ["modelStats"]}}}));
+```
+
+`AdminApp` aggregates each plugin's `adminContribution()`:
+
+- `FeatureFlagsApp`: FeatureFlag model and `feature-flags-overrides` home widget.
+- `ConsentApp`: ConsentForm and ConsentResponse models plus consent field-widget IDs.
+- `DocumentStorageApp`: `documents` custom screen.
+- `AIAdminApp`: `ai-requests` custom screen and explorer API.
+
+Wrap frontend admin routes in `AdminProvider`. First-party widgets are already in the built-in
+registry, so no consumer-side switch statement or custom-screen map is required.
+
+`featureFlagAdminConfig` and `AdminApp.models` remain compatibility paths, but new integrations
+should use plugin contributions and `modelRouter({admin: ...})`.

package/src/docs/versioned/next/how-to/circleci.md

@@ -0,0 +1,173 @@
+# CircleCI (Terreno)
+
+Dual-run migration from GitHub Actions. See
+[`docs/implementationPlans/migrate-cicd-to-circleci.md`](../implementationPlans/migrate-cicd-to-circleci.md).
+
+**Status (2026-08-20):** CircleCI is **disabled**. GitHub Actions is the CI of
+record. Setup/path-filtering is parked in `.circleci/config.setup.yml`;
+`.circleci/config.yml` is a no-op (`workflows.disabled.when: false`). Real jobs
+remain in `.circleci/continue-config.yml`. To re-enable, copy `config.setup.yml`
+over `config.yml`.
+
+**Parked (2026-08-17):** Phase 1–3 config is in-repo (package CI, repo policy, Playwright
+e2e). **Deploys are not ported yet** (Netlify, GCP CD, EAS, npm publish). GHA remains
+required until CircleCI twins are trusted.
+
+## Project setup (maintainers)
+
+1. Link `FlourishHealth/terreno` in CircleCI (GitHub App).
+2. Default branch: `master`.
+3. Enable **dynamic config** / setup workflows for the project (required for
+   `.circleci/config.yml` `setup: true`).
+4. Build forked PRs if you want DCO + rulesync on forks.
+
+Org/project slug: _(record after Phase 0.1 — e.g. `flourishhealth/terreno`)_.
+
+## Config layout
+
+| File | Role |
+|------|------|
+| `.circleci/config.yml` | Active CircleCI config (currently a disabled no-op) |
+| `.circleci/config.setup.yml` | Parked setup workflow + `path-filtering` (copy over `config.yml` to re-enable) |
+| `.circleci/continue-config.yml` | Real jobs/workflows gated by those params |
+
+Smoke job `config-ok` always runs on continuation.
+
+`.circleci/**` sets `run-circleci-config`, which starts the `circleci-config`
+workflow: one job from each ported family (package CI, policy, example apps,
+`e2e` with `spec: login`, admin-spa). `comms/**` also sets
+`run-example-backend` and `run-example-backend-script`, matching the GitHub
+Actions twins.
+
+## Contexts (create empty shells, then fill)
+
+Do **not** paste secret values into the repo. Create these CircleCI Contexts and restrict
+`terreno-release` to tag/release pipelines when publish is ported.
+
+| Context | Maps from GHA | Used by (planned / current) |
+|---------|---------------|------------------------------|
+| `terreno-npm` | `NPM_TOKEN` | publish (deferred) |
+| `terreno-netlify` | `NETLIFY_*` | deploys (deferred) |
+| `terreno-expo` | `EXPO_TOKEN` | EAS (deferred) |
+| `terreno-gcp` | OIDC / WIF (no long-lived key for CD) | GCP CD (deferred) |
+| `terreno-e2e` | `E2E_TOKEN_SECRET`, `E2E_REFRESH_TOKEN_SECRET`, `E2E_SESSION_SECRET` | `e2e`, `admin-spa-integration` |
+| `terreno-release` | `REPO_ADMIN_TOKEN`, Zoom webhooks | publish (deferred) |
+| `terreno-agentic` | `CURSOR_API_KEY` | agentic replacements (deferred) |
+| `terreno-github-api` | PAT (`pull-requests`, `contents`, …) | `dco`, PR comments later |
+
+Until contexts exist, e2e jobs may use **project env vars for `E2E_*` secrets only**
+(or the in-job `ci-e2e-*-secret` fallbacks). **Do not** put `GITHUB_TOKEN` (or any
+GitHub PAT) in project env vars — those are injected into every job, including
+`bun` scripts from the PR. Create `terreno-github-api`, restrict it to this
+project, leave fork-PR secret passing off, and attach that context **only** to
+`dco` (and later comment jobs). DCO skips if `GITHUB_TOKEN` is unset.
+
+After contexts exist, attach them on the matching jobs in
+`.circleci/continue-config.yml` (see comments in the `workflows:` section).
+
+## Check name map (GHA → CircleCI)
+
+Branch protection still requires **GitHub Actions** names during dual-run. CircleCI
+checks appear as CircleCI job names in the GitHub Checks UI.
+
+| GHA job `name:` / workflow | CircleCI job |
+|----------------------------|--------------|
+| Repository policies / No barrel imports | `no-barrel-imports` |
+| Explicit any baseline | `explicit-any` |
+| License coverage | `license-coverage` |
+| Verify rules are in sync | `rulesync-check` |
+| `dco` | `dco` |
+| Run all tests (API CI) | `api-ci` |
+| Run all tests (AI CI) | `ai-ci` |
+| RTK Lint and Build | `rtk-ci` |
+| UI Lint, Build, Types, and Tests | `ui-ci` |
+| Demo TypeScript Check (UI dependency) | `ui-demo-typecheck` |
+| Demo Lint and TypeScript Check | `ui-demo-ci` |
+| Lint, compile, and test communications | `comms-ci` |
+| Lint, Build, and Test (MCP) | `mcp-server-ci` |
+| Build Docker Image (MCP) | `mcp-server-docker` |
+| Example Frontend Lint and Test | `example-frontend-ci` |
+| Example Backend Lint, Build, and Test | `example-backend-ci` |
+| Run admin script CLI | `example-backend-script-runner` |
+| Build backend Docker image | `example-backend-docker` |
+| Admin SPA Build and E2E | `admin-spa-ci` |
+| E2E · `<spec>` | `e2e` (matrix `spec`) |
+| E2E Load · syncdb-loadlab | `e2e-load` (trigger-gated, see below) |
+| Admin SPA Backend Integration E2E | `admin-spa-integration` |
+| _(new)_ CircleCI path-filter parity | `circleci-parity` |
+| _(smoke)_ | `config-ok` |
+
+Deferred phases keep their GHA checks for now; these are the planned CircleCI job
+names so branch protection can be remapped in one pass later:
+
+| GHA job `name:` / workflow (not yet ported) | Planned CircleCI job |
+|---------------------------------------------|----------------------|
+| Fingerprint gate (`fingerprint-gate.yml`) | `fingerprint-gate` (Phase 5) |
+| EAS PR update/build (`eas-pr.yml`) | `eas-pr` (Phase 5) |
+| EAS dev build (`eas-dev-build.yml`) | `eas-dev-build`, manual pipeline (Phase 5) |
+| CD terraform preview/apply (`cd.yml`) | `cd-terraform`, `cd-deploy` (Phase 6) |
+| Preview cleanup (`preview-cleanup.yml`) | `preview-cleanup` (Phase 6) |
+| Netlify demo / frontend / docs deploys | `deploy-demo`, `deploy-example-frontend`, `deploy-docs` (Phase 4) |
+| Publish on tag (`publish-on-tag.yml`) | `publish-npm` (Phase 7, single-writer cutover) |
+| Appium / Maestro | `appium-android`, `appium-ios`, `maestro` (Phase 8) |
+
+## Path-filter parity guard
+
+`bun run check:circleci-parity` fails when a GHA `paths:` entry has no mapping to
+its CircleCI parameter — otherwise the twin silently never runs. It runs as the
+`circleci-parity` job (CircleCI) and the **CircleCI path-filter parity** job
+(GitHub Actions `repo-policies`). Add new packages/paths to the mapping in
+`.circleci/config.setup.yml` (or `config.yml` when enabled) and to `WORKFLOW_PARAMETERS` in
+`scripts/check-circleci-parity/lib.ts`.
+
+## Config-only changes
+
+When CircleCI is enabled, `.circleci/config.yml` / `continue-config.yml` /
+`example-frontend/playwright.circleci.config.ts` edits set `run-circleci-config`,
+which runs a representative slice (`api-ci`, `ui-ci`, `example-backend-ci`,
+`no-barrel-imports`, `e2e` spec `login`) so config changes are actually exercised
+instead of only hitting the always-on smoke jobs. While disabled, keep the mapping
+in `config.setup.yml` in sync; `check:circleci-parity` reads that file first. CircleCI e2e
+pre-starts a static `bun expo export` on `:8082` (`NODE_OPTIONS=--max-old-space-size=3072`
+for the export only) and reuses it (60s test timeout, `large` Docker). Keeping Metro
+alive next to Chromium gets SIGKILL on 8GB. `xlarge` is not on this project's plan.
+
+## Nightly load test
+
+`e2e-load` (syncdb-loadlab) is never PR-blocking. Trigger the **setup** pipeline
+with `run-e2e-load`. Setup skips path-filtering and continues with a differently
+named continuation parameter (`e2e-load`) so CircleCI does not report conflicting
+pipeline parameters.
+
+```json
+{"run-e2e-load": true}
+```
+
+This replaces the GHA cron / `workflow_dispatch` / `load-test` label triggers in
+`e2e-load-nightly.yml`.
+
+## Local validation
+
+```bash
+circleci config validate .circleci/config.yml
+circleci config validate .circleci/continue-config.yml
+```
+
+## Dual-run drift
+
+While both systems run, keep these in sync when editing a GHA workflow:
+
+1. `paths:` → mapping in `.circleci/config.setup.yml` (or `config.yml` when enabled; enforced by `check:circleci-parity`)
+2. e2e `spec:` matrix → `e2e` workflow matrix in `continue-config.yml`
+3. New package CI workflow → new param + job + `WORKFLOW_PARAMETERS` entry
+
+## Not in this phase
+
+- Netlify / docs / demo / example-frontend **deploys**
+- GCP `cd.yml`, preview-cleanup, OIDC
+- EAS / fingerprint
+- npm publish-on-tag
+- Appium / Maestro
+- CodeQL, Dependabot auto-merge, triage, gh-aw agentics
+
+Keep matching `.github/workflows/*` until dual-run cutover deletes them per phase.

package/src/docs/versioned/next/how-to/configure-better-auth.md

@@ -1,20 +1,23 @@
 # Configure Better Auth
 
-Set up Better Auth as an alternative authentication provider with built-in social OAuth support.
+Set up Better Auth as the **default** authentication provider for new Terreno apps — session-based auth with built-in social OAuth and first-class `@terreno/syncdb` integration.
 
 ## Overview
 
-Better Auth is an optional authentication system that runs **alongside** the existing JWT/Passport authentication. You can choose which authentication provider to use at server startup via environment variables.
+Better Auth is the recommended authentication system for new Terreno frontends. Register `BetterAuthApp` on the backend, set `AUTH_PROVIDER=better-auth`, and wire `createBetterAuthClient` + `generateBetterAuthSlice` on the client. Pair with `betterAuthAdapter` when using `@terreno/syncdb`.
 
-**Use Better Auth when you need:**
+JWT/Passport remains available for legacy deployments (`AUTH_PROVIDER=jwt`). Both can run in parallel during migration.
+
+**Choose Better Auth for:**
+- New apps and greenfield screens
 - Social login (Google, GitHub, Apple)
-- Session-based authentication
-- Modern OAuth 2.0 flows
+- Session-based authentication with `@terreno/syncdb`
+- Socket.io sync via `RealtimeApp` bearer sessions
 
-**Use JWT authentication when you need:**
-- Stateless authentication
-- Simpler token-based auth
-- No social login required
+**Stay on JWT only when:**
+- You have an existing JWT deployment and are mid-migration
+- You require a fully stateless token contract with no session cookies
+- You have custom JWT payload requirements Better Auth cannot satisfy
 
 ## Backend Setup
 
@@ -292,5 +295,5 @@ Better Auth runs **in parallel** with JWT auth. You don't need to migrate existi
 
 - [Authentication Architecture](../explanation/authentication.md)
 - [@terreno/api Reference](../reference/api.md#better-auth)
-- [@terreno/rtk Reference](../reference/rtk.md#better-auth)
+- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md#better-auth)
 - [Better Auth Documentation](https://better-auth.com/)