@terreno/mcp 57.19.2 → 57.20.0

package/src/docs/templates/bootstrap/frontend/app/_layout.template.tsx

@@ -5,14 +5,15 @@ import {Stack} from "expo-router";
 import * as SplashScreen from "expo-splash-screen";
 import {useEffect} from "react";
 import "react-native-reanimated";
-import {baseUrl, installTerrenoDevConsoleLogger, selectBetterAuthUserId} from "@terreno/rtk";
+import {baseUrl, selectBetterAuthUserId} from "@terreno/rtk";
+import {installTerrenoDevConsoleLogger} from "@terreno/syncdb";
 import {TerrenoProvider} from "@terreno/ui";
 import {Provider, useSelector} from "react-redux";
 import {PersistGate} from "redux-persist/integration/react";
 import {useColorScheme} from "@/components/useColorScheme";
 import store, {persistor} from "@/store/index";
 
-installTerrenoDevConsoleLogger();
+installTerrenoDevConsoleLogger({baseUrl});
 
 export {ErrorBoundary} from "expo-router";
 

package/src/docs/templates/bootstrap/frontend/app/login.template.tsx

@@ -68,7 +68,7 @@ const LoginScreen: React.FC = () => {
             />
           )}
           <TextField
-            autoComplete="off"
+            autoComplete="username"
             disabled={isLoading}
             onChange={setEmail}
             placeholder="Email"

package/src/docs/upgrades/57.20.0.md

