@terreno/mcp 57.19.2 → 57.21.0

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

@@ -33,7 +33,7 @@ terreno generate rest-cli --schema http://localhost:4000/openapi.json --out ./to
 | `api request <METHOD> <path>` | Invoke by method + path template |
 | `info` | Local `@terreno/*` versions (via MCP local tools) |
 | `logs` | Merge backend/browser JSONL, Metro events, and app CDP console (`--entries`, `--level`, `--since`, `--sources`; `last-error`) |
-| `state` | Inspect Better Auth (via `auth` alias or `betterAuth`) or RTK Query state (`--slice`, `--query`) through the dev store or Metro CDP |
+| `state` | Inspect client state with `get_client_state`: RTK Query (Better Auth via the `auth` alias or `betterAuth`; `--slice`, `--query`) and SyncDB, through the dev stores or Metro CDP. The result names the detected `layer` |
 | `eval` | Evaluate JavaScript in the app runtime through Metro CDP (`--code`; requires `TERRENO_MCP_EVAL=1`) |
 | `navigate` | Navigate Expo Router through Metro CDP (requires `TERRENO_MCP_EVAL=1`) |
 | `web [url]` | Automate the web app with Bun 1.4 `Bun.WebView`; ordered `--action` JSON, `--snapshot`, and `--screenshot` |

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

@@ -442,3 +442,11 @@ verify links as `${publicAppUrl}/resetPassword?token=...` and
 `${publicAppUrl}/verifyEmail?token=...`. Pass `templates` to override subject/text/html
 per template id (`resetPassword` | `verifyEmail`). Variables: `resetUrl`, `verifyUrl`,
 `publicAppUrl`, `token`.
