@terreno/mcp 58.0.0 → 58.0.1

package/src/docs/versioned/58.0.0/tasks/remove-rtk.md

@@ -0,0 +1,155 @@
+# Task List: Remove @terreno/rtk and Redux in Terreno 58
+
+See: [`docs/implementationPlans/remove-rtk.md`](../implementationPlans/remove-rtk.md)
+
+**Target:** Terreno **58.0.0**, branch `remove-rtk-58`, one PR into `release-58.0.0`.
+
+Wide refactor: **expand → migrate → contract**. Every task leaves the branch compiling and
+green. Phase 4.1 (delete `rtk/`) is blocked by every migration task.
+
+**Supporting skills:** `terreno-data-fetching`, `terreno-backend-api`,
+`mongoose-schema-safety`, `building-terreno-apps`, `building-admin-interfaces`, `terreno-ui`,
+`backend-test-env`, `verify-ui-changes`, `update-docs`, `generate-sdk` (rewrite in 4.2).
+
+## Phase 1: Expand syncdb
+
+- [x] **Task 1.1** (tracer): Request client + query/mutation hooks + `/config`
+  - Delivers: `createApiClient({baseUrl, authProvider, credentials?, headers?})` and `useApiQuery` / `useLazyApiQuery` / `useApiMutation` / `ApiClientProvider`, with a shared per-client cache keyed by URL+args, tag invalidation, `{data}` / list-envelope unwrap matching RTK, 401 → `authProvider.refresh` → retry, `App-Version` / `App-Platform` headers. `@terreno/syncdb/config` exports `baseUrl`, `baseWebsocketsUrl`, `resolveBaseUrls`, `resolveDevApiPort` (moved from `rtk/src/constants.ts` with their tests). example-frontend profile screen reads `GET /auth/me` through `useApiQuery`; `store/syncdb.ts` imports `baseUrl` from `@terreno/syncdb/config`.
+  - Files: `syncdb/src/api/{client,cache,hooks}.ts` + tests, `syncdb/src/config/baseUrl.ts` + tests, `syncdb/package.json` exports, `admin-frontend/src/{adminRequest,useAdminRpc}.ts` (wrap the syncdb client), `example-frontend/app/(tabs)/profile.tsx`, `example-frontend/store/syncdb.ts`
+  - Blocked by: none
+  - Acceptance: bun tests for dedupe, tag invalidation, envelope unwrap, refresh-retry, abort/timeout; admin-frontend tests still pass unchanged; profile e2e passes
+  - Docs: `docs/reference/syncdb.md` (API client, config sections)
+
+- [x] **Task 1.2**: Codegen for every non-synced OpenAPI operation
+  - Delivers: `terreno-syncdb generate` also emits typed request/response types and `useXQuery` / `useXMutation` hooks for every operation without `x-terreno-sync`, including plain routes (`/auth/me`, `/consents/pending`, `/files/upload` multipart, `/version-check`). Tags inferred per path. example-frontend `bun run sdk` runs it and writes `store/apiSdk.ts`; profile screen switches to the generated `useGetAuthMeQuery`.
+  - Also: add OpenAPI docs for the 13 frontend-called routes the spec omits — `GET/PATCH /auth/me`, `POST /auth/{sendVerification,forgotPassword,verifyEmail}`, `POST /resetPassword` (`api`); `GET /feature-flags/flagConfiguration` (`feature-flags`); `GET /version-check` (`api`); `GET /consents/pending`, `POST /consents/respond` (`api`); `GET /announcements/{pending,feed}`, `POST /announcements/{id}/{acknowledge,click,impression}` (`announcements`); `POST /files/upload` multipart (`ai`).
+  - Files: `syncdb/src/codegen/{emitApi,discoverOperations}.ts` + fixtures/tests, `syncdb/src/codegen/{cli,generate}.ts`, `example-frontend/scripts/generate-sdk.ts`, `example-frontend/store/apiSdk.ts` (generated), OpenAPI registrations in the owning packages + their route tests
+  - Blocked by: 1.1
+  - Acceptance: codegen tests against fixture spec cover query, mutation, path params, multipart, synced ops excluded; generated file compiles in example-frontend; live `/openapi.json` lists all 13 previously missing routes
+  - Docs: `docs/reference/syncdb.md` (codegen), `docs/how-to/` page for regenerating the SDK
+
+- [x] **Task 1.3**: `@terreno/syncdb/auth` — Better Auth client + session without Redux
+  - Delivers: `createBetterAuthClient`, `createStorageAdapter`, cookie-jar repair (moved with tests), `SessionProvider` + `useSession()` → `{userId, user, isLoading, isAuthenticated, error, logout}`; `logout` signs out, stops syncdb, wipes local data. example-frontend `lib/betterAuth.ts` imports from syncdb.
+  - Files: `syncdb/src/auth/{betterAuthClient,session,SessionProvider}.ts(x)` + tests, `syncdb/package.json` (move `better-auth`, `@better-auth/expo`, `expo-secure-store`, async-storage deps/peers), `example-frontend/lib/betterAuth.ts`
+  - Blocked by: 1.1
+  - Acceptance: ported `betterAuthClient` / `betterAuthSlice` behaviours as hook tests (session sync on start, after login, logout side effects)
+  - Docs: `docs/reference/syncdb.md` (auth), `docs/explanation/authentication.md`, `docs/how-to/configure-better-auth.md`
+
+- [x] **Task 1.4**: Port legacy JWT frontend auth
+  - Delivers: `jwtAuthAdapter` (token storage on SecureStore/AsyncStorage, refresh when < 2 min to expiry, mutex, 401 → refresh → retry, logout on refresh failure) and `useJwtAuth()` (`login`, `signup`, `googleLogin`, `resetPassword`, `logout`) feeding `SessionProvider`; token-expiry helpers (`getTokenExpirationTimes`, `shouldShowStillThereModal`).
+  - Files: `syncdb/src/auth/{jwtAuthAdapter,useJwtAuth,tokenExpiry}.ts` + tests (ported from `rtk/src/authSlice*.test.ts`, `rtk/src/isolated/emptyApi*.isolated.ts`)
+  - Blocked by: 1.3
+  - Acceptance: AC9 — ported tests pass against an `api` test server using JWT auth
+  - Docs: `docs/explanation/authentication.md`, `docs/reference/syncdb.md`
+
+- [x] **Task 1.5**: Socket event API + `@terreno/syncdb/flags`
+  - Delivers: `client.onSocketEvent` / `useSocketEvent`; `useFeatureFlags(client)` / `useTerrenoFeatureFlags` (OpenFeature provider) fetching via the request client and refetching on the flags push event. example-frontend `_layout.tsx` drops `useSocketConnection` / `useRealtimeDebug`. Server deprecation message updated.
+  - Files: `syncdb/src/sync/socketTransport.ts`, `syncdb/src/react/useSocketEvent.ts`, `syncdb/src/flags/*` + tests (ported from `rtk/src/useFeatureFlags.test.ts`, `useTerrenoFeatureFlags.test.ts`), `feature-flags/src/featureFlagsApp.ts`, `example-frontend/app/_layout.tsx`, `(tabs)/{ai,documents,profile}.tsx`
+  - Blocked by: 1.1
+  - Acceptance: AC7 — Playwright spec asserts one socket.io connection and a pushed flag change updates the UI
+  - Docs: `docs/reference/feature-flags.md`, `docs/how-to/add-feature-flags.md`, `docs/how-to/websocket-integration.md`
+
+- [x] **Task 1.6**: `@terreno/syncdb/app` and `/buildNumber`
+  - Delivers: `useUpgradeCheck` (on the request client), `hasPermission` / `canOpenAdminPage`, `installDevConsoleLogger`, `useMCPTools` (token from the shared AuthProvider, fixing the Better Auth gap), `buildNumber` node subpath — all moved with tests. example-frontend uses them.
+  - Files: `syncdb/src/app/*`, `syncdb/src/buildNumber.ts` + tests, `example-frontend/app/_layout.tsx`, `app/admin/_layout.tsx`, `(tabs)/{ai,profile}.tsx`
+  - Blocked by: 1.1
+  - Acceptance: ported `useUpgradeCheck*`, `usePermissions`, `devConsoleLogger`, `useMCPTools`, `buildNumber` tests pass
+  - Docs: `docs/how-to/upgrade-banner.md`, `docs/how-to/expose-mcp-tools.md`, `docs/reference/syncdb.md`
+
+## Phase 2: Backend sync for GptHistory and McpServiceToken
+
+- [x] **Task 2.1**: GptHistory synced with string ids + migration
+  - Delivers: String `_id` (UUID default), `syncPlugin` + `isDeletedPlugin`, `sync: {scope: owner}` on `/gpt/histories`; `AIDataset.historyId` String; `gpt-history-string-ids` migration; SSE / turn / actions routes accept string ids. Backend example registers the stream.
+  - Files: `ai/src/models/{gptHistory,aiDataset}.ts`, `ai/src/routes/{gptHistories,gpt,gptActions}.ts`, `ai/src/migrations/gptHistoryStringIds.ts` + tests, `example-backend/src/server.ts`
+  - Blocked by: none
+  - Acceptance: AC5; existing `ai` route tests pass with string ids; sync snapshot test returns only the owner's histories
+  - Docs: `docs/reference/ai.md`, `.rulesync/rules/ai/00-ai.md`, 58.0.0 upgrade notes (run migration first)
+  - Skills: `mongoose-schema-safety`
+
+- [x] **Task 2.2**: McpServiceToken synced read-only + actions + migration
+  - Delivers: `modelRouter("/mcp/service-tokens", McpServiceToken, {sync})` with client writes disabled, sync `responseHandler` stripping `tokenHash`; `collectionActions.create` (plaintext once), `instanceActions.revoke`; `mcp-service-token-string-ids` migration; `verify` unchanged.
+  - Files: `api/src/models/mcpServiceToken.ts`, `api/src/mcp/serviceTokens.ts`, `api/src/migrations/` (built-in migration), tests
+  - Blocked by: none
+  - Acceptance: AC6; migration idempotence test; existing MCP auth tests pass
+  - Docs: `docs/reference/mcp-server.md` / service-token how-to, upgrade notes
+
+## Phase 3: Migrate consumers
+
+- [x] **Task 3.1**: `@terreno/ui` consents and announcements take `client`
+  - Delivers: `TerrenoRequestClient` structural interface; `ConsentNavigator`, `AnnouncementNavigator`, `useConsentForms`, `useSubmitConsent`, `useAnnouncements`, `useAcknowledgeAnnouncement` take `client`; no `injectEndpoints`. Tests use a fake client.
+  - Files: `ui/src/requestClient.ts`, the six source files above and their tests, `ui/src/OfflineBanner.tsx` (JSDoc)
+  - Blocked by: 1.1
+  - Acceptance: ui suite green; `rg injectEndpoints ui/src` → none
+  - Docs: `docs/reference/ui.md` (consent / announcement props)
+
+- [x] **Task 3.2**: example-frontend — remove Redux store, session, auth screens
+  - Delivers: delete `store/index.ts`, `store/appState.ts` Redux slice (→ context + `useStoredState`), `store/errors.ts` middleware (→ client `onError` reporting to Sentry), `store/betterAuthApi.ts`; root layout uses `SessionProvider` + `ApiClientProvider`; login, signup, forgot / reset password, verify email use generated hooks / `useSession`.
+  - Files: `example-frontend/store/*`, `app/_layout.tsx`, `app/{login,signup,forgotPassword,resetPassword,verifyEmail}.tsx`, `lib/authRecoveryActions.ts`, related tests
+  - Blocked by: 1.2, 1.3, 1.5, 1.6, 3.1
+  - Acceptance: auth e2e shard green; unit suite green
+  - Docs: `example-frontend/README.md`, `.rulesync/rules/example-frontend/00-example-frontend.md`
+
+- [x] **Task 3.3**: example-frontend — profile, admin layout, notifications, documents, push tokens
+  - Delivers: all remaining non-AI screens on generated hooks; `store/sdk.ts`, `store/openApiSdk.ts`, `store/commsOpenApiSdk.ts`, `openapi-config.ts`, `comms-openapi-config.ts` deleted.
+  - Files: `app/(tabs)/{profile,documents}.tsx`, `app/admin/**`, `components/NotificationCenter.tsx`, `components/TodoSummaryCard.tsx`, `app/gcs-settings.tsx`, `hooks/useSyncLabEngines.ts`, `app/admin/SyncLabScreen.tsx`
+  - Blocked by: 3.2
+  - Acceptance: app + admin-core + admin-table e2e shards green
+  - Docs: none beyond 3.2 (record skip)
+
+- [x] **Task 3.4**: example-frontend — AI screen and MCP settings on syncdb
+  - Delivers: `ai.tsx` histories via `useQuery("gptHistories")` / `useMutate` (rename, delete), no `updateQueryData` / `invalidateTags`; SSE uses the shared auth provider; MCP settings list via `useQuery("mcpServiceTokens")`, create/revoke via generated action hooks; `useMCPTools` from `/app`.
+  - Files: `app/(tabs)/ai.tsx`, `app/settings/mcp/index.tsx`, `store/syncdb.ts` (collections), `lib/gptAsks.ts`
+  - Blocked by: 2.1, 2.2, 3.2
+  - Acceptance: `ai-chat` e2e green incl. list / rename / delete across reload; new MCP tokens spec green
+  - Docs: `docs/how-to/` AI chat page if it names RTK hooks
+
+- [x] **Task 3.5**: example-frontend tests off RTK
+  - Delivers: `tests/bunSetup.ts` / `testPreload.ts` no longer import or mock `@/store/sdk`; `documents.test.tsx`, `NotificationCenter.test.tsx`, `orgMembersRoute.test.tsx`, `errors.test.ts`, `gptAsks.test.ts`, `TodoSummaryCard.test.tsx` use the syncdb client / fake transport; e2e allowlists and comments drop RTK entries (`consoleAllowlist.ts`, `syncdbSuite.ts`, `offlineHelpers.ts`, `adminAuth.ts`, `login` / `signup` / `admin-todo-crud` specs).
+  - Files: listed above
+  - Blocked by: 3.3, 3.4
+  - Acceptance: AC3 and AC4 for example-frontend
+  - Docs: none (record skip)
+
+- [x] **Task 3.6**: admin-spa off Redux
+  - Delivers: `StoreProvider` / `AdminGate` use `SessionProvider` (cookie mode); profile via the request client with `credentials: "same-origin"`; `store/sdk.ts` deleted; Redux deps removed.
+  - Files: `admin-spa/components/{StoreProvider,AdminGate,AdminSpaShell}.tsx`, `admin-spa/app/orgs/index.tsx`, `admin-spa/store/*`, `admin-spa/src/adminSpaUiCoverage.test.tsx`, `admin-spa/package.json`, `admin-spa/metro.config.js`
+  - Blocked by: 1.1, 1.3
+  - Acceptance: `bun run admin-spa:test` + admin-spa e2e and integration specs green
+  - Docs: `docs/reference/admin-spa*` / `docs/reference/admin-frontend.md` references
+
+- [x] **Task 3.7**: admin-frontend RTK-shaped test doubles
+  - Delivers: observability / prompts isolated tests use fake request clients instead of `injectEndpoints` APIs; RTK wording in assertions removed.
+  - Files: `admin-frontend/src/isolated/{observabilityFakeApi,aiObservabilityScreens,AiPromptsListScreen,AiPromptEditorScreen,adminRpcHooks}.isolated.tsx`, the other test files named in the IP research
+  - Blocked by: 1.1
+  - Acceptance: admin-frontend suite green; `rg -i "rtk|injectEndpoints" admin-frontend/src` → none
+  - Docs: `.rulesync/rules/admin-frontend/00-admin-frontend.md` (layout example imports `baseUrl` from `/config`)
+
+- [x] **Task 3.8**: Generators, MCP tools, cli
+  - Delivers: `create-terreno-app` scaffolds syncdb client, `SessionProvider`, generated `apiSdk.ts`, no Redux / rtk; `mcp-server` bootstrap templates, prompts, `tools.ts` (`generateInstallAdmin`), `resources.ts` (drop `terreno://docs/rtk`) updated; `get_rtk_state` and `terreno state --slice rtk` removed in favour of syncdb state tools.
+  - Files: `create-terreno-app/src/generate.ts` + tests, `mcp-server/src/{tools,prompts,bootstrap,resources}.ts`, `mcp-server/src/docs/templates/**`, `mcp-server/src/local/**`, `cli/src/commands/project.ts`, `cli/src/help.ts` + tests
+  - Blocked by: 1.2, 1.3, 1.5, 1.6
+  - Acceptance: AC10; generated app compiles in a temp dir
+  - Docs: `docs/how-to/create-a-terreno-app.md`, `docs/reference/mcp-server.md`, `docs/reference/cli.md`
+
+## Phase 4: Contract
+
+- [x] **Task 4.1**: Delete `rtk/` and its wiring
+  - Delivers: `rtk/` removed; root workspaces, `rtk:*` scripts, catalog entries (`@reduxjs/toolkit`, `@rtk-query/codegen-openapi`, `redux-persist`, `react-redux`, `axios-retry`, `async-mutex`, `jwt-decode` if unused); metro aliases; `example-backend/Dockerfile`; `knip.jsonc`; `biome.jsonc`; `codecov.yml`; CircleCI (`config.yml`, `continue-config.yml`); GitHub workflows (`rtk-ci.yml` deleted; `publish-on-tag`, `cd`, `docs-deploy`, `eas-pr`, `frontend-example-deploy`, `admin-spa-ci`, `dependabot`, issue templates, `architectural-pr-review.ts`); `scripts/**` maps and their tests; `website/scripts` + docusaurus redirect; `mcp-server/scripts/sync-package-guidelines.ts`. Apps declare native deps rtk used to pull in (`expo-secure-store`, `@better-auth/expo`, `better-auth`, `socket.io-client`, `expo-network` if still used); Expo fingerprint change recorded.
+  - Files: listed above, `bun.lock`
+  - Blocked by: 3.1–3.8
+  - Acceptance: AC1, AC2; `bun install && bun run compile`; `bun run check:knip`; `bun run analyze:full`
+  - Docs: none beyond 4.2
+
+- [x] **Task 4.2**: Docs, rules, skills, upgrade notes
+  - Delivers: `docs/how-to/migrate-rtk-to-syncdb.md` rewritten as the 58 upgrade path (every removed export → replacement table); `docs/reference/legacy/rtk.md` and `docs/explanation/announcements/rtk-deprecation.md` updated to "removed in 58"; `docs/explanation/local-first-data.md`, `docs/reference/environment-variables.md`, remaining single mentions; `mcp-server/src/docs/upgrades/58.0.0.md`; `changelog/unreleased/remove-rtk.md`; `.rulesync/rules/rtk/00-rtk.md` deleted, root / syncdb / example-frontend / mcp-server rules updated; plugin skills (`terreno-data-fetching`, `building-terreno-apps`, `generate-sdk`, `upgrading-terreno`, `building-admin-interfaces`); `README.md`, `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md`, `CONTRIBUTING.md`; regenerate rulesync outputs and `bun run skills:sync`.
+  - Files: listed above
+  - Blocked by: 4.1
+  - Acceptance: AC12
+  - Skills: `update-docs`, `update-agent-docs`
+
+- [x] **Task 4.3**: Full verification and UI evidence
+  - Delivers: `bun run prepush`; full `frontend:e2e`; admin-spa e2e; `maestro:test`; screenshots / videos for AC11 under `/opt/cursor/artifacts/`.
+  - Files: none (evidence only)
+  - Blocked by: 4.2
+  - Acceptance: AC3, AC4, AC11 with commands and artifact paths recorded in the PR Verification table
+  - Skills: `verify-ui-changes`