@@ -0,0 +1,238 @@
+# Upgrading to 57.20.0
+
+**Action required:** Yes
+**Affected packages:** @terreno/api, @terreno/rtk, @terreno/ui, @terreno/admin-frontend, @terreno/mcp
+
+## Summary
+
+This release ships the Better Auth account suite: social login, account linking, passkeys,
+two-factor with backup codes, closed sign-up, and staff account recovery (`AccountSecurityApp`,
+org-admin recovery). It adds drop-in `TerrenoLoginScreen` and `TerrenoAccountSecurityScreen`
+screens, `ListDetailLayout`, provisional consent signing, and MCP OAuth client credentials. The
+app `User` claim guard now runs before a Better Auth user is created, which can refuse sign-ups
+that 57.17.0 accepted. Several defaults also change: the desktop layout floor, sign-out timing,
+web autofill, and the hosted MCP URL.
+
+## Breaking changes
+
+### Better Auth claims an existing app `User` only with a verified email or its password
+
+**What changed**
+
+A Better Auth sign-up or sign-in links to an unlinked app `User` with the same email (ignoring
+case) only when the provider verified the email, or when the password verifies against that
+`User`'s passport-local-mongoose hash. Otherwise the request answers 409 with
+`code: "VERIFY_EMAIL_TO_USE_ACCOUNT"` and creates no Better Auth user, account, or verification
+email. OAuth callbacks redirect with that `error`. A `User` already bound to another Better Auth
+account is refused with `code: "ACCOUNT_ALREADY_EXISTS"`. `syncBetterAuthUser` throws `APIError`
+409 instead of inserting a duplicate `User`, and takes a new `password` option.
+
+`BetterAuthApp` registered without a `userModel` now adopts `TerrenoApp`'s user model, and the
+`terreno-app-user-sync` plugin syncs the app `User` when each session is created. A
+password-proven link that fails to save fails the sign-in with 500 `APP_USER_LINK_FAILED`.
+
+**Why**
+
+57.17.0 checked the claim only after the Better Auth user existed, so a later email verification
+could still hand that user someone else's `User`.
+
+**Migration**
+
+Users who sign up with their existing password, or sign in with a provider that verified their
+email, link at once. Users with no password hash (for example GitHub JWT sign-in) must reset their
+password through JWT `POST /auth/forgotPassword` first, or sign in with a verified provider. Keep
+the JWT auth routes mounted while users move. Handle the new 409 codes on your login screen:
+
+```typescript
+import {getLoginFeedback} from "@terreno/rtk";
+
+// Before: a generic error for any refused sign-up
+setError(error.message);
+
+// After: VERIFY_EMAIL_TO_USE_ACCOUNT reads as "verify your email"
+const {notice, error: errorLine} = getLoginFeedback({
+  failure: {code: error.code, message: error.message, source: "response"},
+  mode: methods?.accountLinking.mode,
+});
+```
+
+`TerrenoLoginScreen` from `@terreno/rtk` handles these codes for you. See
+`docs/explanation/account-linking.md`.
+
+### `accountLinking: {mode: "never"}` refuses `link-social` up front
+
+**What changed**
+
+With linking off (`accountLinking: {mode: "never"}` or
+`options.account.accountLinking.enabled: false`), `POST {basePath}/link-social` answers 403
+`LINKING_DISABLED` instead of failing at the provider callback.
+
+**Why**
+
+The user learns linking is off before leaving for the provider.
+
+**Migration**
+
+Hide the "Link" action when `useAuthMethods(authClient)` reports linking is off, or treat 403
+`LINKING_DISABLED` as a final answer:
+
+```typescript
+// Before
+await authClient.linkSocial({provider: "google"}); // failed later at the callback
+
+// After
+const {methods} = useAuthMethods(authClient);
+const canLink = methods?.accountLinking.mode !== "never";
+```
+
+### Desktop layout floor moves from 768pt to 1024pt
+
+**What changed**
+
+`Card`, `MarkdownEditor`, the admin shell, and the admin filter drawer use the narrow layout
+below 1024pt instead of 768pt. Admin home stacks its panes below that floor.
+`ADMIN_FILTER_MOBILE_BREAKPOINT` is now 1024, and `isSupportedDesktopWidth({width})` reports the
+floor.
+
+**Why**
+
+Tablets between 768pt and 1023pt got cramped desktop layouts. See
+`docs/explanation/responsive-design.md`.
+
+**Migration**
+
+```typescript
+// Before
+const isDesktop = width >= 768;
+
+// After
+import {isSupportedDesktopWidth} from "@terreno/ui";
+const isDesktop = isSupportedDesktopWidth({width});
+```
+
+Check screens you tuned for 768–1023pt widths, such as iPad portrait.
+
+### `logout()` waits for the server before clearing the session
+
+**What changed**
+
+In `@terreno/rtk` `generateBetterAuthSlice`, `logout()` keeps the session until
+`authClient.signOut()` finishes (`signOutTimeoutMs`, default 10 seconds). Meanwhile
+`isSigningOut` (`selectBetterAuthIsSigningOut`) is true. A sign-out that fails while the session
+is still live stays signed in and sets `error` to `SIGN_OUT_FAILED_MESSAGE`. With `apisToReset`,
+the cache purges when the session clears, not at dispatch.
+
+**Why**
+
+A login screen that opened at once could find the still-live session and sign the user straight
+back in.
+
+**Migration**
+
+```typescript
+// Before: navigate as soon as logout is dispatched
+dispatch(betterAuth.actions.logout());
+router.replace("/login");
+
+// After: navigate when the session clears; show progress meanwhile
+const isSigningOut = useSelector(selectBetterAuthIsSigningOut);
+const isAuthenticated = useSelector(selectBetterAuthIsAuthenticated);
+```
+
+### `TextField` `autoComplete` now reaches the browser
+
+**What changed**
+
+`TextField` sets `autoComplete` as the input's `autocomplete` attribute on web, and as
+`autoComplete` / `textContentType` on native. `autoComplete="off"` now turns autofill off on web.
+`LoginScreen` and `SignUpScreen` default email to `"username"`.
+
+**Why**
+
+Password managers could not offer saved credentials or new passwords.
+
+**Migration**
+
+```tsx
+// Before
+<TextField autoComplete="off" type="email" ... />
+<TextField type="password" ... /> // on a set-new-password form
+
+// After
+<TextField autoComplete="username" type="email" ... />  // "email" on sign-up
+<TextField autoComplete="new-password" type="password" ... />
+```
+
+### Hosted Terreno MCP server moves to `https://mcp.terreno.app/mcp`
+
+**What changed**
+
+Docs and `create-terreno-app` now use `https://mcp.terreno.app/mcp`.
+`https://mcp.terreno.flourish.health/mcp` keeps serving for at least one more release.
+
+**Why**
+
+The hosted server has a Terreno-owned domain.
+
+**Migration**
+
+```json
+// Before (.cursor/mcp.json, .mcp.json)
+{"url": "https://mcp.terreno.flourish.health/mcp"}
+
+// After
+{"url": "https://mcp.terreno.app/mcp"}
+```
+
+Re-run `claude mcp add` registrations with the new URL. See `docs/how-to/set-up-terreno-mcp.md`.
+
+### `SyncStatusBanner` waits before showing Offline
+
+**What changed**
+
+The Offline badge appears only after `isOnline` stays false for `offlineGraceMs` (default 3000 ms).
+
+**Why**
+
+It flashed Offline during the first socket connect and brief drops.
+
+**Migration**
+
+```tsx
+// Before: shown immediately
+<SyncStatusBanner />
+
+// After: pass 0 to keep the old behavior
+<SyncStatusBanner offlineGraceMs={0} />
+```
+
+## Deprecations
+
+- `installTerrenoDevConsoleLogger` moves to `@terreno/syncdb` (also
+  `@terreno/syncdb/devConsoleLogger`) and takes `{baseUrl}`. The `@terreno/rtk` export is a
+  deprecated wrapper that keeps working with no arguments.
+- `terreno-mcp-local` `get_rtk_state` is a deprecated alias of the new `get_client_state` for one
+  release. It returns the same wrapped response, now with a `layer` field.
+
+## New capabilities
+
+- Better Auth features as config: `accountLinking`, `twoFactor`, `passkey`, `signUp: {mode: "closed"}`,
+  `oauthProxy`, `oauthHandoff` linking, and the Sign in with Apple key form. Login screens read
+  `GET {basePath}/terreno/methods` through `useAuthMethods`.
+- Drop-in screens in `@terreno/rtk`: `TerrenoLoginScreen` (remembered accounts, passkeys, inline
+  two-factor) and `TerrenoAccountSecurityScreen`, built on new `@terreno/ui` security cards,
+  `OtpField`, `TwoFactorChallengeScreen`, and `FormContainer`.
+- `AccountSecurityApp` for staff account recovery under `/users/:id/security`, org-admin recovery
+  under `/orgs/:orgId/members/:userId/security`, security notification emails, and
+  `UserSecurityScreen` / `MemberSecurityPanel` in `@terreno/admin-frontend`.
+- `ListDetailLayout` in `@terreno/ui`, provisional consent signing, and MCP OAuth
+  `client_credentials` with loopback redirect ports.
+
+## Verification
+
+- `bun run compile` and `bun run lint` at the app root.
+- `cd <your frontend> && bun run sdk` to pick up the new auth and security routes.
+- Sign up with an email that matches an existing unverified `User` and confirm a 409
+  `VERIFY_EMAIL_TO_USE_ACCOUNT`; sign up with that `User`'s password and confirm it links.
+- Sign out on web and confirm the app does not sign back in before the server answers.
+- Load key screens at 900pt width and confirm the narrow layout reads well.

