@terreno/mcp 57.19.2 → 57.20.0

package/dist/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/dist/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

package/dist/docs/versioned/next/explanation/agent-guidelines.md

@@ -0,0 +1,173 @@
+# Agent guidelines
+
+An agent writes Terreno-shaped code only when Terreno's conventions are in its context.
+Those conventions reach it through four channels. Each one has a single source of truth,
+and every other copy is generated from it.
+
+| Channel | Source of truth | How the agent gets it | Status |
+| --- | --- | --- | --- |
+| Hosted MCP docs | `docs/`, `website/versioned_docs/`, `mcp-server/src/docs/resources/` | `terreno_search_docs`, `terreno_get_component_docs`, `terreno://docs/*` resources | Shipped |
+| Per-package guidelines | `<package>/.ai/guidelines/core.md` | Merged into the files `terreno_bootstrap_ai_rules` returns | Shipped |
+| App rule files | The app's `.rulesync/rules/` | Generated per editor by `rulesync generate` | Shipped |
+| Agent skills | `plugins/terreno-planning/skills/`, `plugins/terreno-scan/skills/`, `.rulesync/skills/` | `npx skills add TerrenoLabs/terreno` or a host plugin | Shipped |
+
+The runtime side of the loop, meaning what the agent can see in a running app, is covered
+in [AI development loop](ai-development-loop.md). This page covers only conventions.
+
+## Hosted docs and search
+
+The hosted server (`terreno-mcp`) bundles the docs at build time. `sync-versioned-docs`
+copies `docs/` as the `next` version and each `website/versioned_docs/version-*` tree as a
+released version. `sync-ui-docs` copies the component type data.
+
+`terreno_search_docs` runs BM25 over that corpus and the resource pages. It takes several
+queries in one call, an optional package filter, and an optional lockstep `version`. With a
+version, it answers from the nearest retained snapshot, so an app on an older release gets
+that release's guidance.
+
+Resources are the fixed entry points: `terreno://docs/overview`, `api`, `ui`, `syncdb`,
+`rtk`, `patterns`, plus one page per `@terreno/ui` component. A client can read them
+without a tool call.
+
+Search is pull-based. The agent sees nothing until it asks. That is why the search tool's
+own description tells the agent to call it before guessing at Terreno APIs.
+
+## Per-package `.ai/` guidelines
+
+Each core package keeps a short `.ai/guidelines/core.md` next to its code, so a change to
+the package and a change to its guidance land in the same PR. Two packages also carry skill
+copies under `.ai/skills/`.
+
+| Package | `.ai/` contents | In the npm tarball |
+| --- | --- | --- |
+| `@terreno/api` | `guidelines/core.md`, `skills/mongoose-schema-safety/` | Yes (no `files` field) |
+| `@terreno/ui` | `guidelines/core.md` | Yes (`.ai/**/*` in `files`) |
+| `@terreno/rtk` | `guidelines/core.md` | Yes (`.ai/**/*` in `files`) |
+| `@terreno/syncdb` | `guidelines/core.md`, `skills/debug-syncdb-with-mcp/` | No (`files` is `dist` and `src` only) |
+| `@terreno/admin-backend` | `guidelines/core.md` | Yes (no `files` field) |
+| `@terreno/admin-frontend` | `guidelines/core.md` | Yes (`.ai/**/*` in `files`) |
+
+The path that matters today runs through the MCP server, not `node_modules`.
+`mcp-server/scripts/sync-package-guidelines.ts` copies every `.ai/` tree into
+`mcp-server/src/docs/guidelines/<package>/`. `@terreno/mcp` publishes that directory, and
+`terreno_bootstrap_ai_rules` reads it.
+
+Nothing in Terreno reads `node_modules/@terreno/*/.ai/` in a consumer project yet; the
+tarball copies are available to any tool that looks for vendor guidelines there.
+
+Planned (from the per-package guidelines phase of the MCP parity plan, not built):
+
+- Versioned guidelines (`.ai/guidelines/<major>/core.md`) picked by the app's installed
+  version. Guidelines are a single flat `core.md` per package today.
+- Shipping `@terreno/syncdb`'s `.ai/` in its tarball. Its `files` field leaves it out.
+
+## `terreno_bootstrap_ai_rules`
+
+This hosted tool turns the package guidelines into rule files for one app. It does not
+write files. It returns their contents and instructions, and the agent writes them.
+
+| File | Contents |
+| --- | --- |
+| `.rulesync/rules/00-root.md` | The one root rule, for Cursor, Claude Code, Copilot, and `AGENTS.md`: app description, code style, and the merged `core.md` of `api`, `ui`, `rtk`, `syncdb` |
+| `backend/AGENTS.md`, `backend/CLAUDE.md` | Backend conventions, plus the `admin-backend` guidelines when requested |
+| `frontend/AGENTS.md`, `frontend/CLAUDE.md` | Frontend conventions, the MCP servers to use, plus the `admin-frontend` guidelines when requested |
+| `rulesync.jsonc` | rulesync config: `rules` feature, targets `cursor`, `claudecode`, `copilot`, `agentsmd`, `delete: true` |
+
+`packages` narrows the merge. Pass the app's `@terreno/*` dependencies so a project without
+the admin panel gets no admin guidance. Unknown ids are dropped, and an empty result falls
+back to all six packages.
+
+The root rules go through rulesync. The `backend/` and `frontend/` files do not: they are
+direct output, written as-is.
+
+`bunx create-terreno-app` writes its own `.cursorrules` and `CLAUDE.md`. The
+`terreno_bootstrap` prompt tells the agent to run `create-terreno-app` first and this tool
+second.
+
+The returned instructions run `bunx rulesync@9 generate`, the major this repository pins.
+A test in `mcp-server` runs `rulesync generate` on the returned files. From `00-root.md`,
+rulesync writes `.cursor/rules/00-root.mdc`, `CLAUDE.md`, `.github/copilot-instructions.md`,
+and `AGENTS.md`. Windsurf, Codex, and other agents read
+`AGENTS.md`; rulesync 9 has no `windsurf` target. The generated `CLAUDE.md` replaces the
+one `create-terreno-app` wrote, and `.cursor/rules/00-root.mdc` supersedes its
+`.cursorrules`, so delete that file. The root rule contains everything both files said,
+including the "Adding Features" steps.
+
+Earlier versions of the tool also returned `.rulesync/rules/01-claudecode-root.md`, a
+`localRoot` rule that rulesync 9 rejects without a Claude Code `root` rule. Delete that file
+when you re-bootstrap. The root rule now covers Claude Code.
+
+## The `.rulesync/` pattern
+
+This repository and the apps the tool bootstraps follow the same rule. Agent instructions
+are written once under `.rulesync/`, and every editor-specific file is generated from them.
+
+In this repository:
+
+| Source | Generated targets |
+| --- | --- |
+| `.rulesync/rules/**` | `CLAUDE.md`, `.claude/rules/`, `AGENTS.md`, `.cursor/rules/`, `.github/copilot-instructions.md`, `.github/instructions/`, `.devin/rules/` |
+| `.rulesync/skills/`, `.rulesync/subagents/`, `.rulesync/hooks.json` | Per-host skill, subagent, and hook directories (`.claude/`, `.cursor/`, `.github/`, `.devin/`, `.agents/`) |
+| `plugins/terreno-planning/skills/`, `plugins/terreno-scan/skills/`, plus `.rulesync/skills/` | `skills/` (installable set), `plugins/terreno-claude/` and `plugins/terreno-scan-claude/` (Claude Code plugins) |
+
+`rulesync.jsonc` maps each target to its features. `bun run rules` regenerates the rulesync
+targets. `bun run skills:sync` regenerates `skills/` and the Claude plugin. The
+`rulesync-check` workflow regenerates and fails on any diff, and `bun run skills:check` does
+the same for skills.
+
+The config sets `delete: true`. rulesync removes stale generated files before it writes, so
+a generated file holds only what its source says. A hand edit to a generated file is lost
+on the next run.
+
+## Extending the rules in your app
+
+Regeneration replaces two kinds of file. rulesync replaces every generated editor file. A
+re-run of `terreno_bootstrap_ai_rules` returns fresh copies of everything in its table,
+including `00-root.md`, `rulesync.jsonc`, and the `backend/`/`frontend/` agent files. Anything you add to those files is lost.
+
+`rulesync generate` runs with `delete: true`. It overwrites the root `CLAUDE.md`,
+`AGENTS.md`, and `.github/copilot-instructions.md`. It deletes every file under
+`.claude/rules/`, `.cursor/rules/`, `.github/instructions/`, and `.agents/memories/` that
+it did not generate. Before the first `rulesync generate`, and before every later one,
+move any edits to those root files and any hand-written files in those directories into
+`.rulesync/rules/10-project.md` or another `.rulesync/rules/*.md` source. Otherwise they
+are lost.
+
+Keep your conventions in rulesync sources the tool never emits:
+
+1. Leave `00-root.md` untouched. Treat it as Terreno-owned.
+2. Add one or more files such as `.rulesync/rules/10-project.md`. Use a number above `00`
+   and a name the tool does not use.
+3. Scope with `globs` instead of editing `backend/AGENTS.md` or `frontend/AGENTS.md`. A rule
+   with `globs: ["backend/**"]` applies to backend files in every editor.
+4. Run `bunx rulesync@9 generate` and commit the sources and the output together.
+
+```markdown
+---
+targets: ["*"]
+description: "Acme backend conventions"
+globs: ["backend/**"]
+---
+
+# Acme backend
+
+- Store money as integer cents in fields named `*Cents`.
+- Every tenant-scoped model has an `orgId` index.
+```
+
+From one source, rulesync 9 writes `.cursor/rules/10-project.mdc` (`globs`),
+`.claude/rules/10-project.md` (`paths`), `.github/instructions/10-project.instructions.md`
+(`applyTo`), and `.agents/memories/10-project.md` (linked from `AGENTS.md`). A re-bootstrap
+followed by `rulesync generate` leaves these files in place and
+replaces only the Terreno-owned ones.
+
+If you changed `rulesync.jsonc`, for example to add a target, reapply that change after a
+re-bootstrap. The tool returns the default config.
+
+## Related
+
+- [AI development loop](ai-development-loop.md): what the agent sees at runtime
+- [Set up Terreno MCP](../how-to/set-up-terreno-mcp.md): connect both servers to your editor
+- [MCP server reference](../reference/mcp-server.md#terreno_bootstrap_ai_rules): tool parameters
+- [Install agent skills](../how-to/install-agent-skills.md): the skills channel
+- [Planning plugins](planning-plugins.md): how the lifecycle skills are packaged

package/dist/docs/versioned/next/explanation/ai-development-loop.md

@@ -0,0 +1,196 @@
+# AI development loop
+
+A coding agent working on a Terreno app runs the same five-stage loop on every change:
+it asks how something should be done, generates the code, runs the app, observes what the
+app did, and fixes what it finds. Terreno's two MCP servers supply a tool for each stage.
+
+- **`terreno-mcp`** is the hosted server. It holds the docs, the code generators, and the
+  convention validators. It knows Terreno but not your app.
+- **`terreno-mcp-local`** runs in your project over stdio. It reads your app's logs,
+  client state, and database, and drives the running app. It knows your app but not the
+  docs.
+
+```mermaid
+flowchart LR
+  ASK["1. Ask<br/>terreno_search_docs<br/>terreno_get_component_docs<br/>application_info"]
+  GEN["2. Generate<br/>terreno_generate_*<br/>terreno_validate_model_schema"]
+  RUN["3. Run<br/>backend dev server<br/>Metro (Expo)"]
+  OBS["4. Observe<br/>read_logs (backend / browser / metro / app)<br/>last_error<br/>get_client_state"]
+  FIX["5. Fix<br/>edit, then navigate<br/>browser snapshot + screenshot"]
+  ASK --> GEN --> RUN --> OBS --> FIX
+  FIX -->|"iterate"| ASK
+```
+
+This page covers what the agent can see and do at each stage, and where that stops. How
+Terreno's conventions reach the agent in the first place is in
+[Agent guidelines](agent-guidelines.md).
+
+## The five stages
+
+### 1. Ask
+
+The agent looks up the current way to do something before it writes code.
+
+| Tool | Server | Contributes |
+| --- | --- | --- |
+| `application_info` | local | The app's `@terreno/*`, Expo, React Native, and Mongoose versions, so later answers match the installed release |
+| `terreno_search_docs` | hosted | BM25 search over the bundled docs, several queries per call, filtered by package and lockstep `version` |
+| `terreno_get_component_docs` | hosted | The full props table for one `@terreno/ui` component |
+| `terreno_get_upgrade_guide`, `terreno_search_update_notes`, `terreno_get_update_note`, `terreno_ask_update_help` | hosted | Upgrade notes for a version range, and questions against them |
+| `terreno://docs/*` resources | hosted | Fixed entry pages a client can read without a tool call |
+
+Version matters here. An agent that passes the app's version to `terreno_search_docs` gets
+the guidance for the release the app is on, not for the newest one.
+
+### 2. Generate
+
+The agent produces code in Terreno's shape instead of inventing it.
+
+| Tool | Server | Contributes |
+| --- | --- | --- |
+| `terreno_generate_model`, `terreno_generate_route`, `terreno_generate_screen`, `terreno_generate_form_fields` | hosted | A Mongoose model with the standard plugins and types, a `modelRouter` with permissions, an Expo screen, form fields |
+| `terreno_validate_model_schema` | hosted | Checks a schema against the conventions, such as a `description` on every field |
+| `terreno_validate_ui_blocks` | hosted | Checks an agent reply document against the blocks catalog |
+| `terreno_install_admin` | hosted | Admin panel integration snippets |
+| `terreno_bootstrap_ai_rules` | hosted | Rule files for the app's editors |
+
+The generators return file contents and instructions. They do not write files, so the agent
+stays in control of where code lands. A new app is scaffolded by `create-terreno-app`, not by
+an MCP tool.
+
+### 3. Run
+
+The app runs the way a developer runs it: the backend dev server, and Expo's Metro dev
+server for the web, simulator, or device build. There is no special agent runtime. The
+local server attaches to what is already running.
+
+Two pieces of development-only instrumentation make the running app observable:
+
+- The backend's logger writes JSONL to `.terreno/logs/app.log`. By default this is on
+  whenever `NODE_ENV` is not `production`.
+- On web, `installTerrenoDevConsoleLogger` (from `@terreno/syncdb`) forwards `console.error`,
+  `console.warn`, and uncaught errors and rejections to the backend's `POST /__terreno/browser-logs` route, which writes
+  `.terreno/logs/browser.log`. The route exists only in development and is never registered
+  in production. See [Development browser-log ingestion](../reference/api.md#development-browser-log-ingestion).
+
+### 4. Observe
+
+The agent reads what the app did.
+
+| Tool | Contributes |
+| --- | --- |
+| `read_logs` | One merged, time-ordered tail from four sources: `backend` (server JSONL), `browser` (web errors and warnings JSONL), `metro` (bundler events), and `app` (the Hermes console over the Chrome DevTools Protocol). Its `connection` field says which live sources are attached. |
+| `last_error` | The newest error-level entry across the same sources, as the raw line. It includes a stack when the entry carries one. |
+| `get_client_state` | The client data layer in the running app. It reports which `layer` it found (`rtk`, `syncdb`, both, or `none`) and returns the RTK Query cache and auth state, the SyncDB state, or both. `get_rtk_state` is a deprecated alias. |
+| `get_syncdb_state`, `syncdb_snapshot` | SyncDB entities, outbox, conflicts, cursors, and debug events, plus snapshots to compare before and after a change |
+| `database_schema`, `database_query` | The app's MongoDB collections and documents, through a read-only allowlist |
+
+All of these are reads. None of them needs an opt-in.
+
+### 5. Fix
+
+The agent edits code in its own editor, then reproduces the path that failed and checks the
+result.
+
+| Tool | Contributes |
+| --- | --- |
+| `navigate` | Moves a native app to an expo-router path over the same CDP connection the logs use |
+| `browser` | Drives the web app in a headless WebView: open, click, type, scroll, then `snapshot` the rendered page and save a `screenshot` as proof |
+| `evaluate` | Runs a JavaScript expression in the app's Hermes runtime |
+| `syncdb_action` | Changes a live SyncDB client: mutate, flush, resync, resolve conflicts, go offline |
+
+`evaluate`, `navigate`, `syncdb_action`, and the `browser` tool's `evaluate` action run code
+or change state inside the app, so they refuse unless the local server was started with
+`TERRENO_MCP_EVAL=1`. Generated editor configuration never sets it. The other `browser`
+actions do not need it.
+
+After the fix, the loop goes back to Observe. A change is done when the logs and state show
+the new behavior, not when the edit compiles.
+
+## Tool layer versus process layer
+
+The loop is half of how Terreno works with agents. This page covers the tool layer. The
+`/terreno-*` lifecycle skills are the process layer, described in
+[Planning plugins](planning-plugins.md).
+
+| Layer | Answers | Delivered by |
+| --- | --- | --- |
+| **Tool** | What can the agent see and do? | MCP servers: docs search, codegen, merged logs, client state, navigation |
+| **Process** | In what order should the agent work, and who checks it? | `/terreno-*`: question-first planning, TDD, fresh-context independent review, evidence gates, reactive review loop |
+
+The two compose. The lifecycle's build and prove stages use the loop's tools to gather their
+evidence, and the tools are most useful when the lifecycle decides when to call them.
+
+## What makes this different
+
+The agent observes what the app actually did, not a description of it.
+
+Without these tools, an agent learns about a failure from a person's summary, a pasted stack
+trace, or its own guess about what the code should do. With them, it reads the 500 from the
+server log, the uncaught error from the browser console, and the cache entry the screen
+rendered from. It reads them from the same run it just changed.
+
+The rest is table stakes. Docs search, generators, and rule files exist for other frameworks
+too, and Terreno does not claim otherwise.
+
+## What the agent cannot see
+
+The loop ends at the edge of the local development session, and some sources have gaps
+inside it.
+
+- **Production.** The backend log file is off in production by default, the browser-log
+  route is never registered there, and no tool reads a hosted log service. Production errors
+  reach the agent only if a person brings them in.
+- **Native crash reports.** A native crash outside the dev loop, such as an iOS crash report
+  or an Android tombstone, never reaches the JavaScript console, so no log source carries it.
+- **Devices not attached to a dev server.** The `app` source, `navigate`, and `evaluate` reach
+  a runtime only through Metro's inspector. A phone running a release build, or one not
+  connected to Metro, is invisible.
+- **The `app` source on web.** The web build has no Hermes target, so `app` returns nothing
+  there. On web, errors, warnings, and uncaught exceptions arrive through the `browser` source
+  instead; `console.log` and `console.info` reach no source. `app` needs a native
+  development build or Expo Go attached to Metro.
+- **Metro events under Expo CLI.** The `metro` source reads Metro's `/events` socket. In Expo
+  CLI 57 that socket accepts connections but never sends events, so `metro` stays empty even
+  when its status reads connected.
+- **The Hermes debugger connection.** The local server holds one CDP session to the app. On a
+  default `expo start` with current React Native, that session and React Native DevTools
+  coexist. On a target that allows a single debugger, or when Expo runs headless, opening
+  DevTools disconnects the local server. The next call that reads the app reconnects and
+  disconnects DevTools in turn, and console entries logged in between are lost. The
+  `connection` field reports the close reason.
+- **Missing stacks.** `last_error` returns the line as it was logged. If the code logged a
+  message without a stack, there is no stack to return.
+
+## How this composes
+
+Terreno does not build its own simulator or browser automation. It composes with three tools
+that already do it well, and keeps to the part they lack: reading the app's logs, client
+state, and data.
+
+| Tool | Use it for | Lives |
+| --- | --- | --- |
+| `expo-mcp` | Interacting with the iOS simulator or Android emulator: screenshots and taps on the native app | Agent session |
+| Playwright MCP | Interacting with the web app in a full browser while working | Agent session |
+| Maestro | Flows worth keeping, such as login, signup, and creating a todo, committed and run in CI | Repository |
+
+The division of labor:
+
+- **Interaction is the composed servers' job.** `expo-mcp` and Playwright MCP move the app
+  and show what is on screen. Terreno's `browser` tool covers the same ground on web when a
+  lightweight headless session is enough.
+- **Observation is Terreno's job.** After a tap or a click, `read_logs`, `last_error`, and
+  `get_client_state` show what the app did behind the screen.
+- **Durability is Maestro's job.** An agent session ends. A flow that proved a fix and should
+  keep proving it becomes a Maestro flow, so CI repeats the check on every change.
+
+`create-terreno-app` writes `expo` and `playwright` entries next to the two Terreno servers
+in the app's `.cursor/mcp.json` and `.mcp.json`, so a new app starts with all four.
+
+## Related
+
+- [Set up Terreno MCP](../how-to/set-up-terreno-mcp.md): connect the servers to your editor
+- [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md): the loop on a real failure
+- [MCP server reference](../reference/mcp-server.md): every tool, prompt, resource, and variable
+- [Agent guidelines](agent-guidelines.md): how Terreno's conventions reach the agent
+- [Planning plugins](planning-plugins.md): the process layer

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

@@ -37,11 +37,55 @@ Modern session-based authentication with built-in social OAuth support.
 3. Backend redirects to OAuth provider or validates credentials
 4. Better Auth creates session in MongoDB
 5. Frontend receives a session cookie (web, default), a bearer session token (native), or, on web with `webAuth: "bearer"`, a bearer token from the `set-auth-token` header. Bearer on web is the option when the web app and the API are on different sites, where browsers block the third-party session cookie. See [Frontend and API on different sites](../how-to/configure-better-auth.md#frontend-and-api-on-different-sites)
-6. On the first authenticated request or socket handshake, Terreno looks up the app `User` by `betterAuthId` and creates it if missing (`syncBetterAuthUser`). An email alone does not prove someone owns an existing account, so an existing app `User` with the same email is linked only after Better Auth verifies that email, and never when the row already belongs to another Better Auth account. Linking removes a legacy password the row never proved with a verified email. `RealtimeApp` uses the registered `BetterAuthApp` instance for socket sessions without extra wiring
+6. As the session is created, Terreno looks up the app `User` by `betterAuthId` and creates it if missing (`syncBetterAuthUser`), recording the OAuth provider in `oauthProvider`. An email alone does not prove someone owns an existing account, so a Better Auth user claims an existing `User` with the same email only when Better Auth verified that email or its sign-up password matches that `User`'s passport hash; otherwise the sign-up answers 409 "Verify your email to use this account" before any Better Auth user is created. A `User` that already belongs to another Better Auth account is never relinked (409 `ACCOUNT_ALREADY_EXISTS`). Linking through a verified email removes a legacy password the row never proved with a verified email, and bumps `tokenEpoch`. See [Account linking](account-linking.md). The first authenticated request or socket handshake retries the sync if it did not run. `RealtimeApp` uses the registered `BetterAuthApp` instance for socket sessions without extra wiring
 7. `req.user` is that app document for subsequent `modelRouter` permissions. A session whose app `User` has `disabled: true` no longer authenticates: `req.user` stays unset, so protected routes answer 401 and disabling an account ends its live sessions. Better Auth's own routes, such as sign-out, still work
 
 Email/password create omits `oauthProvider`. Apps that never use social login can keep `strict: "throw"` without declaring that field. OAuth create sets `oauthProvider` and the User schema must declare it.
 
+#### Challenges without cookies
+
+Bearer mode sends no cookies, but Better Auth keeps three short-lived values in signed cookies:
+the two-factor challenge set when a sign-in needs a second factor, the trust-device token set
+when the user ticks "trust this device", and the passkey challenge set by the WebAuthn options
+endpoints. A cross-site bearer client never sends them back, so without help it could not finish
+a 2FA or passkey sign-in.
+
+When `twoFactor` or `passkey` is configured, Terreno adds a plugin that carries those cookies in
+the `X-Terreno-Auth-Challenge` header instead:
+
+1. A bearer client sends the header on every `{basePath}/two-factor/*`, `/passkey/*`, and
+   `/sign-in/*` call. It sends `-` when it holds nothing, which opts it in.
+2. For a request that sent the header, the response copies each challenge cookie it sets into
+   the header as `name=value` pairs (URL search params), still signed with the auth secret. Only
+   values that response sets are copied, never cookies the request already had. An expired
+   cookie comes back with an empty value. A `rememberMe: false` sign-in's `dont_remember` cookie
+   rides along with the two-factor challenge, so the verified session stays short. The header is
+   added to `Access-Control-Expose-Headers`, the same way `bearer()` exposes `set-auth-token`.
+   A sign-in answered with a two-factor challenge loses its `set-auth-token`, which named the
+   session two-factor had just deleted.
+3. On those paths the server turns the header back into cookies before Better Auth reads them.
+   A real cookie always wins, and only the challenge cookies (plus `dont_remember`) are accepted. The header can
+   never set a session cookie, and a tampered value fails Better Auth's signature check (the 2FA
+   verify answers 401, a passkey verify 400 `CHALLENGE_NOT_FOUND`, and a tampered trust value
+   just asks for the second factor).
+4. rtk's bearer mode stores the header under `${storagePrefix}_auth_challenge` in the same
+   `bearerStorage` as the bearer token. It never stores a token from a response that asks for a
+   second factor. It drops the 2FA challenge and `dont_remember` after a successful verify, and
+   everything but the trust-device value on sign-out. The trust-device value stays until the server
+   expires it or `trustDeviceDays` runs out, so the device stays trusted across sign-outs.
+
+Clients that do not send the header (cookie mode, native) never receive it, so their challenge
+cookies stay httpOnly. That holds only for requests the page's own code does not send with the
+header: a script on the page that adds it to a sign-in or verify call can read the challenge
+values that call's response sets.
+
+Exposure: in bearer mode the trust-device token lives in web storage beside the bearer token.
+Any XSS on the frontend's origin can read both, and a stolen trust value skips the second factor
+for that account until it expires (it is still useless without the password). Apps that handle
+PHI should pass `bearerStorage: window.sessionStorage`, which ends trust with the tab, and serve
+a strict Content-Security-Policy. See
+[Frontend and API on different sites](../how-to/configure-better-auth.md#frontend-and-api-on-different-sites).
+
 **Key properties:**
 - Session-based (cookies / bearer session) vs. stateless JWT
 - A session cookie is sent with requests other sites start, so a cookie-authenticated write counts only when it comes from a trusted origin. Bearer tokens are never sent automatically, so they need no such check