+
+The same helpers render the security notifications `AccountSecurityApp` sends: the `security*`
+template ids (`securityPasswordChanged`, `securityPasskeyAdded`, `securityTwoFactorDisabled`, and
+the rest in `SECURITY_MAIL_TEMPLATE_IDS` from `@terreno/api`). Those pass their values in `data`
+and no `token`. HTML bodies get HTML-escaped values; subject and text get the raw values. Pass it
+as `AccountSecurityApp` `notifications.render` to render them with comms. The templates,
+placeholders, and sending rules are in
+[Account security: Notifications](account-security.md#notifications).

package/src/docs/versioned/next/reference/create-terreno-app.md

@@ -37,7 +37,9 @@ Writes `<cwd>/<appName>/`. Refuses a non-empty target except `.git` / `.gitignor
 
 Printed next steps install, seed, then start the backend. SDK and web run in a second terminal while the backend is up.
 
-The generated Profile tab uses `@terreno/ui` `TapToEdit` with `PATCH /auth/me`. Fonts come from `@terreno/ui`. `app.json` leaves icon/splash/favicon unset. `metro.config.js` pins `jspdf` so Metro can bundle admin PDF export. Generated tsconfigs use no TypeScript 6 deprecated options and no `ignoreDeprecations` (see [TypeScript configuration](../explanation/typescript-configuration.md)). Auth routes use `<Stack.Protected>`.
+The generated Profile tab uses `@terreno/ui` `TapToEdit` with `PATCH /auth/me` for name and email. Changing the email there does not change the Better Auth sign-in email. Passwords are changed on the Security screen. Fonts come from `@terreno/ui`. `app.json` leaves icon/splash/favicon unset. `metro.config.js` pins `jspdf` so Metro can bundle admin PDF export. Generated tsconfigs use no TypeScript 6 deprecated options and no `ignoreDeprecations` (see [TypeScript configuration](../explanation/typescript-configuration.md)). Auth routes use `<Stack.Protected>`.
+
+Generated apps turn on the auth suite: account linking, two-factor, passkeys, last sign-in method, multi-session, and native apps in `backend/src/utils/betterAuthConfig.ts`, plus `AuditApp` and `AccountSecurityApp` in `server.ts`. `app/login.tsx` renders `TerrenoLoginScreen` (remembering only the sign-in method), and `app/settings/security.tsx` renders `TerrenoAccountSecurityScreen`, opened from the Profile tab. Generated apps set no `sendMail`, so forgot-password, recovery emails, and security notifications do nothing until the app wires `@terreno/comms`. Env vars and details: [Auth features in generated apps](../how-to/configure-better-auth.md#auth-features-in-generated-apps).
 
 ## Library
 

package/src/docs/versioned/next/reference/environment-variables.md

@@ -56,6 +56,9 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `GITHUB_CLIENT_ID` | `@terreno/api` | ❌ | — | No | server |
 | `GITHUB_CLIENT_SECRET` | `@terreno/api` | ❌ | — | Yes | server |
 | `GITHUB_CALLBACK_URL` | `@terreno/api` | ❌ | — | No | server |
+| `AUTH_ACCOUNT_LINKING` | example-backend `accountLinking.mode`: `verified-email`, `explicit`, or `never` ([details](../how-to/configure-better-auth.md#auth-features-in-example-backend)) | ❌ | `verified-email` | No | server |
+| `AUTH_SIGN_UP` | example-backend `signUp.mode`: `open` or `closed` ([details](../how-to/configure-better-auth.md#auth-features-in-example-backend)) | ❌ | `open` | No | server |
+| `PASSKEY_RP_ID` | example-backend `passkey.rpID`: the `FRONTEND_URL` host or a parent domain of it ([details](../how-to/configure-better-auth.md#auth-features-in-example-backend)) | ❌ | the `FRONTEND_URL` host | No | server |
 
 ## Server configuration
 
@@ -67,12 +70,12 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `ENABLE_SWAGGER` | `@terreno/api` | ❌ | `false` | No | server |
 | `APP_ENV` | example-backend | ❌ | `development` | No | server |
 | `BACKEND_URL` | scripts, deploy | ❌ | — | No | server |
-| `FRONTEND_URL` | example-backend CORS and `authOptions.publicAppUrl` | ❌ | `http://localhost:8082` | No | server |
+| `FRONTEND_URL` | example-backend `publicAppUrl` (auth mail links), the first passkey origin, and the default `PASSKEY_RP_ID` (its host). In production a loopback value turns passkeys off ([Auth features in example-backend](../how-to/configure-better-auth.md#auth-features-in-example-backend)) | ❌ (✅ for passkeys on a deploy) | `http://localhost:8082` | No | server |
 | `CORS_ORIGINS` | example-backend (`utils/betterAuthConfig.ts`) | ✅ for deployed web origins | localhost:8082 origins only | No | server |
 | `CROSS_DOMAIN_AUTH_COOKIES` | example-backend Better Auth config | ❌ | `false` | No | server |
 | `API_URL` | microservice split | ❌ | — | No | server |
 | `DISABLE_LOG_ALL_REQUESTS` | `@terreno/api` logging | ❌ | — | No | server |
-| `TERRENO_BROWSER_LOGS` | `@terreno/api` dev log ingestion | ❌ | enabled only in development; loopback or authenticated requests only | No | server |
+| `TERRENO_BROWSER_LOGS` | `@terreno/api` `TerrenoApp` (`POST /__terreno/browser-logs`) | ❌ | on only when `NODE_ENV=development`. `false`/`0` turns it off. `true`/`1` turns it on in any non-production environment. Ignored when `NODE_ENV=production`: the route is never registered and returns 404. See [Development browser-log ingestion](api.md#development-browser-log-ingestion). | No | server |
 | `ALLOW_MIGRATIONS` | `@terreno/api` `terreno-migrate` | ❌ | unset | No | server |
 | `MIGRATIONS_DIR` | example-backend Dockerfile / `resolveMigrationDir` | ❌ | `<cwd>/migrations` when `dir` is `$bunfs` | No | server |
 
@@ -217,7 +220,7 @@ for authenticated test sends.
 | `USE_SENTRY_LOGGING` | `@terreno/api` | ❌ | `false` | No | server |
 | `SLOW_REQUEST_THRESHOLD_MS` | `@terreno/api` | ❌ | `5000` | No | server |
 | `SLOW_DB_QUERY_THRESHOLD_MS` | `@terreno/api` | ❌ | `100` | No | server |
-| `TERRENO_LOG_FILE` | logger | ❌ | — | No | server |
+| `TERRENO_LOG_FILE` | `@terreno/api` logger | ❌ | on unless `NODE_ENV=production`. An on/off switch, not a path: `false`/`0` turns it off, and `true`/`1` turns it on even in production. Writes JSONL to `<cwd>/.terreno/logs/app.log`. | No | server |
 | `TRACE_SAMPLING_RATE` | example-backend OTEL | ❌ | `0.1` | No | server |
 | `MEMORY_SAMPLE_INTERVAL_MS` | example-backend | ❌ | `60000` | No | server |
 | `JOB_TRACE_LOGS` | workers | ❌ | — | No | server |
@@ -269,6 +272,9 @@ secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
 | `TERRENO_MCP_DOCS_DIR` | `@terreno/mcp` | ❌ | — | No | tooling |
 | `TERRENO_MCP_EVAL` | MCP eval | ❌ | — | No | tooling |
 | `TERRENO_PROJECT_ROOT` | MCP local | ❌ | — | No | tooling |
+| `TERRENO_MCP_RATE_LIMIT_MAX` | `@terreno/mcp` hosted server | ❌ | `120` (`0` disables) | No | server |
+| `TERRENO_MCP_RATE_LIMIT_WINDOW_MS` | `@terreno/mcp` hosted server | ❌ | `60000` | No | server |
+| `TERRENO_MCP_TRUST_PROXY_HOPS` | `@terreno/mcp` hosted server | ❌ | `1` when `K_SERVICE` is set (Cloud Run), else `0` | No | server |
 
 ## Background jobs
 

package/src/docs/versioned/next/reference/legacy/rtk.md

@@ -114,12 +114,27 @@ void betterAuth.syncSession(store.dispatch);
 ``````
 
 **Key exports:**
-- `createBetterAuthClient({baseURL, scheme, storagePrefix?, webAuth?, bearerStorage?})` — Factory for Better Auth client with Expo support. `webAuth: "bearer"` authenticates the web client with a stored bearer token and no cookies, for a frontend and API on different sites ([how-to](../../how-to/configure-better-auth.md#frontend-and-api-on-different-sites))
+- `createBetterAuthClient({baseURL, scheme, storagePrefix?, webAuth?, bearerStorage?, features?})` — Factory for Better Auth client with Expo support. `webAuth: "bearer"` authenticates the web client with a stored bearer token and no cookies, for a frontend and API on different sites ([how-to](../../how-to/configure-better-auth.md#frontend-and-api-on-different-sites)). `features` (`BetterAuthClientFeatures`: `twoFactor?: boolean | {onTwoFactorRedirect}`, `passkey?`, `multiSession?`, `lastLoginMethod?`, `oneTimeToken?`) adds `twoFactorClient`, `passkeyClient` (`@better-auth/passkey/client`), `multiSessionClient`, `lastLoginMethodClient` and `oneTimeTokenClient` after the Expo plugin, and types their namespaces (`client.twoFactor.enable`, `client.passkey.addPasskey`, `client.multiSession.listDeviceSessions`, `client.getLastUsedLoginMethod`, `client.oneTimeToken.verify`). Without `features`, or when its type does not name the features (a config typed `BetterAuthClientConfig`), the return type is `BetterAuthClient`, unchanged. In bearer mode `multiSession` lists no sessions and 2FA and passkey challenges need cookies ([how-to](../../how-to/configure-better-auth.md#client-features))
+- `BetterAuthClient` — The client type without `features` (also `ReturnType<typeof createBetterAuthClient>`). `BetterAuthClientWithFeatures<Features>` — the client type with them. `BetterAuthClientFor<Features>` — which of the two `createBetterAuthClient` returns. `BetterAuthHandoffClient` — what the OAuth handoff helpers accept: any client from `createBetterAuthClient`
+- `BetterAuthOAuthProvider` — `"google" | "github" | "apple"` or any generic OAuth provider id, such as `"mock-oidc"`
 - `getBetterAuthBearerToken({storagePrefix?, bearerStorage?})` — Reads the token bearer mode stored, or `null`
 - `signInSocialWithHandoff({client, provider, callbackURL?, errorCallbackURL?})` — Starts a social or generic OAuth sign-in for a web bearer client: stores a random nonce in `sessionStorage` and navigates the page to the server's `{basePath}/oauth-handoff/start` with `handoff=<nonce>` on the callback URLs. Throws on native and in cookie mode ([how-to](../../how-to/configure-better-auth.md#social-sign-in-in-bearer-mode))
 - `completeBetterAuthOAuthHandoff({client}): Promise<boolean>` — On the return page, removes `#ott` and `handoff` from the URL first, then exchanges the token at `{basePath}/one-time-token/verify` only when `handoff` matches the stored nonce. Resolves `true` only when a bearer token was stored; never rejects. Await it at startup before session reads and Sentry
-- `generateBetterAuthSlice({authClient, apisToReset?, syncInterval?})` — Returns `{reducer, middleware, actions, slice, syncSession, authClient}`. Pass the app's RTK Query APIs (for example `apisToReset: [terrenoApi]`) so their caches are purged (`util.resetApiState()`) when a signed-in session logs out (`betterAuth/logout` or `auth/logout`), when `syncSession` finds the session gone, and when the session changes to another user. Without it, the next account on the same client can be served the previous account's cached responses
-- `selectBetterAuthIsAuthenticated`, `selectBetterAuthUserId`, `selectBetterAuthUser` — Selectors over `state.betterAuth`
+- `linkSocialWithHandoff({client, provider, callbackURL, errorCallbackURL?}): Promise<{error}>` — Links a provider to the signed-in user. On web in bearer mode it posts the intent to `{basePath}/oauth-handoff/link-intent` with the bearer, then submits the returned single-use token in a hidden POST form to `startURL`, which redirects to the provider; the page comes back to `callbackURL` with no `#ott`. Both URLs may be any page on a web origin (`callbackPaths` do not apply); `errorCallbackURL` defaults to `callbackURL`. In cookie mode and on native it calls `client.linkSocial`. Resolves `{error: null}` once the browser is on its way, or `{error: {status, code?, message?}}` (such as 403 `LINKING_DISABLED`) without submitting anything. `BetterAuthLinkClient` is its client type ([how-to](../../how-to/configure-better-auth.md#linking-a-provider-in-bearer-mode))
+- `useAuthMethods(authClient, {skip?}): {methods, isLoading, error, refetch}` — Loads the server's enabled sign-in methods (`BetterAuthMethods`: `providers`, `emailPassword`, `signUp`, `accountLinking`, and feature flags) once per client from `{basePath}/terreno/methods` through the client's `$fetch`, so bearer and cookie modes both work. `methods` is `undefined` while loading and after an error; render no provider buttons until it arrives. `refetch()` requests them again (for Try again); `skip: true` makes no request ([response](../api.md#better-auth-authentication))
+- `createRememberedAccountsStore({rememberIdentity, storageKey?, max?, storage?})` — On-device store of accounts that signed in here, for the login screen. Returns `{record(entry), forget(userId), clear(), list(), lastUsedMethod(), isHydrated(), ready, getSnapshot(), subscribe(listener), dispose()}`. Each change re-reads storage first, and on web the store follows `storage` events for its key until `dispose()`, so a stale tab cannot bring back a forgotten account. A failed change rejects to its caller without blocking later changes. Persists `{userId, method, lastUsedAt}` (newest first, at most `max`, default 5, and at most 2048 bytes) under `storageKey` (default `terreno_remembered_accounts`) in SecureStore on native (`WHEN_UNLOCKED_THIS_DEVICE_ONLY` on iOS) or localStorage on web. `rememberIdentity` is required: pass `false` to keep only the method. `name` (in clear), a masked `email`, and an `https://` `image` are kept only with `rememberIdentity: true`. Unreadable or oversized stored data resets to an empty list ([how-to](../../how-to/configure-better-auth.md#4-remember-accounts-on-this-device))
+- `useRememberedAccounts(store): {accounts, lastUsedMethod, isHydrated, forget, clear}` — Subscribes a component to the store. `isHydrated` is `false` until native storage has loaded
+- `toLoginAccountOptions(accounts)` — Maps `RememberedAccount[]` to `@terreno/ui` `LoginAccountOption[]` (`id` is the `userId`) for `LoginScreen`'s `rememberedAccounts`
+- `maskEmail(email)` — `josh@mail.flourish.health` → `j***@m***.health`: first character of the local part and domain, subdomains hidden, top-level domain kept; `undefined` for non-emails
+- `getBetterAuthClientWebAuth(client): {webAuth, bearerToken}` — Whether a client from `createBetterAuthClient` is in web bearer mode, and the token it holds; `{webAuth: "cookie", bearerToken: null}` on native, in cookie mode, and for other clients. No request
+- `useLoginController({client, rememberedAccounts, onSignedIn, onTwoFactorRequired?, rememberIdentity?, callbackURL?, errorCallbackURL?, error?, onSignUpPress?, onForgotPasswordPress?, providerLabels?, passkeyAutofill?, skipWhenSignedIn?, webAuth?, getBearerToken?, initialEmail?})` — Drives a login screen from a Better Auth client. Returns `{step, methods, isEmailPasswordEnabled, screenProps, twoFactor, signInEmail, signInSocial, signInPasskey, continueAs, forget}`: `step` is `"checking"`, `"login"`, `"twoFactor"` or `"signedIn"`; `isEmailPasswordEnabled` is `false` when the server has email and password off (render `LoginScreen` with `fields={[]}`); `screenProps` spreads into `@terreno/ui` `LoginScreen`; `twoFactor` feeds `TwoFactorChallengeScreen`. A live session calls `onSignedIn` without showing the screen (in bearer mode it first finishes a pending OAuth handoff; with no stored token it asks the server nothing). If `onSignedIn` throws, `step` returns to `"login"` with an error. The passkey button and autofill are web-only. Device sessions (`multiSession.listDeviceSessions`, never in bearer mode) become session cards and hide remembered entries for the same user. Social sign-in uses `signInSocialWithHandoff` in bearer mode and `signIn.social` otherwise. Every finished sign-in is recorded in the store. Server refusals become notices through `getLoginFeedback` ([how-to](../../how-to/configure-better-auth.md#5-drop-in-login-screen))
+- `TerrenoLoginScreen` — `LoginScreen` connected through `useLoginController`; takes its options plus `fields?` (default `DEFAULT_LOGIN_FIELDS`), `title?`, `logo?`, `trustDeviceDays?`, `initialTrustDevice?` (pass `false` to start "Trust this device" unchecked), `onStepChange?` (called with each new step: `checking`, `login`, `twoFactor`, `signedIn`), `testID?` (default `login-screen`; spinner `${testID}-checking`). Renders the inline two-factor challenge unless `onTwoFactorRequired` is set
+- `useAccountSecurity({client, callbackURL, methods?, errorCallbackURL?, linkError?, providerLabels?, passkeySupported?, minPasswordLength?})` — Drives an account security screen from a Better Auth client. Returns `{screenProps, methods, user, refetch}`; `screenProps` (`linkedAccounts`, `password`, `passkeys`, `twoFactor`, `sessions`, `isLoading`, `error`, `onRetry`) spreads into `@terreno/ui` `AccountSecurityScreen`. A card's props are `undefined` when the server's methods (or the client's features) leave it off; passkeys are web-only. Loads `listAccounts`, `passkey.listUserPasskeys`, `getSession({query: {disableCookieCache: true}})` and `listSessions`; each Better Auth `{error}` becomes a thrown `Error` for the card, and after each change only the affected section reloads. Never calls `unlinkAccount` for the only account, or `deletePasskey` for the only sign-in method (`LAST_SIGN_IN_METHOD_MESSAGE`). Links through `linkSocialWithHandoff`; "Set a password" posts `{basePath}/terreno/set-password`. `SESSION_NOT_FRESH` becomes `SIGN_IN_AGAIN_MESSAGE`; a change refused with `CREDENTIAL_ACCOUNT_NOT_FOUND` switches the password card to set mode (`NO_PASSWORD_YET_MESSAGE`). `getLinkErrorMessage(code)` maps a link's `?error=` to safe text ([how-to](../../how-to/configure-better-auth.md#6-drop-in-security-screen))
+- `TerrenoAccountSecurityScreen` — `AccountSecurityScreen` connected through `useAccountSecurity`; takes its options plus `title?`, `description?`, `header?`, `children?`, `withPage?`, `maxWidth?`, `testID?`
+- `recordRememberedSignIn({store, user, method, rememberIdentity?})` — Records a sign-in the controller did not finish, such as one completed on the app's own two-factor screen
+- `getLoginFeedback({failure, mode?, originalMethod?}): {notice?, error?, isSignUpClosed}` — Maps `{code?, message?, source: "response" | "url"}` to login screen feedback: `account_not_linked` / `OAUTH_LINK_ERROR` / "account not linked" to guidance for the linking mode, `VERIFY_EMAIL_TO_USE_ACCOUNT` to "verify your email", `signup_disabled` / `EMAIL_PASSWORD_SIGN_UP_DISABLED` to "ask your administrator" (and `isSignUpClosed`), `LINKING_DISABLED`, `provider_not_found`; a response's own message otherwise, and never text from a URL
+- `generateBetterAuthSlice({authClient, apisToReset?, syncInterval?, signOutTimeoutMs?})` — Returns `{reducer, middleware, actions, slice, syncSession, authClient}`. Pass the app's RTK Query APIs (for example `apisToReset: [terrenoApi]`) so their caches are purged (`util.resetApiState()`) when a signed-in session logs out (`betterAuth/logout` purges once the session clears, so a sign-out that fails keeps both; `auth/logout` purges at once and again when the session clears), when `syncSession` finds the session gone, and when the session changes to another user. Without it, the next account on the same client can be served the previous account's cached responses. `actions.logout()` keeps the session in the state with `isSigningOut: true` (`isLoading` unchanged) while the middleware calls `authClient.signOut()` (`signOutTimeoutMs`, default 10000), then dispatches `clearSession`. A sign-out that fails or times out asks `getSession`: a session that is still live, or a cookie or native client the server cannot be asked about, stays signed in with `error` set to `SIGN_OUT_FAILED_MESSAGE` ("Couldn't sign out. Check your connection and try again."); a web bearer client, which drops its token before the request leaves, ends signed out. The global `auth/logout` action (a refused session) always ends signed out. Either sign-out leaves alone a session for another user that signed in while it was in flight; a sign-out that started signed out asks `getSession` first, and clears a session that landed meanwhile unless the server still has it
+- `selectBetterAuthIsAuthenticated`, `selectBetterAuthUserId`, `selectBetterAuthUser`, `selectBetterAuthIsLoading`, `selectBetterAuthIsSigningOut`, `selectBetterAuthError` — Selectors over `state.betterAuth`
 - `BetterAuthUser`, `BetterAuthState` — TypeScript types for session/user data
 
 **Session State (`state.betterAuth`):**
@@ -129,6 +144,7 @@ void betterAuth.syncSession(store.dispatch);
   userId: string | null;
   user: BetterAuthUser | null;
   isLoading: boolean;
+  isSigningOut: boolean;
   error: string | null;
   lastSyncTimestamp: number | null;
 }

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
@@ -106,6 +106,12 @@ changes but otherwise keeps the body stable instead of summarizing the latest tu
 These are the only visible PR sections; optional detail is expandable; comments are
 reserved for blocked decisions or non-obvious review resolutions.
 
+The body is also the approval bot's input (`brewery approve`, scored with
+`docs/approval-rubric.md`), so its shape is strict. The headings are spelled exactly as
+above. `Why` ends with the plan's repository path and the task ids the PR delivers.
+Every `Verification` row starts with `✅`, `🧭`, or `⚠️` and names the outcome, not only
+the command. The stage-result `ip` is the plan's filename, and later stages keep it.
+
 Every stage follows the
 [documentation contract](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/documentation-contract.md):
 read architecture docs before acting, update them in the same slice, and fail the slice
@@ -143,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).
@@ -159,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.