package/src/docs/versioned/next/approval-rubric.md

@@ -5,11 +5,25 @@ enforced in code before and after this judgment; your level moves only inside th
 
 ## Levels
 
-| Level | Meaning | Examples |
-| --- | --- | --- |
-| low | A mistake is cheap and visible; the PR proves itself | docs; tests, snapshots, fixtures; copy and i18n strings; lint autofix; regenerated files whose source changed in the same PR; changelog fragments; dependency patch bumps with green CI; one-line bug fixes with a regression test |
-| medium | Ordinary product logic a reviewer would read once | new or changed behavior with tests; UI changes with screenshots; new endpoints with permission tests; minor dependency bumps; refactors inside one package |
-| high | A mistake is costly, hidden, or hard to undo | auth, sessions, permissions; schema and migrations; data backfills; billing; PHI handling; secrets, env, infra, Dockerfiles; CI; public API shape; lockstep framework bumps; feature-flag removals; reverts of security changes; hotfix branches with commits not on master; deleted or skipped tests |
+Most features are medium. High is reserved for security-related code.
+
+| Level | Human approvals | Meaning | Examples |
+| --- | --- | --- | --- |
+| low | None, once automated review and security checks are green | A mistake is cheap and visible; the PR proves itself | docs; copy and i18n strings; tests, snapshots, fixtures; internal-only features (admin screens, dev tooling, scripts no user runs); additive changes behind a feature flag that defaults off; lint autofix; regenerated files whose source changed in the same PR; changelog fragments; dependency patch bumps with green CI; one-line bug fixes with a regression test; small presentational UI tweaks (see below) |
+| medium | One person | Ordinary product changes, and changes to sensitive areas | new or changed behavior with tests; UI changes with screenshots beyond a small presentational tweak; new endpoints with permission tests; schema changes, migrations, and backfills; caching (RTK tags, syncdb, HTTP/CDN caching); app updates (expo-updates, `eas.json`, `app.json`, release channels); AI system prompts and tool definitions; billing; infra, Dockerfiles, CI; public API shape (removed, renamed, or retyped exports, props, or endpoints); dependency minor and major bumps; feature-flag removals; hotfix branches; deleted or skipped tests |
+| high | One person | Security-related code, where a mistake is costly, hidden, or hard to undo | auth, sessions, tokens, Better Auth and Passport config; permissions, RBAC, `queryFilter`s that scope data to a user; MCP OAuth; `socketAuth` and `sessionRevalidation`; secrets and env files; crypto, hashing, signature verification (webhook verifiers); PHI handling, consent, and audit logging; rate limits on unauthenticated routes; CORS and trusted origins; IAM, network, and firewall rules in infra; dependencies added for auth, crypto, or parsing untrusted input; reverts of security changes |
+
+A PR is high only when it changes how the system decides who may see or do something,
+or how secrets, credentials, or PHI are handled. Touching a security-adjacent file for an
+unrelated reason (a typo, a log message, a rename) is judged by what the change does.
+
+A **small presentational UI tweak** is low. It changes how one component looks or when it
+shows something (layout, spacing, copy, color, a display delay or debounce, an animation)
+and nothing else: no data fetching or syncdb/RTK changes, no navigation, no change to what
+a user can submit or do, no auth or consent screens. It may add an optional prop with a
+default, and that default may change what every consumer sees, as long as the old look is
+one prop away. It still needs tests that would fail without the change and before/after
+screenshots or video. A changelog fragment and docs update do not raise it.
 
 ## Dimensions
 
