@terreno/mcp 57.20.0 → 57.21.0

package/src/docs/versioned/next/reference/admin-backend.md

@@ -113,6 +113,29 @@ When `JobsApp` is already registered, the run is enqueued as job `admin/script`
 `defineAdminScriptJob` on the worker process with the same script list. The CLI
 (`runScriptCli`) does not enqueue.
 
+## MCP screens
+
+`mcpAdminModels(options?)` returns model configs for an MCP server's admin screens, in the `MCP` sidebar group:
+
+| Route | Model | Allowed | Notes |
+| --- | --- | --- | --- |
+| `/mcp-service-tokens` | `McpServiceToken` | list, read, delete | Delete sets `revokedAt` |
+| `/mcp-oauth-clients` | `McpOAuthClient` | list, read, delete | Delete removes the registration and revokes every token issued to it |
+| `/mcp-oauth-connections` | `McpOAuthToken` | list, read, delete | One row per token pair; delete revokes the whole family (connection) and keeps the rows |
+| `/mcp-request-log` | `McpRequestLog` | list, read | Needs `mcpRequestLog` on `TerrenoApp` |
+| `/mcp-tools` | `McpToolSetting` | list, read, update | Only `enabled` is writable. Needs `mcpToolSettings` on `TerrenoApp` |
+
+Options: `group` (default `"MCP"`); `requestLog: true` and `toolSettings: true` add those screens. Both default to `false`; set them to match `TerrenoApp`'s `mcpRequestLog` and `mcpToolSettings`. Hash fields are hidden. Each config sets `adminAccess.resource`; with `accessControl`, spread `mcpAdminStatements` into your `createAccess({statements})`.
+
+`mcpAdminScripts()` adds `mcp-sign-out-everywhere` (`--user <id or email>`), which revokes every OAuth connection and service token the user holds. A dry run reports the counts. Email lookup uses the model registered as `User`.
+
+```typescript
+new AdminApp({
+  models: [...appModels, ...mcpAdminModels({requestLog: true, toolSettings: true})],
+  scripts: [...appScripts, ...mcpAdminScripts()],
+});
+```
+
 ## Config Endpoint
 
 `GET {basePath}/config` returns metadata for all registered models:

package/src/docs/versioned/next/reference/admin-spa.md

@@ -139,6 +139,15 @@ new TerrenoApp({userModel: User})
 
 If no bundle exists at `distDir/index.html`, the plugin logs a warning suggesting `bun run --filter '@terreno/admin-spa' build:web` or `devProxyTarget`.
 
+## MCP OAuth consent route
+
+`${basePath}/oauth/consent?request=<id>` is the consent screen for `@terreno/api` MCP OAuth. Set `mcpOAuth.consentUrl` to `${issuer}${basePath}/oauth/consent` on a backend that serves the SPA from the same origin.
+
+- Any signed-in user can open it, not only admins. Admin providers (sync client, org context) do not start on this route.
+- A signed-out user is sent to `${basePath}/login?returnTo=<path>` and returned after sign-in. `returnTo` must start with a single `/` and contain no `\`, scheme, whitespace, or control characters; anything else is ignored.
+- The screen calls `GET /oauth/authorize/:request` and `POST /oauth/authorize/:request/approve` or `/deny` with the Better Auth session cookie, then follows `data.redirectUrl`.
+- States: loading, missing `request`, expired (400), already decided (409), not found, signed out, and error. Test ids start with `admin-spa-oauth-consent-`.
+
 ## Mount path constraint
 
 The default web export is built with `experiments.baseUrl: "/console"`, so `basePath` must match. To mount elsewhere, rebuild with a matching base (e.g. `EXPO_BASE_URL=/admin-ui bun run build:web`) and set `basePath` accordingly. Mounting at `/` requires a root-base build and `basePath: "/"`.

package/src/docs/versioned/next/reference/api.md

@@ -138,6 +138,24 @@ new TerrenoApp({
 
 `mcpServiceTokens: true` is `{enabled: true}`. When enabled, TerrenoApp mounts the self-serve routes (passing its OpenAPI bundle) and sets `mcpServiceTokens` on MCP auth. Operator steps: [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md).
 
+### MCP request log and tool settings
+
+Both are opt-in and off by default.
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpRequestLog: {enabled: true, retentionDays: 30}, // `true` is {enabled: true, retentionDays: 30}
+  mcpToolSettings: true,
+});
+```
+
+- `mcpRequestLog` writes one `McpRequestLog` row per `tools/call`: `toolName`, `userId`, `credential`, `serviceTokenId` or `oauthClientId` + `oauthFamilyId`, `durationMs`, `outcome` (`ok`, `tool_error`, `exception`), `errorName` (the error class only), and `expiresAt` (TTL index). Tool arguments, results, and error messages are never stored. Writes are fire-and-forget: a failed write is logged at debug level and never fails or delays the tool call. `retentionDays` must be positive; it applies to rows written after a change.
+- `mcpToolSettings` upserts one `McpToolSetting` row per tool when `/mcp` mounts (`name`, `description`, `source`: `model` or `custom`, `registered`, `lastRegisteredAt`). `enabled` is set to `true` only on insert, so a restart never undoes an admin's switch. Tools no longer registered get `registered: false`; rows are never deleted. Each `/mcp` request leaves out tools with `enabled: false`, so they are missing from `tools/list` and `tools/call` answers with an unknown-tool error. A tool without a row is served. `McpToolSetting.disabledNames()` caches the disabled set per process for 5 seconds; any write through the model clears it, so other instances see a switch within 5 seconds. A failed read reuses the last known set, or fails the request when there is none.
+- `MCPAuthResult` carries `serviceTokenId`, `oauthClientId`, and `oauthFamilyId` (identifiers, never secrets) for these rows.
+
+Admin screens for both, plus service tokens and OAuth clients and connections: [Manage MCP from the admin panel](../how-to/manage-mcp-in-admin.md).
+
 ### Audit log (`AuditApp`)
 
 Opt-in append-only log. Register the plugin; importing `@terreno/api` does **not** compile `AuditEvent` onto the default mongoose connection. The compiled Mongoose name is `TerrenoAuditEvent` on collection `auditevents`. Admin UI and RBAC keep `AuditEvent` / `adminAuditEvent`.