package/src/docs/versioned/58.0.0/testing/e2e/admin-backend.md

@@ -0,0 +1,71 @@
+# @terreno/admin-backend e2e tests
+
+Run the admin-backend smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd admin-backend smoke   # or, from the root: bun run smoke admin-backend
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `/admin/config` metadata, admin CRUD, row scope, text search, list filters, bulk actions, migrations, scripts, sync meta, document storage, and the HTTP goldens through supertest against in-memory Mongo (`src/**/*.test.ts`) | `bun run --cwd admin-backend test` |
+| Smoke | The compiled `AdminApp` mounted in a real `TerrenoApp`, serving real HTTP from a child process | `bun run --cwd admin-backend smoke` |
+| E2E | The admin panel in Chromium (home, tables, forms, search, bulk actions, custom screens) through example-frontend's `admin-*.spec.ts` Playwright suite against example-backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`admin-backend/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/admin-backend/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/api` and `@terreno/admin-backend` by package name. The
+child builds a `TerrenoApp` with a passport-local user model, one `Widget` model registered
+through `modelRouter("/widgets", Widget, {admin: {...}})`, `new AdminApp({})`, and an inline
+`/health` plugin. It seeds one admin user and one widget, then listens on a `freePort()` against
+`smokeMongoUri()`. The parent waits for `/health` with `spawnUntilReady`, then checks over real
+HTTP:
+
+1. The seeded admin logs in through `POST /auth/login`.
+2. `GET /admin/config` returns the Widget model, found by its `displayName`.
+3. `GET` on that model's `routePath` (`/admin/widgets`) lists the seeded widget.
+4. A user who signs up through `POST /auth/signup` gets 403 from `GET /admin/config`.
+5. The same user gets 405 from `GET /admin/widgets`, modelRouter's permission-denied status.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. The model uses the `modelRouter` `admin:` option rather than the legacy
+`AdminApp.models` list, so the smoke also proves that `AdminApp` discovers models registered on
+the app. The admin is seeded straight into MongoDB because signup never grants admin. Each run
+uses new emails and a new widget name, so reruns against a shared `TERRENO_TEST_MONGODB_URI`
+never collide.
+
+Signup logs a `publicAppUrl is required to send verification mail` error in the server
+output. The smoke app does not configure email, and signup still returns 200.
+
+**Measured time:** 8–24 s against an external replica set (passing runs took 7.6, 20.7 and
+23.6 s), excluding the compile. Most of it is loading the compiled packages in the child, which
+alone takes about 6 s. In a container shared with parallel builds and test suites, three other
+runs missed the 30 s readiness timeout before the child answered `/health`. The in-memory
+replica set added about two minutes on that loaded container and then timed out. Budget: 30 s.
+
+If the in-memory replica set times out waiting for a primary, point the smoke at a running
+replica set the way CI does:
+
+```bash
+TERRENO_TEST_MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs0" bun run --cwd admin-backend smoke
+```
+
+## Add an e2e test
+
+- **New config field, route, filter, or permission rule:** add a test in
+  `admin-backend/src/`. The smoke stays one happy path; do not add edge cases to it.
+- **The admin read path changed** (for example, the `/admin/config` response shape, the model
+  `routePath` scheme, or how `AdminApp` discovers `modelRouter` models): update the checks in
+  `admin-backend/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible admin flow:** add a Playwright spec next to the `admin-*.spec.ts` files in
+  `example-frontend/e2e/`, following [Write a Playwright spec](../e2e.md#write-a-playwright-spec),
+  against example-backend, which already registers `AdminApp`.
+
+See [the admin-backend reference](../../reference/admin-backend.md) for the plugin API,
+[Add a model to the admin](../../how-to/admin-add-model.md) for the `admin:` option, and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/src/docs/versioned/58.0.0/testing/e2e/admin-frontend.md

@@ -0,0 +1,79 @@
+# @terreno/admin-frontend e2e tests
+
+Run the admin-frontend smoke after a compile and the admin-spa web export, with Playwright's
+Chromium installed:
+
+```bash
+bun run compile && bun run --cwd admin-spa build:web && bun run --cwd admin-frontend smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Screens, widgets, hooks, and request helpers with `@testing-library/react-native` (`src/**/*.test.ts(x)`), plus the `*.isolated.tsx` files that each need a fresh module registry | `bun run --cwd admin-frontend test` |
+| Smoke | The compiled screens, bundled into the admin-spa web export, rendering AdminHome for a signed-in admin in Chromium against example-backend | `bun run --cwd admin-frontend smoke` |
+| E2E | Admin flows in example-frontend's Playwright suite against example-backend: the home, tables, search and filters, bulk actions, forms, Todo CRUD, custom screens, and the comms dashboard (`example-frontend/e2e/admin-*.spec.ts`) | `bun run frontend:e2e` |
+| E2E (admin-spa) | The same screens inside the standalone SPA: `test:e2e` (mocked backend) and `test:integration` (real backend). See [the admin-spa page](admin-spa.md) | `bun run --cwd admin-spa test:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`admin-frontend/e2e/smoke.spec.ts`](https://github.com/TerrenoLabs/terreno/blob/master/admin-frontend/e2e/smoke.spec.ts)
+runs at the `browser` layer. admin-frontend ships screens, not a server or a binary, so the
+smoke drives them where a consumer gets them: the admin-spa web export, which bundles the
+compiled package. The one file has two roles.
+
+Run with Bun (`bun e2e/smoke.spec.ts`), it is the driver:
+
+1. It exits 1 at once when `admin-spa/dist/index.html` is missing and asks for `build:web`.
+   It does not check that the export is newer than `admin-frontend/dist`, so rebuild the
+   export after each compile, as the command above does.
+2. `spawnExampleBackend()` starts example-backend against `smokeMongoUri()` with
+   `ADMIN_SPA_ENABLED=true` and `AUTH_PROVIDER=better-auth`, so one origin serves the export
+   at `/console`, Better Auth, and the admin API. The smoke never imports `@terreno/api`.
+3. It seeds the admin in its own process, the way example-backend's
+   `src/scripts/seed-admin-spa-admin.ts` does. It signs `admin-frontend-smoke@example.com` up
+   through Better Auth, calls `/admin/config` once so the session middleware creates the app's
+   `User`, then sets `admin: true` and the `superadmin` role on that `users` document with
+   `mongoose`. A rerun against a persistent `TERRENO_TEST_MONGODB_URI` signs in instead.
+   Running the seed script as a second process cost about 4.5 s, mostly loading the backend's
+   models a second time; seeding in the driver takes under 0.5 s.
+4. It runs the root-locked Playwright CLI on Node against this same file, passing the backend
+   URL in `ADMIN_FRONTEND_SMOKE_BASE_URL`. There is no Playwright config: admin-frontend has
+   no other Playwright suite, so the default Chromium project runs only this spec. If the package
+   gains a `playwright.config.ts`, give the smoke its own config and pass it with
+   `--config`. Traces and screenshots go to a temp dir that the driver deletes.
+
+Loaded by Playwright, the file defines one test. The admin opens `/console/login`, fills
+`admin-spa-login-email` and `admin-spa-login-password`, and presses `admin-spa-login-submit`.
+The test then waits for AdminHome's `admin-home-widget-modelsGrid`, which renders only after
+`/admin/config` answers 200 for an admin, and checks that
+`admin-home-models-grid-Todo-clickable` is visible.
+
+The driver prints one `✅` line per step and exits 1 on the first failure, after printing
+example-backend's output and Playwright's report.
+
+The smoke needs Chromium (`bunx playwright install chromium`) but no secrets: the backend
+uses fixed dev values from `spawnExampleBackend()`.
+
+**Measured time:** 23–24.5 s in three runs on an idle 4-CPU container with the in-memory
+replica set: Mongo and example-backend's first boot on an empty database 16–18 s, the seed
+0.4 s, Chromium 5–6 s, and teardown 1 s. Before the seed moved in-process and
+`spawnExampleBackend()` stopped waiting 5 s on SIGTERM, the same runs took 27–29.5 s. Under
+load the boot stretches: one run that shared four CPUs with several other suites waited 75 s
+for `/health`, so the driver waits up to 120 s. Budget: 30 s, excluding the compile and the web
+export.
+
+## Add an e2e test
+
+- **A screen, widget, or hook changed:** add a unit test next to it in `admin-frontend/src/`.
+  The smoke stays one happy path; do not add edge cases to it.
+- **AdminHome, the models grid, or the admin sign-in contract changed:** update the `testID`s
+  in `admin-frontend/e2e/smoke.spec.ts` and keep it within 30 s.
+- **A user flow through the admin screens** (tables, forms, CRUD): add a spec to
+  `example-frontend/e2e/admin-*.spec.ts` and list it in an admin shard. Follow
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec).
+- **A flow specific to the standalone SPA:** add it to admin-spa's suites.
+
+See [the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/src/docs/versioned/58.0.0/testing/e2e/admin-spa.md

@@ -0,0 +1,92 @@
+# @terreno/admin-spa e2e tests
+
+Run the admin-spa smoke after a compile and the web export:
+
+```bash
+bun run compile && bun run --cwd admin-spa build:web && bun run --cwd admin-spa smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `AdminSpaServeApp` routing, the server render and its 503 without a server build, the basePath/baseUrl check, the access gate, cache headers, `loadSsrPayload`, the route loaders, app-config merging, the dev proxy, and the SPA's store and components (`src/**/*.test.ts(x)`, `store/`, `components/`, `server/`) | `bun run --cwd admin-spa test:ci` |
+| Smoke | The compiled serve plugin server-rendering the built export from a real server in a child process | `bun run --cwd admin-spa smoke` |
+| E2E | `test:e2e`: Chromium against the built export on `e2e/serveTestApp.ts`, a backend-free server with mocked Better Auth and `/admin/config` | `bun run --cwd admin-spa test:e2e` |
+| E2E (integration) | `test:integration`: Chromium against example-backend serving the SPA at `/console` with Better Auth and the admin API. It needs a running backend with `ADMIN_SPA_ENABLED=true` and a seeded admin; see `playwright.integration.config.ts` | `bun run --cwd admin-spa test:integration` |
+| Image smoke | The built `example-backend/Dockerfile` image server-rendering `/console/login` and the root loader | `scripts/admin-spa-image-smoke.sh <base-url>` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+### Specs
+
+| Spec | Layer | Covers |
+| --- | --- | --- |
+| `e2e/ssr.spec.ts` | `browser` | The login page holds the brand and form with JavaScript off; an anonymous protected route gets a server 302; login hydrates without a warning, by direct visit or client navigation |
+| `e2e/login.spec.ts` | `browser` | The anonymous redirect to `/login` with `returnTo` (unsafe values ignored), an admin signing in to AdminHome, a wrong password showing an error |
+| `e2e/shell.ssr.spec.ts` | `browser` | The admin shell is in the first HTML with no spinner; hydration does not request the admin config again; no loader data or shell payload stays in the page |
+| `e2e/integration/adminSpa.ssr.list.integration.spec.ts` | `browser` | `/console/User` shows seeded rows with JavaScript off and hydrates without `GET /admin/users` |
+| `e2e/integration/adminSpa.ssr.detail.integration.spec.ts` | `browser` | `/console/User/<id>` (also fully percent-encoded) shows the form's values with JavaScript off and hydrates without a read |
+| `e2e/integration/adminSpa.ssr.windowed.integration.spec.ts` | `browser` | `/console/Todo` shows seeded rows; syncdb starts and keeps them; a change made right after the render shows without a refresh |
+| `e2e/integration/adminSpa.ssr.rpc.integration.spec.ts` | `browser` | `/console/configuration` and the home widgets show their data with JavaScript off |
+| `e2e/integration/adminSpa.ssr.jobs.integration.spec.ts` | `browser` | `/console/jobs` shows dashboard data, not a spinner, with JavaScript off |
+| `e2e/integration/adminSpa.ssr.comms.integration.spec.ts` | `browser` | `/console/comms` shows seeded message rows with JavaScript off |
+| `e2e/integration/adminSpa.ssr.orgs.integration.spec.ts` | `browser` | `/console/orgs` and an organization's members page show their data with JavaScript off |
+
+The other `e2e/integration/` specs cover sign-in, admin CRUD and the MCP OAuth consent page.
+
+CircleCI runs `test:e2e` in `admin-spa-ci`, `test:integration` in `admin-spa-integration`, the
+smoke in the `smoke` job, and the image smoke in `admin-spa-image-smoke`.
+
+## The smoke
+
+[`admin-spa/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/admin-spa/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/admin-spa` by package name, registers `AdminSpaServeApp` on
+a plain Express app at `/console` with a custom `brandName`, and listens on a `freePort()`. The
+plugin serves the export (`client/` + `server/`) from its default location (`admin-spa/dist`),
+the path a published package uses. The parent waits for `/console/app-config.json` with
+`spawnUntilReady`, then checks over real HTTP:
+
+1. `GET /console/login` answers 200 HTML with `Cache-Control: no-store, private`, holding the
+   brand name, the login form and `window.__ADMIN_SPA_BASE__="/console"`.
+2. The entry bundle the page names under `/console/_expo/` returns JavaScript.
+3. `GET /_expo/loaders/login` (the site root) answers 200 with `Cache-Control: no-store, private`.
+4. `GET /console/app-config.json` returns the custom `brandName` merged over the default
+   providers.
+5. An anonymous `GET /console/User/123` answers 302 to `/console/login?returnTo=%2FUser%2F123`.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. Without `admin-spa/dist/server` it exits 1 at once and asks for `build:web`.
+
+The smoke needs no browser, MongoDB, or secrets. The browser flows belong to `test:e2e` and
+`test:integration`.
+
+**Budget:** 30 s, excluding the compile and the web export.
+
+## The image smoke
+
+Job `admin-spa-image-smoke` builds `example-backend/Dockerfile`, runs the image with
+`ADMIN_SPA_ENABLED=true` against a mongo replica set, and runs
+`scripts/admin-spa-image-smoke.sh`. It passes only when `/console/login` is 200 HTML with the
+brand and `admin-spa-login-email`, and `/_expo/loaders/login` is 200 JSON with
+`Cache-Control: no-store, private`. It also runs the image with
+`ADMIN_SPA_DIST_DIR=/nonexistent` and expects the script to fail with a 503. See
+[Run tests locally](../../how-to/run-tests-locally.md) for the local commands.
+
+## Add an e2e test
+
+- **New serve-plugin option, gate rule or loader branch:** add a unit test in
+  `admin-spa/src/serve.test.ts`, `src/gate.test.ts`, or `src/server/` next to the loader's
+  tests. The smoke stays one happy path; do not add edge cases to it.
+- **The serving contract changed** (the SSR login page, the root loader path, cache headers,
+  the app-config route, the anonymous redirect): update the checks in `admin-spa/e2e/smoke.ts`
+  and keep it within 30 s.
+- **A screen or flow that needs no real backend:** add a Playwright spec to `admin-spa/e2e/`
+  and extend the mocks in `e2e/serveTestApp.ts`. Follow
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec) for `testID`s and waits.
+- **A server-rendered screen, or a flow that needs the real admin API or Better Auth:** add a
+  spec to `admin-spa/e2e/integration/`, one file per screen family
+  (`adminSpa.ssr.<area>.integration.spec.ts`).
+
+See [the `@terreno/admin-spa` reference](../../reference/admin-spa.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/src/docs/versioned/58.0.0/testing/e2e/ai.md

@@ -0,0 +1,63 @@
+# @terreno/ai e2e tests
+
+Run the ai smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd ai smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `AIService`, chat turns, asks, blocks, history, files, MCP, Langfuse, and observability routes through supertest with scripted mock models (`src/**/*.test.ts`, `src/isolated/*.isolated.ts`) | `bun run --cwd ai test` |
+| Smoke | The compiled `AiApp` streaming a chat reply from a deterministic fake provider, served by a real server in a child process | `bun run --cwd ai smoke` |
+| E2E | The chat screen seen by a user, through example-frontend's `e2e/ai-chat.spec.ts` against example-backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`ai/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/ai/e2e/smoke.ts) runs
+at the `http` layer. It re-runs itself with a `serve` argument to start a child process that
+imports the compiled `@terreno/api` and `@terreno/ai` by package name. The child builds a
+`TerrenoApp` with a passport-local user model, an inline `/health` plugin, and
+`AiApp({aiService})`, and listens on a `freePort()` against `smokeMongoUri()`. The
+`AIService` wraps a deterministic fake provider: `MockLanguageModelV3` from `ai/test`, which
+streams one fixed reply and answers the title request with one fixed title. The parent starts
+the child with every provider key unset (`GEMINI_API_KEY`, `OPENAI_API_KEY`,
+`ANTHROPIC_API_KEY`, the Google and Vertex credentials, and the Langfuse keys), so no real
+provider can answer. It waits for `/health` with `spawnUntilReady`, then checks over real
+HTTP:
+
+1. `POST /auth/signup` returns a token.
+2. `POST /gpt/prompt` with that token streams Server-Sent Events whose `text` events join to
+   the fake provider's reply, with no `error` event. The `done` event carries the new
+   conversation's `historyId` and the fake title.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. Matching the fake reply exactly also proves the request did not fall back to
+the canned demo-mode reply that `/gpt/prompt` sends when no AI service resolves.
+
+**Measured time:** 11–29 s against an external replica set while other smokes ran on the same
+4-CPU container, excluding the compile. With the in-memory replica set under the same load,
+startup alone pushed a run past 2 minutes; the api smoke slowed the same way. Budget: 30 s.
+
+If the in-memory replica set is slow or times out waiting for a primary, point the smoke at a
+running replica set the way CI does:
+
+```bash
+TERRENO_TEST_MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs0" bun run --cwd ai smoke
+```
+
+## Add an e2e test
+
+- **New route, option, ask kind, or block:** add a test in `ai/src/`, next to the code, with a
+  scripted mock model. The smoke stays one happy path; do not add edge cases to it.
+- **The chat path changed** (for example, the `/gpt/prompt` body or the SSE event shape):
+  update the checks in `ai/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible chat flow** (for example, asks or blocks in `GPTChat`): add a Playwright
+  spec in `example-frontend/e2e/` (or extend `ai-chat.spec.ts`), following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), against example-backend.
+
+See [the ai reference](../../reference/ai.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/src/docs/versioned/58.0.0/testing/e2e/announcements.md

@@ -0,0 +1,63 @@
+# @terreno/announcements e2e tests
+
+Run the announcements smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd announcements smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | Pending and feed selection, audience and platform rules, acknowledgements, impressions, clicks, release import, the admin overview, and help routes through supertest (`src/tests/*.test.ts`) | `bun run --cwd announcements test` |
+| Smoke | The compiled plugin publishing an announcement and serving it to a signed-in user from a real server in a child process | `bun run --cwd announcements smoke` |
+| E2E | None yet. example-frontend has no Playwright spec for announcements | none |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`announcements/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/announcements/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/api` and `@terreno/announcements` by package name. The
+child builds a `TerrenoApp` with a passport-local user model, an inline `/health` plugin, and
+`AnnouncementsApp` with an `uploadToken`, and listens on a `freePort()` against
+`smokeMongoUri()`. The parent waits for `/health` with `spawnUntilReady`, then checks over
+real HTTP:
+
+1. `POST /announcements/import-release` with the upload token and `publish: true` returns one
+   published announcement.
+2. `POST /auth/signup` returns a token for a new, non-admin user.
+3. `GET /announcements/feed` with that token lists the announcement with its title.
+
+It prints one `✅` line per check and exits 1 on the first failure, after printing the
+server's output. The announcement is created through release import, the route release
+pipelines call, because signup never grants admin. Creating it through the admin CRUD routes
+would mean seeding an admin straight into MongoDB. Each run imports under a new release
+version, so reruns against a shared `TERRENO_TEST_MONGODB_URI` never collide.
+
+**Measured time:** 4.5–8 s in three root `bun run smoke` runs (the [guide's](../e2e.md#package-pages) figure), excluding the compile. Earlier single runs took
+21–24 s on a quiet 4-CPU container against an external replica set, and 40–100 s when parallel builds starved the CPU, excluding the compile. Most of it is loading
+the compiled packages in the child; under load, password hashing on signup alone took 17 s.
+Budget: 30 s.
+
+If the in-memory replica set times out waiting for a primary, point the smoke at a running
+replica set the way CI does:
+
+```bash
+TERRENO_TEST_MONGODB_URI="mongodb://127.0.0.1:27017/?replicaSet=rs0" bun run --cwd announcements smoke
+```
+
+## Add an e2e test
+
+- **New route, option, or visibility rule:** add a test in `announcements/src/tests/`. The
+  smoke stays one happy path; do not add edge cases to it.
+- **The publish-to-feed path changed** (for example, the import body or the feed response
+  shape): update the checks in `announcements/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible flow** (for example, the announcement modal or the changelog feed): add a
+  Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), against example-backend, which
+  already registers the plugin.
+
+See [the announcements reference](../../reference/announcements.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.

package/src/docs/versioned/58.0.0/testing/e2e/api-health.md

@@ -0,0 +1,54 @@
+# @terreno/api-health e2e tests
+
+Run the api-health smoke after a compile:
+
+```bash
+bun run compile && bun run --cwd api-health smoke
+```
+
+## Test tiers
+
+| Tier | What it covers | Command |
+| --- | --- | --- |
+| Unit and integration | `HealthApp` options and branches (custom path, `enabled: false`, sync, async, failing, and throwing checks) through supertest (`src/healthApp.test.ts`) | `bun run api-health:test` |
+| Smoke | The compiled plugin answering health checks from a real server in a child process | `bun run --cwd api-health smoke` |
+| E2E | The plugin as example-backend registers it, with a MongoDB check. Client smokes that start example-backend (`spawnExampleBackend`) wait on its `/health`, and example-frontend's Playwright suite runs against that backend | `bun run frontend:e2e` |
+| Manual regression | Cases in `docs/regression/` | none |
+
+## The smoke
+
+[`api-health/e2e/smoke.ts`](https://github.com/TerrenoLabs/terreno/blob/master/api-health/e2e/smoke.ts)
+runs at the `http` layer. It re-runs itself with a `serve` argument to start a child process
+that imports the compiled `@terreno/api-health` by package name, registers `HealthApp` on a
+plain Express app the way `TerrenoApp.register` does, and listens on a `freePort()`. It
+registers the plugin twice: once with defaults, and once at `/health/down` with a `check` that
+reports a dependency down. The parent waits for `/health` with `spawnUntilReady`, then checks
+over real HTTP:
+
+1. `GET /health` returns 200 with `{healthy: true}`.
+2. `GET /health/down` returns 503 with `healthy: false` and the check's `details`.
+
+The 503 is part of the happy path for this plugin: it is the status load balancers and Cloud
+Run probes act on. It prints one `✅` line per check and exits 1 on the first failure, after
+printing the server's output. A compiled plugin patched to always answer 200 fails check 2. A
+default route that stops answering 2xx shows up as a `spawnUntilReady` timeout, not as check 1.
+
+The smoke uses no `TerrenoApp`, so it needs no user model, MongoDB, or secrets. That also keeps
+it free of dependencies api-health does not already declare.
+
+**Measured time:** 2 s in three root `bun run smoke` runs (the [guide's](../e2e.md#package-pages) figure), excluding the compile. A single run that also loads
+`@terreno/test` cold took about 8 s on an idle machine and 11–20 s under load. Budget: 30 s.
+
+## Add an e2e test
+
+- **New option or branch:** add a unit test in `api-health/src/healthApp.test.ts`. The smoke
+  stays one happy path; do not add edge cases to it.
+- **The wire contract changed** (the status codes or the `{healthy, details}` body): update the
+  checks in `api-health/e2e/smoke.ts` and keep it within 30 s.
+- **A user-visible flow** (for example, an app screen that reports service health): add a
+  Playwright spec in `example-frontend/e2e/`, following
+  [Write a Playwright spec](../e2e.md#write-a-playwright-spec), with the plugin wired into
+  example-backend.
+
+See [the `@terreno/api-health` reference](../../reference/api-health.md) for the plugin API and
+[the `@terreno/test` reference](../../reference/test.md#smoke-helpers) for the smoke helpers.