@@ -27,7 +41,8 @@ Score each 0–3 (0 absent, 1 weak, 2 adequate, 3 strong) and give reasons a rev
   or weakened; snapshot updates explained; a coverage gate check green when present.
 - **Evidence**: the `Verification` table names commands and outcomes, not just commands;
   UI changes carry screenshots or video; CI is green on this head; `⚠️ Not tested` rows
-  are absent or covered by an explicit reviewer instruction; each plan acceptance criterion
+  are absent or each carries an explicit reviewer instruction (the blocked behavior and the
+  exact steps to check it); each plan acceptance criterion
   has its named verification present.
 
 ## Architecture: Terreno rules
@@ -99,13 +114,14 @@ A finding here is blocking when it is certain and should-fix when it is likely.
 - A new runtime dependency is named in the PR body with the reason and is on the catalog
   in `.rulesync/rules/01-dependency-catalog.md` or justified against it; a missing reason
   lowers Architecture. Dev-only additions need no reason.
-- Patch bumps of catalog packages with green CI stay low. Minor bumps are medium. Major
-  bumps, Expo SDK and React Native upgrades, Better Auth and Mongoose majors, and
-  lockfile-only changes without a `package.json` change are high.
+- Patch bumps of catalog packages with green CI stay low. Minor and major bumps, Expo SDK
+  and React Native upgrades, Mongoose majors, and lockfile-only changes without a
+  `package.json` change are medium. Better Auth and other auth or crypto majors are high.
 - A bump that changes generated output (`bun.lock`, snapshots, `openApiSdk.ts`,
   `plugins/terreno-claude/`) ships the regenerated output in the same PR.
 - A new dependency's license passes `bun run check:licenses`.