@@ -376,7 +394,7 @@ const {mcpServiceToken, token} = await McpServiceToken.issueFor(
 // Store or show `token` once. Only its SHA-256 hash is persisted.
 ```
 
-The token begins with `mcp_` followed by 32 random bytes encoded as hex. `issueFor` records the user's `tokenEpoch` (pass it on the user argument; default 0). `/mcp` refuses a token whose recorded epoch differs from the user's current `tokenEpoch` and sets its `revokedAt`, so a password reset, Better Auth password change, or session revocation ends every key minted before it. A row stored without `tokenEpoch` counts as epoch 0. `revokeOutdatedForUser(user)` revokes the user's keys from earlier epochs; the list and create routes call it so the list shows them as revoked. `verify(token)` returns `null` for unknown, expired, or revoked tokens. `revokeForUser(user, tokenId)` records `revokedAt`, and `countActiveForUser(userId)` excludes expired or revoked records. Document `deleteOne` (admin DELETE) also sets `revokedAt` and leaves the row for audit. Never return or log `tokenHash` or the plaintext token outside the initial issue result.
+The token begins with `mcp_` followed by 32 random bytes encoded as hex. `issueFor` records the user's `tokenEpoch` (pass it on the user argument; default 0). `/mcp` refuses a token whose recorded epoch differs from the user's current `tokenEpoch` and sets its `revokedAt`, so a password reset, Better Auth password change, or session revocation ends every key minted before it. A row stored without `tokenEpoch` counts as epoch 0. `revokeOutdatedForUser(user)` revokes the user's keys from earlier epochs; the list and create routes call it so the list shows them as revoked. `verify(token)` returns `null` for unknown, expired, or revoked tokens. `revokeForUser(user, tokenId)` records `revokedAt`, and `countActiveForUser(userId)` excludes expired or revoked records. Document `deleteOne` (admin DELETE) also sets `revokedAt` and leaves the row for audit. `revokeAllForUser(userId)` revokes every active token the user holds and returns the count. Never return or log `tokenHash` or the plaintext token outside the initial issue result.
 
 Self-serve HTTP routes live at `/mcp/service-tokens`. `TerrenoApp` mounts them when `mcpServiceTokens` is enabled, passing its OpenAPI bundle. You can also call `addMcpServiceTokenRoutes(app, {publicMcpUrl, openApi})` yourself. They require session or JWT auth and **reject** `Authorization: Bearer mcp_…` so a service token cannot mint or list tokens.
 
@@ -437,7 +455,7 @@ The consent endpoints are in OpenAPI (`getMcpOAuthRequest`, `approveMcpOAuthRequ
 
 Tokens are opaque (`mcpat_` access, `mcprt_` refresh) and stored only as SHA-256 hashes in `McpOAuthToken`. Each refresh rotates the pair; reusing a rotated refresh token revokes every pair issued from that authorization (its family). Codes are single-use: a failed exchange burns the code, and replaying a used code revokes the tokens it issued. The code exchange fixes the family id when it consumes the code, so a replay can revoke the family before its tokens exist. A `client_credentials` token has no refresh token. Its document still stores a unique hash of a discarded secret so the `refreshTokenHash` unique index is unchanged, and `hasRefreshToken: false` rejects that hash if it is ever presented. `McpOAuthClient.revoke(clientId)` revokes every family issued to that client. An authorization-code exchange, a refresh, or a client_credentials grant that loses a race with that revoke is discarded instead of returned. `deleteOne`, `findOneAndDelete`, and `deleteMany` revoke those families too. A query `deleteOne` or `findOneAndDelete` whose filter matches several clients deletes one of them and revokes that client's tokens. `bulkWrite` bypasses the hooks.
 
-`McpOAuthToken.revokeFamily(familyId)` first writes an `McpOAuthRevokedFamily` tombstone, then revokes every pair in the family. `McpOAuthToken.issue` refuses a tombstoned family with `McpOAuthFamilyRevokedError` (the token endpoint answers `invalid_grant`), and checks again after creating the pair, revoking it if a revoke landed meanwhile. A request that won a rotation or code exchange before a concurrent revoke therefore cannot leave a live pair behind. Tombstones expire after the family's last refresh expiry, and at least one hour after the revoke.
+`McpOAuthToken.revokeFamily(familyId)` first writes an `McpOAuthRevokedFamily` tombstone, then revokes every pair in the family. `McpOAuthToken.issue` refuses a tombstoned family with `McpOAuthFamilyRevokedError` (the token endpoint answers `invalid_grant`), and checks again after creating the pair, revoking it if a revoke landed meanwhile. A request that won a rotation or code exchange before a concurrent revoke therefore cannot leave a live pair behind. Tombstones expire after the family's last refresh expiry, and at least one hour after the revoke. Deleting an `McpOAuthToken` row (document `deleteOne` or query `deleteOne`, as the admin panel does) calls `revokeFamily` for that row's family and keeps every row, so the connection ends and its history stays. `deleteMany` and `bulkWrite` still remove rows without revoking. `McpOAuthToken.revokeAllForUser(userId)` revokes every active family the user holds and returns how many.
 
 Models: `McpOAuthClient` (`mcpoauthclients`), `McpOAuthAuthorization` (`mcpoauthauthorizations`, TTL on `expiresAt`), `McpOAuthToken` (`mcpoauthtokens`, TTL on `refreshExpiresAt`), `McpOAuthRevokedFamily` (`mcpoauthrevokedfamilies`, unique `familyId`, TTL on `expiresAt`).
 

package/src/docs/versioned/next/reference/lifecycle-plugin.md

@@ -1,6 +1,6 @@
 # Lifecycle plugin reference
 
-Plugin: `terreno-planning` (`2.12.0`)
+Plugin: `terreno-planning` (`2.14.0`)
 
 Planning skills are model-invocable: agents may select them from descriptions, not only
 from slash commands. Grow, Brew, and Taste each implement one bounded transition. Pick continues an inner loop until the
@@ -149,6 +149,10 @@ and `.codex-plugin/plugin.json` on the canonical plugin. Claude Code:
 /plugin install terreno@terreno-plugins
 ```
 
+That tracks `master`. For a pinned release or the latest release from npm
+(`@terreno/agent-plugin`, marketplace `terreno-releases`), see
+[Install agent skills](../how-to/install-agent-skills.md#pick-a-channel).
+
 Claude Code resolves a plugin skill's command from the frontmatter `name`, so the short
 names ship as a generated Claude-only copy at
 [`plugins/terreno-claude/`](https://github.com/TerrenoLabs/terreno/tree/master/plugins/terreno-claude).
@@ -165,3 +169,137 @@ docs, upgrade, deployment, and UI-verification workflows, plus `pre-commit` and
 `ui-verifier` agents on Cursor and Claude Code. Codex consumes the combined skills
 without plugin-defined agents. Repository-local skills supply only project-specific
 roadmap, release, and maintenance conventions discovered at stage start.
+
+## Testing plan
+
+Every IP plans its e2e tests and its manual regression cases up front, per
+[testing-plan.md](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/testing-plan.md).
+Grow writes both sections; later stages read them and never invent rows.
+
+| Stage | Duty |
+| --- | --- |
+| Grow | Reads the spot, writes `## E2E tests` and `## Regression cases`, adds a guide-writing task when no e2e guide exists |
+| Pick | Writes each `## E2E tests` row whose `Written in` names the current task, at its path, following the e2e guide |
+| Roast | Runs the task's rows (missing or failing is `FAIL`, unreachable is `deferred`) and holds regression rows to the regression-step bar |
+| Brew | Gates on every row passing, merges regression rows into the suite with the next free ID, lists the IDs in the PR `Verification` section |
+| Taste | Re-runs affected rows after a behaviour-changing fix, renumbers regression ID collisions with the base, runs the declared `Smoke command` before push |
+
+### Standardized spot
+
+The e2e guide is `docs/testing/e2e.md` and the suites live in `docs/regression/`. A repo
+with a different layout overrides them with a `## Testing conventions` table in AGENTS.md
+or CLAUDE.md:
+
+```markdown
+## Testing conventions
+
+| Key | Value |
+| --- | --- |
+| E2E guide | docs/testing/e2e.md |
+| Regression suites | docs/regression/ |
+| Smoke command | bun run smoke:local |
+```
+
+Set `Regression suites` to `none` to opt out of manual regression suites. Every IP's
+`## Regression cases` then reads `None — regression suites opted out`, Brew and Taste skip
+all suite work, and `backfill-regression` stops at once. E2E tests are unaffected.
+
+### IP sections
+
+Both sections are required. Either may be `None — <reason>`; neither may be missing. An
+IP approved before the contract reads as `None — predates contract`, and stages warn
+instead of failing. Regression IDs in an IP are provisional (`<AREA>-new-<n>`).
+
+```markdown
+## E2E tests
+
+| ID | Spec or flow | Layer | Proves | Written in |
+| --- | --- | --- | --- | --- |
+| E1 | `e2e/todos-due-date.spec.ts` | browser | A user sets a due date and sees it in the list | T2 |
+
+## Regression cases
+
+Destination: TODO → docs/regression/todos.md
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| TODO-new-1 | Due date survives a reinstall | Signed in on a phone with one dated todo, delete and reinstall the app, then sign in | The todo shows the same due date | iOS, Android | manual | todos-due-date |
+```
+
+A stage that cannot reach a row's layer records it `deferred` with its exact command.
+Only Brew accepts a deferred row, and only after that command passes locally or in
+product CI on the branch.
+
+### Suite file format
+
+One living file per area at `<Regression suites>/<area>.md`. IDs are `<AREA>-NNN` and
+never reused; Brew assigns the next free ID when it writes the case.
+
+```markdown
+# Todos regression suite
+
+Area: TODO
+Owner: mobile team
+Last full run: never
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| TODO-001 | Due date survives a reinstall | Signed in on a phone with one dated todo, delete and reinstall the app, then sign in | The todo shows the same due date | iOS, Android | manual | todos-due-date |
+```
+
+## User guide
+
+Every IP says which end-user guide pages it adds, updates, or retires, per
+[user-guide.md](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/user-guide.md).
+A page explains one feature in the words users see on screen. Chat agents read the pages
+to answer "how do I…" questions, so a page describes shipped behavior only.
+
+| Stage | Duty |
+| --- | --- |
+| Grow | Writes `## User guide` rows (`G<n>`), or `None — <reason>`, and a `User guide:` line in the brief |
+| Pick | Writes or edits each page whose row names the current task, and updates the guide index |
+| Roast | Holds each page to the guide-entry bar and checks its steps against the shipped screens |
+| Brew | Confirms every row's page exists or is retired and the index matches the pages on disk |
+| Taste | Updates affected pages after a fix that changes user-visible behavior |
+
+### Spot and opt-out
+
+The guide lives in `docs/user-guide/`, one page per feature at `<area>/<feature>.md`, with
+a `README.md` index. A repo overrides the path, or opts out, with a
+`## User guide conventions` table in AGENTS.md or CLAUDE.md:
+
+```markdown
+## User guide conventions
+
+| Key | Value |
+| --- | --- |
+| User guide | none — command-line tool with no in-app users |
+```
+
+With `none`, Grow writes `None — user guide off` and every stage, check, and backfill
+skips the guide.
+
+### Page format
+
+```markdown
+---
+title: Set a due date on a todo
+area: todos
+audience: user            # user | admin | staff
+platforms: [web, ios, android]
+questions:
+  - How do I set a due date on a todo?
+added: todos-due-date     # IP slug, or user-guide-backfill
+---
+
+# Set a due date on a todo
+
+## What it does
+## How to use it         # numbered steps naming on-screen labels in bold
+## Intended use          # what it is for, and what it is not for
+```
+
+`questions` is what retrieval matches; `audience` keeps a chat agent from describing an
+admin feature to a user. Pages never hold personal or health information, secrets, or
+internal URLs. The `backfill-user-guide` skill drafts pages for features that shipped
+before the contract and writes only the ones the human approves.

package/src/docs/versioned/next/reference/scan-plugin.md

@@ -1,6 +1,6 @@
 # Scan plugin reference
 
-Plugin: `terreno-scan` (`2.11.0`). Requires the lifecycle plugin
+Plugin: `terreno-loop` (`2.12.0`). Requires the lifecycle plugin `2.14.0` or later
 ([lifecycle plugin reference](lifecycle-plugin.md)).
 
 A scan turns a long-term outcome — "cold builds under 30s", "no unbounded reads", "WCAG
@@ -12,22 +12,22 @@ Scan stages never edit product code. The lifecycle does.
 
 | Skill | Preconditions | Primary output | PASS next |
 | --- | --- | --- | --- |
-| `terreno-scan-1-aim` | goal/outcome + repository | approved charter: metric, measured baseline, dry-run rules, exclusions, validity rule, severity rubric, slice policy, budget | Sweep |
-| `terreno-scan-2-sweep` | approved charter | per-rule hits, deterministic shard manifest, schema-valid candidate findings from parallel workers | Sift |
-| `terreno-scan-3-sift` | candidates for the round | deduped, adversarially verified, ranked findings report plus dropped-candidate summary | Plot, or Track when dry |
-| `terreno-scan-4-plot` | findings report + slice policy | ordered PR-sized slices, one standalone Grow brief each, findings marked `planned` | Track, with `handoff: grow` |
-| `terreno-scan-5-track` | landed slice or dry round | re-measured metric with command output, findings closed/reopened with evidence, round record, next move | Plot, Sweep, or `null` |
+| `terreno-loop-1-aim` | goal/outcome + repository | approved charter: metric, measured baseline, dry-run rules, exclusions, validity rule, severity rubric, slice policy, budget | Sweep |
+| `terreno-loop-2-sweep` | approved charter | per-rule hits, deterministic shard manifest, schema-valid candidate findings from parallel workers | Sift |
+| `terreno-loop-3-sift` | candidates for the round | deduped, adversarially verified, ranked findings report plus dropped-candidate summary | Plot, or Track when dry |
+| `terreno-loop-4-plot` | findings report + slice policy | ordered PR-sized slices, one standalone Grow brief each (with `## E2E tests` and `## Regression cases`), findings marked `planned` | Track, with `handoff: grow` |
+| `terreno-loop-5-track` | landed slice or dry round | re-measured metric with command output, findings closed/reopened with evidence, round record, next move | Plot, Sweep, or `null` |
 
 Outer loops (not stages):
 
 | Skill | What it walks | Default |
 | --- | --- | --- |
-| `terreno-scan-campaign` | One goal, round after round | Aim once, then Sweep → Sift → Plot → lifecycle → Track until the metric hits target, the budget is spent, or a genuine human gate is reached. Stops at each gate. |
-| `terreno-scan-loop` | The same, but resident | Keeps the campaign moving **and** heartbeats over every open campaign PR — routing it to a reviewer, answering review comments through Taste, fixing red CI, tracking merges — refilling work as PRs land. Runs until the goal is met, a stop argument fires, or a human decision is required. |
+| `terreno-loop-campaign` | One goal, round after round | Aim once, then Sweep → Sift → Plot → lifecycle → Track until the metric hits target, the budget is spent, or a genuine human gate is reached. Stops at each gate. |
+| `terreno-loop-run` | The same, but resident | Keeps the campaign moving **and** heartbeats over every open campaign PR — routing it to a reviewer, answering review comments through Taste, fixing red CI, tracking merges — refilling work as PRs land. Runs until the goal is met, a stop argument fires, or a human decision is required. |
 
 ## Resident loop
 
-`terreno-scan-loop` is the "leave it running" entry point. One session holds the goal,
+`terreno-loop-run` is the "leave it running" entry point. One session holds the goal,
 the state, and the schedule; every unit of work happens in a fresh subagent.
 
 Arguments: `goal=<slug>`, `reviewer=<handle[,handle]>`, `assignee=<handle>`, `wip=<n>`,
@@ -42,7 +42,7 @@ priority order:
 | `unrouted` | Apply the charter's routing, then count the slice in flight |
 | `answered` | A human commented or requested changes → one `terreno-5-taste` in a fresh subagent |
 | `broken` | CI failed or the PR conflicts → one `terreno-5-taste` |
-| `merged` | → `terreno-scan-5-track`: re-measure, close findings with evidence |
+| `merged` | → `terreno-loop-5-track`: re-measure, close findings with evidence |
 | `closed` | Mark the slice abandoned, return its findings to `open`, free its slot |
 | `bot-pending`, `waiting` | Nothing — this is why the next tick exists |
 
@@ -51,7 +51,7 @@ watch hook while CI runs, 2–5 minutes while review bots report, 15–30 minute
 human holds the PR, and no wait at all while backlog work remains. Ticks that find
 nothing print nothing, and every comment is answered exactly once — answered ids live in
 state. See
-[`heartbeat.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/heartbeat.md).
+[`heartbeat.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-loop/references/heartbeat.md).
 
 ## PR routing
 
@@ -65,7 +65,7 @@ Routing is applied right after Brew reports the PR (`gh pr edit --add-reviewer
 --add-assignee --add-label`) and re-requested once when requested changes are addressed.
 The campaign never approves its own PRs, never dismisses a review, and never merges when
 `mergePolicy` is `human` — the default. See
-[`pr-routing.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/pr-routing.md).
+[`pr-routing.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-loop/references/pr-routing.md).
 
 ## Stage anatomy
 
@@ -74,11 +74,11 @@ produced, Success/Failure/Blocked conditions, and a recommended next stage — t
 shape as the lifecycle stages.
 
 Results use `PASS`, `FAIL`, `BLOCKED`, or `PENDING` and the compact `v: 2`
-[`scan-result.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/scan-result.schema.json)
+[`scan-result.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-loop/references/scan-result.schema.json)
 (`v`, `stage`, `status`, `next`, `action`; omit empty keys). Campaign state follows
-[`scan-state.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/scan-state.schema.json)
+[`scan-state.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-loop/references/scan-state.schema.json)
 and findings follow
-[`finding.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/finding.schema.json).
+[`finding.schema.json`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-loop/references/finding.schema.json).
 Chat shows `status` / `next` / `action` plus the current metric; the YAML lives in a
 Details toggle.
 
@@ -93,7 +93,7 @@ large, never spawn nested agents, and never edit files. Sift then dedupes by
 keeping it, drops what does not reproduce, and ranks by impact × confidence ÷ effort.
 Dropped shards and capped coverage are always reported; silent truncation is a defect.
 See
-[`mapreduce.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/mapreduce.md).
+[`mapreduce.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-loop/references/mapreduce.md).
 
 ## Goal and metric
 
@@ -102,7 +102,7 @@ came from running it. Track re-runs that command with the charter's protocol eve
 and records the value with its output. A finding that cannot be tied to the metric is
 dismissed in Sift, not deferred. Re-baselining without recording both values, the reason,
 and the round is untrustworthy and Track says so. See
-[`goal-tracking.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-scan/references/goal-tracking.md).
+[`goal-tracking.md`](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-loop/references/goal-tracking.md).
 
 ## Artifacts
 
@@ -138,20 +138,20 @@ to Grow, and the lifecycle takes it from there.
 
 | Host | Plugin | Invoke Aim | Invoke the campaign |
 | --- | --- | --- | --- |
-| Cursor | `terreno-scan` | `/terreno-scan-1-aim` | `/terreno-scan-campaign` |
-| Codex | `terreno-scan` | `$terreno-scan-1-aim` | `$terreno-scan-campaign` |
-| Claude Code | `terreno-scan` | `/terreno-scan:1-aim` | `/terreno-scan:campaign` |
+| Cursor | `terreno-loop` | `/terreno-loop-1-aim` | `/terreno-loop-campaign` |
+| Codex | `terreno-loop` | `$terreno-loop-1-aim` | `$terreno-loop-campaign` |
+| Claude Code | `terreno-loop` | `/terreno-loop:1-aim` | `/terreno-loop:campaign` |
 
-The resident loop is `/terreno-scan-loop` (Cursor), `$terreno-scan-loop` (Codex), and
-`/terreno-scan:loop` (Claude Code).
+The resident loop is `/terreno-loop-run` (Cursor), `$terreno-loop-run` (Codex), and
+`/terreno-loop:run` (Claude Code).
 
-`plugins/terreno-scan/` is canonical. `plugins/terreno-scan-claude/` is generated with
+`plugins/terreno-loop/` is canonical. `plugins/terreno-loop-claude/` is generated with
 shortened skill names; regenerate it with `bun run skills:sync` and never hand-edit it.
 
 ## Example
 
 ```text
-/terreno-scan:loop reduce cold compile time reviewer=octocat wip=2
+/terreno-loop:run reduce cold compile time reviewer=octocat wip=2
 ```
 
 Aim grills the target (30s), measures the baseline with `bun run compile` on a clean

package/src/docs/versioned/next/reference/test.md

@@ -1,6 +1,6 @@
 # @terreno/test
 
-Shared Bun test helpers for Terreno backend packages: in-memory MongoDB lifecycle, auth env defaults, HTTP fixtures, and log silencing.
+Shared Bun test helpers for Terreno packages: in-memory MongoDB lifecycle, auth env defaults, HTTP fixtures, log silencing, and real-process smoke helpers.
 
 ## Install
 
@@ -79,7 +79,7 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 | Variable | Effect |
 |----------|--------|
 | `TERRENO_TEST_USE_MEMORY_MONGO` | When `"true"`, `registerSimpleMongoPreload` starts `mongodb-memory-server` if `TERRENO_TEST_MONGODB_URI` is unset. |
-| `TERRENO_TEST_MONGODB_URI` | External MongoDB URI. Takes priority over in-memory server in `startMongoServer` and `registerSimpleMongoPreload`. |
+| `TERRENO_TEST_MONGODB_URI` | External MongoDB URI. Takes priority over in-memory server in `startMongoServer`, `registerSimpleMongoPreload`, and `smokeMongoUri`. |
 | `TERRENO_TEST_MONGO_LAUNCH_TIMEOUT_MS` | Per-mongod start timeout for in-memory servers started by `startMongoServer`. Default `60000` (mongodb-memory-server's own default is 10s). Startup is tried twice. |
 | `BUN_TEST_DISABLE_DB` | When `"true"`, `registerBackendPreload` skips all Mongo `beforeAll`/`afterAll` hooks (no DB startup). |
 
@@ -282,6 +282,54 @@ per-file, per-rule counts so CI fails only on new violations. Suppress one line
 `test-hygiene-disable-next-line <rule>[, <rule>]` comment. Exit codes: 0 clean, 1 new
 violations, 2 usage error.
 
+## Smoke helpers
+
+A package smoke is a real-process check of the package's built output. It lives in
+`<package>/e2e/smoke.ts` (`e2e/smoke.spec.ts` for browser packages), runs with the package's
+`smoke` script after `bun run compile`, and takes 30 s or less. It starts a server on a real
+port, runs the compiled binary, or opens a page, then walks one happy path. It exits non-zero on
+the first failed check. These helpers do the process work:
+
+| Export | Description |
+|--------|-------------|
+| `freePort()` | An unused TCP port on `127.0.0.1`. |
+| `smokeMongoUri({databaseName?})` | MongoDB URI with the database name (default `terrenoSmoke`). Uses `TERRENO_TEST_MONGODB_URI` when set (the CI sidecar). Otherwise it starts one single-node in-memory replica set per process, so change streams work. `stopSmokeMongo()` stops it. |
+| `spawnUntilReady({cmd, url, timeoutMs?, cwd?, env?, stopGraceMs?})` | Starts a long-running child and resolves once `url` answers 2xx (default timeout 20 s). Returns `{pid, output, stop}`. It rejects with the child's output when the child exits first or is not ready in time. `stop()` sends SIGTERM, then SIGKILL after `stopGraceMs` (default 5 s). |
+| `spawnExampleBackend({mongoUri, port?, env?, timeoutMs?, backendDir?})` | Starts the monorepo's `example-backend` by path with dev auth secrets and the demo AI model, then waits for `/health` (default timeout 60 s). `env` overrides the defaults; `backendDir` points at another directory holding `src/index.ts`. Returns `{baseUrl, port, pid, output, stop}`. Client smokes (rtk, syncdb, admin-frontend, example-frontend) use it, so they never import `@terreno/api`. Its `stop()` waits only 0.5 s after SIGTERM: example-backend's SIGTERM hook stops the jobs worker but keeps serving, so a longer grace only adds time. |
+| `runBin({bin, args?, cwd?, env?, timeoutMs?})` | Runs a binary to completion and resolves `{exitCode, stdout, stderr}`. A `.js`, `.mjs`, `.cjs`, or `.ts` path runs with Bun. Running past `timeoutMs` (default 30 s) rejects. Background processes the binary leaves behind are killed when it exits. |
+
+Each child that `spawnUntilReady`, `spawnExampleBackend`, or `runBin` starts runs in its own
+process group. `stop()`, a timeout, and the smoke process exiting, crashing, or receiving
+`SIGINT` or `SIGTERM` kill the whole group, so a wrapper command (`sh -c`, `bun run`) and the
+server it started both die and no server is left on a port. A smoke killed with `SIGKILL`
+cannot clean up.
+
+A server smoke can host its own server by re-running its file with an argument, which keeps
+one file per package. `api/e2e/smoke.ts` is the reference:
+
+```typescript
+import {freePort, smokeMongoUri, spawnUntilReady, stopSmokeMongo} from "@terreno/test";
+
+const port = await freePort();
+const server = await spawnUntilReady({
+  cmd: [process.execPath, __filename, "serve"],
+  env: {MONGO_URI: await smokeMongoUri({databaseName: "apiSmoke"}), PORT: String(port)},
+  url: `http://127.0.0.1:${port}/health`,
+});
+try {
+  // fetch() the happy path and throw on the first unexpected response
+} finally {
+  await server.stop();
+  await stopSmokeMongo();
+}
+```
+
+Run one package's smoke with `bun run --cwd <package> smoke`. From the repo root,
+`bun run smoke` runs every workspace's `smoke` script one at a time and prints each package's
+time. It keeps going after a failure and exits 1 if any package failed. Pass workspace
+directory names to run a subset: `bun run smoke api rtk`. Naming a workspace that does not
+exist or has no `smoke` script is an error.
+
 ## Conventions
 
 - Preload once per package via `bunfig.toml`; do not start Mongo in individual test files.

package/src/docs/versioned/next/reference/ui.md

@@ -112,6 +112,33 @@ Figma AI surface/border roles and the dark status ramps. Custom overrides set
 through `useTheme()` are layered over the active mode; `resetTheme()` removes
 those overrides without changing the provider's selected mode.
 
+### Field theme
+
+The `field` section colors the input box of `TextField` (and the fields built on it, such as
+`TextArea`, `EmailField`, `NumberField`, and `PasswordField`), `SelectField`, `DateTimeField`,
+`HeightField`, and `OtpField`. Each token maps to a primitive key:
+
+| Token | Used for | Light | Dark |
+|---|---|---|---|
+| `background` | Enabled input background | `neutral000` | `neutral800` |
+| `backgroundDisabled` | Disabled input background | `neutral300` | `neutral600` |
+| `border` | Border at rest | `neutral500` | `neutral300` |
+| `borderFocus` | Border while focused | `primary200` | `primary200` |
+| `borderError` | Border when the field has an error | `error100` | `error050` |
+| `borderDisabled` | Border when disabled | `neutral700` | `neutral100` |
+
+```tsx
+const {setTheme} = useTheme();
+setTheme({field: {background: "neutral050", border: "neutral300", borderFocus: "primary500"}});
+```
+
+The defaults equal the `surface` and `border` tokens fields used before, so fields look the
+same unless you set `field`. Fields no longer follow `surface.base`, `surface.neutralLight`,
+`border.dark`, `border.focus`, `border.error`, or `border.activeNeutral`; restyle them through
+`field` instead. `DateTimeField` keeps `surface.disabled` for its disabled time picker.
+`MarkdownEditorField` and the native address autocomplete keep their own `border.default`
+styling.
+
 ### DashboardGrid and DashboardGridItem
 
 Eager layout-only wrapping grid. Default columns `{sm: 1, md: 2, lg: 3}`. Children stay caller-supplied `Card`s. Cell width is `(rowWidth - gap × (columns - 1)) / columns` so flex `gap` does not wrap extra columns.

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

@@ -0,0 +1,87 @@
+# Regression suites
+
+Run `bun run check:regression-suites` after you edit any file here. CI runs the same check in
+the `repo-policies` job.
+
+These files hold a minimal manual pass a developer or QA walks before a release: a short check
+that the app works as intended, plus the behavior no unit test, smoke, or e2e spec can reach,
+such as push notifications, real email delivery, other hardware or operating-system behavior,
+full flows across devices, and how the app feels. Keep them small. Most features add no case
+here, and anything an e2e spec can drive and assert belongs in an e2e spec instead. Each area
+has one living file. Implementation plans
+propose cases under `## Regression cases`, and Brew writes them here with real IDs before it
+opens the pull request. See [Where regression suites live](../testing/e2e.md#where-regression-suites-live)
+for how this tier fits with the automated ones.
+
+## Areas
+
+| File | Area | Covers |
+| --- | --- | --- |
+| [planning.md](planning.md) | `PLAN` | Retired: planning-stage checks, kept so their IDs are never reused |
+| [auth.md](auth.md) | `AUTH` | Email delivery for password reset and verification, and native session storage |
+| [admin.md](admin.md) | `ADMIN` | Admin edits and announcements seen live on a phone |
+| [syncdb.md](syncdb.md) | `SYNC` | Offline writes, persistence across an app kill, and account switches on a device |
+| [ui-native.md](ui-native.md) | `NATIVE` | Notification permission prompts, finger-drawn signatures, and keyboard behavior on iOS and Android |
+
+## Suite format
+
+Every file follows the same shape:
+
+```markdown
+# Auth regression suite
+
+Area: AUTH
+Owner: <team or person>
+Last full run: 2026-01-15 (<who>, <short sha>)
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| AUTH-001 | ... | ... | ... | ... | manual | <IP slug> |
+```
+
+- **Title** is the first line, a `#` heading.
+- **`Area:`** declares the ID prefix: uppercase letters and digits. Find a suite by this line,
+  not by its file name. No two files declare the same area.
+- **`Owner:`** names the team or person who keeps the file current.
+- **`Last full run:`** is `never`, or the date, who walked it, and the short commit SHA. Change
+  it only after a person walks every case in the file.
+- **IDs** are `<AREA>-NNN`, zero-padded to three digits, and never reused. The next free ID is
+  one past the highest the file has ever held. A retired case keeps its row with `Retired` in
+  `Expected`. Provisional IP IDs such as `AUTH-new-1` never appear here.
+- **Steps** name a concrete starting state (who is signed in, what data exists, which build or
+  device), then an action a person can follow without guessing.
+- **Expected** is observable: what is on screen, in the inbox, or in the response. "It works"
+  or a restatement of the action does not count.
+- **Automated by** is `manual` or the path of the spec that covers the case. It never names an
+  IP-local `E<n>` row.
+- **Added** is the slug of the implementation plan that added the case.
+
+Escape a literal pipe inside a cell as `\|`.
+
+## What the check enforces
+
+`scripts/regression/checkSuites.ts` reads every `.md` file here except this README and fails
+when a file:
+
+- lacks the title, `Area:`, `Owner:`, or `Last full run:` line, or one of them is malformed
+- has a table whose columns differ from the seven above, or more than one table
+- has a row with the wrong number of cells, an ID that is not `<AREA>-NNN`, a `-new-` ID, or a
+  duplicate ID
+- has an empty cell, including Steps and Expected
+- names an `E<n>` row in Automated by
+
+It also fails when two files declare the same area. It does not judge whether a step meets the
+bar above; reviewers do.
+
+## Add a case
+
+1. Open the area's file, or create `<area>.md` with `Last full run: never` and an `Owner:`.
+2. Add a row with the next free ID.
+3. Run `bun run check:regression-suites`.
+
+## Backfill the suites
+
+To find cases an older feature should have had, run the `backfill-regression` skill. It
+surveys the app for behavior automation cannot reach, proposes cases one area at a time, and
+writes only the sets you approve. It records denied cases in
+`.terreno/regression-backfill.json` (not committed) so it never proposes them again.

package/src/docs/versioned/next/regression/admin.md

@@ -0,0 +1,13 @@
+# Admin regression suite
+
+Area: ADMIN
+Owner: Josh Gachnang
+Last full run: never
+
+Walk these cases with an admin account on web and a second, non-admin account signed in on a
+phone. Both run against the same deployed example-backend.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| ADMIN-001 | An admin edit reaches the owner's phone live | A non-admin user is signed in on a phone with the Todos tab open and one todo titled "Buy milk". On web, an admin opens the Admin Panel, opens that todo, changes its title to "Buy oat milk", and saves | Within 10 seconds, without pulling to refresh or reopening the app, the phone's Todos list shows "Buy oat milk" | iOS, Android | manual | e2e-and-regression-testing |
+| ADMIN-002 | A published announcement shows on a phone | A non-admin user is signed in on a phone. On web, an admin creates and publishes an announcement from the Admin Panel, then the user force quits and reopens the app | The announcement shows once on the phone with the admin's title and body, and does not show again after it is dismissed and the app is reopened | iOS, Android | manual | e2e-and-regression-testing |

package/src/docs/versioned/next/regression/auth.md

@@ -0,0 +1,15 @@
+# Auth regression suite
+
+Area: AUTH
+Owner: Josh Gachnang
+Last full run: never
+
+Walk these cases against example-frontend and example-backend on a deployed environment whose
+backend sends real email. Use an inbox you can open, not a seeded `@example.com` address.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| AUTH-001 | Password reset email reaches a real inbox | Signed out, with an account whose email is a real inbox you can open: on the login screen tap the forgot-password link, enter that email, tap "Send reset link", open the email, follow its link, enter a new password, tap "Save new password", then sign in with the new password | One reset email arrives within 2 minutes from the configured sender. Its link opens the "Reset password" screen in the app. Sign-in with the new password lands on Todos, and sign-in with the old password shows an error | Web, iOS, Android | manual | e2e-and-regression-testing |
+| AUTH-002 | Verification email confirms the account | Signed in as a new account with a real inbox that has not verified its email: open Profile, tap "Resend" on the verify-email banner, open the email, follow its link, tap "Confirm email", then reopen Profile | One verification email arrives within 2 minutes. After confirming, Profile no longer shows the "Verify your email" banner | Web, iOS, Android | manual | e2e-and-regression-testing |
+| AUTH-003 | Session survives a force quit on a device | Signed in on a release build on a phone, with at least one todo: force quit the app from the app switcher, wait 10 seconds, then open it again | The app opens on Todos with the same todos and no login screen, because the session is read back from the device's secure storage | iOS, Android | manual | e2e-and-regression-testing |
+| AUTH-004 | Logout clears the stored session on a device | Signed in on a release build on a phone: open Profile, tap "Logout", force quit the app, then open it again | The app opens on the login screen, and no data from the previous account shows before sign-in | iOS, Android | manual | e2e-and-regression-testing |

package/src/docs/versioned/next/regression/planning.md

@@ -0,0 +1,16 @@
+# Planning regression suite
+
+Area: PLAN
+Owner: Josh Gachnang
+Last full run: never
+
+Every case here is retired: they checked agent behavior, not the app, which the minimal
+regression rule leaves out. The rows stay so their IDs are never reused.
+
+| ID | Case | Steps | Expected | Platforms | Automated by | Added |
+| --- | --- | --- | --- | --- | --- | --- |
+| PLAN-001 | Grow plans e2e and regression | In a fresh session in a repo that has `docs/testing/e2e.md`, run Grow on "add a due date to todos" and approve it | Retired: an agent-behavior check, not an app check | Claude Code, Cursor, Codex | manual | e2e-and-regression-testing |
+| PLAN-002 | Grow without a guide | Repeat PLAN-001 in a repo with no `docs/testing/e2e.md` and no Testing conventions table | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |
+| PLAN-003 | Brew writes the suite | Take an approved IP with one regression case through Brew | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |
+| PLAN-004 | Pick writes, Roast enforces a planned spec | Run Pick on a PLAN-001 task that owns an `## E2E tests` row. Then delete the spec file and run Roast | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |
+| PLAN-005 | Taste renumbers a collision | On a branch that added `AUTH-00N`, merge a master commit that also added `AUTH-00N`, then run Taste | Retired: an agent-behavior check, not an app check | Claude Code | manual | e2e-and-regression-testing |