-- A `patches/` change is high: it edits a third party and needs the upstream issue linked.
+- A `patches/` change is medium (high when it patches an auth, crypto, or parsing
+  dependency): it edits a third party and needs the upstream issue linked.
 - Removing a dependency the code still imports is a correctness finding; `knip` must stay
   at zero findings.
 
@@ -136,11 +152,13 @@ A finding here is blocking when it is certain and should-fix when it is likely.
 
 ## Signals that move the level
 
-- Raise one level: more than two packages touched; deletions outnumber additions in
+- Raise one level, never above medium unless the change is security-related: more than
+  two packages touched; deletions outnumber additions in
   source; a `TODO`, `FIXME`, or commented-out code added; explicit `any` added; PR body
   missing `Why`, `What changed`, or `Verification`; `WIP` in the title; the plan edited
   in the same PR to match the code.
-- Never low: new logic without a test; a `⚠️ Not tested` row without a reviewer action; an unresolved bot thread;
+- Never low: new logic without a test; a `⚠️ Not tested` row without an explicit reviewer instruction
+  (a row that does not name the blocked behavior and the exact steps to check it); an unresolved bot thread;
   a revert.
 - Size never moves the level. Changed lines and file counts say nothing about risk on
   their own: judge what the lines do. Pure renames and moves, regenerated SDK or

package/src/docs/versioned/next/explanation/README.md

@@ -15,12 +15,15 @@ Understanding-oriented documentation: concepts, architecture, and context.
 - [Loop engineering](loop-engineering.md) — Fresh-invocation lifecycle, state, evidence, and orchestration boundaries
 - [GitHub issue lifecycle](../how-to/github-issue-lifecycle.md) — Pick-ready issues and plan comments for Pick/Roast
 - [Install agent skills](../how-to/install-agent-skills.md) — `npx skills add TerrenoLabs/terreno`
+- [AI development loop](ai-development-loop.md) — The five-stage Ask, Generate, Run, Observe, Fix loop, what the agent can and cannot see, and how it composes with expo-mcp, Playwright MCP, and Maestro
+- [Agent guidelines](agent-guidelines.md) — How hosted docs, per-package `.ai/` guidelines, and `.rulesync/` rules reach an agent, and how apps extend them
 - [AI observability](ai-observability.md) — Two planes (telemetry vs control), plugins vs LangfuseApp, SOP loop
 - [Durable agent harness](durable-agent-harness.md) — Phases, checkpoints, and why the audit span shares the checkpoint transaction
 - [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
 - [Agent UI Asks](agent-ui-asks.md) — Why agent questions are client-side tool calls, the pause and resume round trip, why cards carry exact answers, the watch paths, asks vs blocks
 - [Agent UI blocks](agent-ui-blocks.md) — Why chat replies use a closed YAML catalog instead of free-form UI, why steppers and checklists call the server, and the rich-blocks rollout
 - [Authentication architecture](authentication.md) — Better Auth, JWT, and optional MCP service tokens
+- [Account linking](account-linking.md) — Linking modes, why both emails must be verified, Apple relay emails, and migrating JWT users
 - [Organization tenancy](organizations.md) — Optional Membership-backed tenancy, context, and isolation boundaries
 - [Configuration system](configuration-system.md) — Runtime configuration with database persistence
 - [Dependency management](dependency-management.md) — Catalog pins, exercise tests, fingerprint freeze
@@ -34,8 +37,10 @@ Understanding-oriented documentation: concepts, architecture, and context.
 - [Versioning policy](versioning-policy.md) — Lockstep `@terreno/*` versions, pre-1.0 breaks, deprecation window
 - [How admin interfaces are shaped](admin-interface.md) — Screens, sidebar, `apiBase` vs `routeBase`
 - [Admin plugin frontend widgets](admin-plugin-frontend.md) — Widget IDs from backend plugins
+- [Consent forms](consent-forms.md) — Versions, responses, the consent gate, and why provisional signatures don't clear it
 - [Consent admin migration](admin-consent-migration.md) — Which consent screens stay hand-written
 - [Public roadmap process](roadmap-process.md) — GitHub roadmap vs Linear execution
 - [Example app coverage](example-coverage.md) — Which framework capabilities the example apps exercise
 - [Repository settings](repository-settings.md) — Maintainer GitHub settings that cannot be committed
 - [Why Terreno owns chart SVG](charts.md) — Owned `react-native-svg` vs victory-native
+- [Responsive design](responsive-design.md) — Support levels, breakpoints, and the desktop floor

package/src/docs/versioned/next/explanation/account-linking.md

@@ -0,0 +1,169 @@
+# Account linking
+
+One person can sign in to a Terreno app in several ways: email and password, Google, GitHub,
+Apple, or a passkey. Account linking decides what happens when a new sign-in method arrives with
+an email that already belongs to an account. Done carelessly, it is an account takeover. This page
+explains the three modes, why Terreno asks for proof of the email before it links anything, and
+how apps that started on JWT auth move their users over.
+
+Setup: [Auth features](../how-to/configure-better-auth.md#auth-features). Reference:
+[`GET {basePath}/terreno/methods`](../reference/api.md#better-auth-authentication).
+
+## Two layers of accounts
+
+A Terreno app with Better Auth has two records per person:
+
+- **The Better Auth user** (`user` collection) owns sign-in. Each sign-in method is an `account`
+  row under it: `credential` for email and password, `google`, `github`, and so on. Better Auth
+  keeps emails unique, so there is at most one Better Auth user per email.
+- **The app `User`** (your Mongoose model) owns everything else: permissions, `admin`,
+  `disabled`, org memberships, and your data. It points at its Better Auth user through
+  `betterAuthId`.
+
+Linking happens at both layers. Better Auth decides whether a new provider `account` joins an
+existing Better Auth user. Terreno decides whether a Better Auth user may claim an existing app
+`User` (`syncBetterAuthUser`).
+
+## The three modes
+
+Set `accountLinking: {mode}` on `BetterAuthConfig`. The mode controls the Better Auth layer.
+
+| Mode | A same-email sign-in with a new method | `POST {basePath}/link-social` |
+| --- | --- | --- |
+| `verified-email` (default) | Joins the account when both emails are verified | Links |
+| `explicit` | Refused with `account_not_linked`; nothing is created | Links, from a signed-in session |
+| `never` | Refused with `account_not_linked`; nothing is created | Refused with 403 `LINKING_DISABLED` |
+
+- **`verified-email`** is the least friction: someone who signed up with email and password and
+  later taps "Continue with Google" on the same address lands in the same account.
+- **`explicit`** makes the user prove they own the existing account first. They sign in the old
+  way, open the Security screen, and link the provider there. A login screen should turn
+  `account_not_linked` into "sign in with your original method, then link this one".
+- **`never`** keeps every sign-in method separate. Because Better Auth keeps emails unique, a
+  second method on the same email cannot sign in at all. Pick it when a shared inbox must not
+  join two people's records.
+
+`/terreno/methods` reports the mode so clients can word their guidance. Unlinking the only
+remaining sign-in method is refused in every mode (400 `FAILED_TO_UNLINK_LAST_ACCOUNT`), so a user
+cannot lock themselves out. rtk's `TerrenoAccountSecurityScreen` checks the same rule before it
+asks, and a social-only user can add a password there (`POST {basePath}/terreno/set-password`) to
+gain a second method before unlinking a provider.
+
+### What the refusals look like
+
+| Path | `account_not_linked` | Unverified email matches an app `User` |
+| --- | --- | --- |
+| OAuth redirect (`/callback/{provider}`) | Redirect with `?error=account_not_linked` | Redirect with `?error=VERIFY_EMAIL_TO_USE_ACCOUNT` |
+| ID-token sign-in (`/sign-in/social` with `idToken`) | 401, `message: "account not linked"` | 409, `code: "VERIFY_EMAIL_TO_USE_ACCOUNT"` |
+| Email sign-up or sign-in | n/a | 409, `code: "VERIFY_EMAIL_TO_USE_ACCOUNT"`, `message: "Verify your email to use this account"` |
+
+## Why both emails must be verified
+
+Linking by email trusts that whoever controls the email controls the account. That trust has to
+hold on both sides:
+
+- **The new method's email.** A provider that reports an unverified email has not checked that
+  the person owns it. Linking on it lets anyone who types your address into that provider into
+  your account. An unverified provider email never links, in any mode. `trustedProviders` turns
+  this check off for the providers it lists, so list only providers that prove email ownership.
+- **The existing account's email.** If the existing account was itself created without proving
+  the email, an attacker can **pre-register**: sign up with the victim's address and a password
+  the attacker knows, wait for the victim to sign in with Google, and share the account.
+  Terreno keeps Better Auth's `requireLocalEmailVerified: true` in every mode, so an unverified
+  local account never absorbs a new method.
+
+The same rule applies one layer down. A Better Auth user claims an existing app `User` only when
+the provider verified its email, or when the user proves they own that `User` another way (see
+the migration below). Terreno checks this **before the Better Auth user is created**. An
+unverified sign-up for someone else's address gets 409 "Verify your email to use this account"
+and leaves nothing behind: no Better Auth user, no `account` row, no verification email. That
+matters because a Better Auth user left behind would be a pre-registration one layer down: once
+anyone verified that email (the victim clicking the mail the attacker's sign-up triggered, or an
+admin), the attacker's password would open the victim's `User`. Terreno never inserts a second
+`User` for the same email either.
+
+Two more rules hold whichever way the claim is proven. A `User` that already carries another
+Better Auth account's `betterAuthId` is never relinked by email (409 `ACCOUNT_ALREADY_EXISTS`).
+And when a verified email links a `User` whose own `emailVerified` is not `true`, the `User`'s
+legacy password is removed and its `tokenEpoch` bumped: whoever set that password never proved
+they own the mailbox, so it and the JWT refresh tokens issued from it stop working. A link proven
+by the legacy password itself keeps that password. Operator seeds pass `trustEmail` to
+`syncBetterAuthUser`, which skips these checks for accounts the seed created itself.
+
+Emails are compared ignoring case, so a legacy `User` stored as `Jane@Example.com` is protected
+from a sign-up as `jane@example.com`, and claiming it never creates a second `User`.
+
+**Trade-off: the 409 reveals that an account exists.** A sign-up that gets 409
+`VERIFY_EMAIL_TO_USE_ACCOUNT` tells the caller that an app `User` already has that email. Terreno
+accepts this account-existence signal: refusing silently would either leave the
+pre-registration hole open or leave legitimate users stuck with no explanation, and Better Auth's
+own sign-up already answers `USER_ALREADY_EXISTS` for emails it knows. Apps that must hide
+membership (for example, where an account implies care) should rate-limit sign-up (the `auth`
+bucket) and word the client message neutrally.
+
+The guard needs a user model on the Better Auth instance. `BetterAuthApp` uses its own
+`userModel`, or adopts `TerrenoApp`'s when it was given none, before it creates Better Auth. If you
+call `createBetterAuth` yourself, pass `userModel` to it whenever a session middleware links app
+`User`s.
+
+Terreno then syncs the app `User` as each Better Auth session is created, while the request that
+proves who the user is (its password, its provider) is still in hand. That is also when
+`oauthProvider` is recorded. The session check repeats the claim rule as a second guard, and a
+password-proven link that fails to save fails the sign-in (500 `APP_USER_LINK_FAILED`) instead of
+leaving a session that every request would refuse.
+
+## Apple private-relay emails
+
+Sign in with Apple lets users hide their address. Apple then reports a relay address such as
+`abc123@privaterelay.appleid.com`, marked verified, that forwards to the real inbox. It never
+matches the email the person used elsewhere, so Apple sign-in creates a separate account in every
+mode. Users who want one account sign in their usual way and link Apple from the Security screen
+(`/link-social`). That link works only when Apple shares the real address ("Share My Email"):
+Better Auth refuses a link whose email differs from the account's unless `allowDifferentEmails`
+is on. Do not merge relay accounts by name: a name proves nothing.
+
+## Several accounts on one device
+
+Linking answers "is this the same person?". Some people really have several accounts, for example
+a parent with their own login and a child's. They should not merge them. `multiSession` lets one
+device hold several signed-in accounts and switch between them without signing out, and
+`signUp: {mode: "closed"}` stops new accounts altogether. Together with the linking mode, these
+are the three knobs an app has over "multiple accounts".
+
+## Migrating users from JWT auth
+
+Apps that started on Terreno's JWT and passport auth already have app `User`s with
+passport-local-mongoose password hashes. When such a user first signs in through Better Auth with
+the same email, Terreno links the new Better Auth user to their existing `User` if either:
+
+- the sign-in comes from a provider (Google, GitHub, Apple, ...) that reports the email as
+  verified, or
+- the password they sign up with verifies against the `User`'s existing passport hash. The
+  plaintext is checked only during that request and never stored. The check does not count as a
+  failed JWT login, so with passport's `limitAttempts` a stranger signing up with the victim's
+  email cannot lock the victim out.
+
+Otherwise the sign-up answers 409 "Verify your email to use this account" and nothing is created.
+Verifying the email afterwards cannot link anything, because there is no Better Auth user to
+verify. Before this change, any unverified sign-up claimed the `User` with the same email, which
+let anyone take over a legacy account by signing up with its address.
+
+Users who signed in with GitHub through JWT have no password hash. They get in one of three ways:
+
+- a provider sign-in whose email the provider verified;
+- a password reset sent to their email through the JWT forgot-password flow
+  (`POST /auth/forgotPassword`), then a Better Auth sign-up with the new password;
+- an admin-issued account recovery link (see [account security](../reference/api.md#better-auth-authentication)
+  once recovery is enabled) that sets their password and creates the Better Auth user.
+
+To migrate smoothly:
+
+1. Keep the JWT auth routes mounted while users move over, so forgot-password still works.
+2. Tell users to sign up with the email and password they already use; those link at once.
+3. Point users without a password at a provider sign-in or at JWT forgot-password.
+
+## Learn more
+
+- [Authentication architecture](authentication.md)
+- [Configure Better Auth](../how-to/configure-better-auth.md)
+- [Better Auth: users and accounts](https://www.better-auth.com/docs/concepts/users-accounts#account-linking)

package/src/docs/versioned/next/explanation/admin-interface.md

@@ -55,7 +55,7 @@ row is `AuditEvent` when `AuditApp` is registered. `isAuditLogModel` also matche
 legacy `AdminAuditLog`, `audit-log`, and `audit-events` names. Jobs is a custom
 screen (`name: "jobs"`); the shell lifts it the same way.
 
-Below 768px the rail becomes a hamburger drawer. The main column is a body-style
+Below the desktop floor (1024pt) the rail becomes a hamburger drawer. The main column is a body-style
 canvas (`neutral-050`, or `neutral-900` in dark mode so `surface.base` cards stand out).
 The colorful teal rail has no dark palette, so dark mode always uses the clinical rail.
 Host apps must give React Navigation a theme that follows the Terreno color scheme