@terreno/mcp 57.15.0 → 57.16.2

package/dist/docs/versioned/57.15.0/implementationPlans/mcp-service-tokens.md

@@ -0,0 +1,282 @@
+# Implementation Plan: MCP service tokens
+
+**Status:** Complete — shipped in #1263  
+**Roadmap:** Area=`mcp`, Target=`Released`, Impact=`Feature`  
+**Branch:** TBD  
+**Owner:** unassigned  
+**Created:** 2026-09-03  
+**Depends on:** [model-router-mcp.md](model-router-mcp.md) (shipped — `POST /mcp` + `extractUserFromHeaders`)  
+**Sibling:** [app-mcp-server.md](app-mcp-server.md) (OAuth 2.1 for interactive MCP clients — complementary, not a blocker)
+
+## Goal
+
+Authenticated users mint **personal MCP service tokens** that act as that user on the
+consumer app's `POST /mcp` endpoint only. They copy an **MCP URL** plus a **Bearer
+`mcp_…` key** into external clients (Perplexity custom connectors, Claude Code, Cursor,
+Inspector) without pasting a session JWT. Admins list and revoke any user's tokens from
+the admin panel.
+
+When this is done, an operator can:
+
+1. Set `mcpServiceTokens: true` on `TerrenoApp`.
+2. Sign in to the example app, open **Settings → MCP**, create a named token, copy URL +
+   key once.
+3. Paste into Perplexity (**Custom connector → Remote → Streamable HTTP → API Key**).
+4. Call `tools/list` on `/mcp` with `Authorization: Bearer mcp_…` and see the same tools
+   that user would see over REST-backed MCP.
+5. Revoke from the settings screen or from **Admin → MCP service tokens**.
+
+## Non-Goals
+
+| Out | Why |
+| --- | --- |
+| Hosted `@terreno/mcp` (dev-time codegen server) | Different product surface |
+| `@terreno/infra-mcp` machine tokens | Separate IP; GCP/Sentry scope |
+| OAuth 2.1 / RFC 9728 for MCP | [app-mcp-server.md](app-mcp-server.md) Phase 6; tokens are the static-key path for Perplexity |
+| Per-token scopes (read-only, tool allowlists) | v1 is full user MCP permissions |
+| Token auth on REST, sync sockets, or admin HTTP | MCP-only credential (Q4) |
+| Secret in query string or connection URL | Header-only Bearer (Q3) |
+| Password re-prompt on mint | Session/JWT is enough for create/list/revoke |
+| Per-token rate limits | Existing `POST /mcp` **api** bucket applies |
+| Auto-enable when `/mcp` mounts | Explicit `mcpServiceTokens: true` (Q7) |
+| Profile-tab mint UI | Dedicated `/settings/mcp` route (Q13) |
+
+## Decisions
+
+| ID | Question | Decision |
+| --- | --- | --- |
+| Q1 | MCP surface | Consumer app `POST /mcp` on `@terreno/api` only |
+| Q2 | Identity | Token acts as **owning user**; same `modelRouter` / `registerMCPTool` permissions; no scopes in v1 |
+| Q3 | Transport | `Authorization: Bearer mcp_…`; plaintext shown **once** on create; never in URL |
+| Q4 | Power | **MCP endpoint only** — not REST, sync, or admin |
+| Q5 | Mint UX | Self-service API + example UI; new IP; hashed model in `@terreno/api` |
+| Q6 | Expiry | Optional `expiresAt` on create; default **no expiry**; expired → 401 on `/mcp` |
+| Q7 | Enablement | **`mcpServiceTokens: true`** on `TerrenoAppOptions` mounts routes + token auth |
+| Q8 | Token shape | Prefix **`mcp_`** + 32 random bytes (hex); SHA-256 hash stored; verify **before** JWT parse |
+| Q9 | Cap | Max **10** active (non-revoked, unexpired) tokens per user; 400 when over cap |
+| Q10 | UI placement | New settings route + admin changelist (not Profile tab) |
+| Q11 | Admin vs owner | Owners self-serve; **admins** list/revoke **all** users' tokens |
+| Q12 | Admin implementation | Generic **`AdminApp` model** registration (no custom widget) |
+| Q13 | User route | **`/settings/mcp`** in example-frontend |
+
+### Recorded assumptions (implementation detail)
+
+- Hash: `crypto.createHash("sha256")` (same as `AuthToken`).
+- Display prefix: first 8 characters after `mcp_` (e.g. `mcp_a1b2c3d4…`) for list UIs.
+- Revoke: set `revokedAt`; do not hard-delete rows (audit-friendly).
+- `lastUsedAt` updated on successful MCP auth (throttle optional; v1 update every auth).
+- Self-serve routes live at **`/mcp/service-tokens`** (session/JWT only).
+- Admin CRUD at **`/admin/mcp-service-tokens`** via `AdminApp` (list + revoke; create/update disabled).
+- `mcpUrl` in create response: `{publicApiUrl}/mcp` from new optional `mcpServiceTokens.publicMcpUrl` or `BETTER_AUTH_URL` / request host fallback.
+- Perplexity: GET `/mcp` is a Streamable-HTTP **405** (no GET SSE stream). POST `initialize` / `tools/list` are unauthenticated catalog in the stateless handler. Identity is enforced on **`tools/call`**. Send the same Bearer on GET and POST anyway.
+
+## Architecture
+
+```
+User (session)                External MCP client (Perplexity, etc.)
+     |                                    |
+     | POST /mcp/service-tokens          | POST|GET /mcp
+     | GET  /mcp/service-tokens            | Authorization: Bearer mcp_…
+     | DELETE /mcp/service-tokens/:id      |
+     v                                    v
+McpServiceToken model (hash only)   extractUserFromHeaders
+     |                                    |
+     |                                    +-- mcp_* ? verify hash -> User
+     |                                    +-- else Better Auth session
+     |                                    +-- else JWT
+     v                                    v
+AdminApp table (IsAdmin)            same User as REST MCP today
+list / revoke all users
+```
+
+### Connection string (operator copy-paste)
+
+Clients that accept JSON (Cursor, VS Code, Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "url": "https://api.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer mcp_<secret-shown-once>"
+      }
+    }
+  }
+}
+```
+
+Perplexity custom connector form:
+
+| Field | Value |
+| --- | --- |
+| MCP Server URL | `https://api.example.com/mcp` |
+| Transport | Streamable HTTP |
+| Authentication | API Key |
+| API Key | full `mcp_…` string (Perplexity sends as Bearer) |
+
+## Models
+
+**`McpServiceToken`** (`api/src/models/mcpServiceToken.ts` + `api/src/types/mcpServiceToken.ts`)
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `userId` | ObjectId ref User | owner; required; indexed |
+| `name` | string | user label ("Perplexity laptop"); required; trim |
+| `tokenPrefix` | string | display only, e.g. `a1b2c3d4` |
+| `tokenHash` | string | SHA-256 of full `mcp_…`; unique |
+| `expiresAt` | Date? | optional; TTL index when set |
+| `revokedAt` | Date? | set on revoke |
+| `lastUsedAt` | Date? | updated on MCP auth |
+
+Plugins: `createdUpdatedPlugin`, `findOneOrNone`, `findExactlyOne`. **No** `isDeletedPlugin
+(revoke is explicit). Statics: `issueFor(user, {name, expiresAt?})` → `{token, doc}`;
+`verify(plaintext)` → `McpServiceTokenDocument | null` (not revoked, not expired);
+`revokeForUser(user, id)`; `countActiveForUser(userId)`.
+
+OpenAPI / admin metadata: **never** expose `tokenHash`. Create response is the only time
+`token` plaintext appears.
+
+## APIs
+
+### Self-serve (`/mcp/service-tokens`)
+
+Mounted only when `mcpServiceTokens: true`. All routes require session/JWT
+(`authenticateMiddleware`); **reject** `mcp_` Bearer on these routes (401 — tokens cannot
+mint tokens).
+
+| Method | Path | Body / params | Response |
+| --- | --- | --- | --- |
+| POST | `/mcp/service-tokens` | `{name, expiresAt?}` | `{data: {id, name, token, tokenPrefix, mcpUrl, expiresAt, created}}` |
+| GET | `/mcp/service-tokens` | `?page&limit` | `{data: [...], page, limit, total, more}` — no `token` field |
+| DELETE | `/mcp/service-tokens/:id` | — | `{data: {id, revokedAt}}` — owner only |
+
+Errors: 400 over cap (10); 404 not found / not owner; 401 unauthenticated.
+
+### MCP auth (`extractUserFromHeaders`)
+
+When `mcpServiceTokens` enabled and `Authorization` bearer starts with `mcp_`:
+
+1. Hash and lookup active token.
+2. Load `userId` → `User`; `rejectIfDisabled`.
+3. Set `lastUsedAt` (fire-and-forget).
+4. Return user (same type as JWT path).
+
+Order: **service token → Better Auth session → JWT** (Q8).
+
+### Admin (`AdminApp`)
+
+Register on consuming app (example-backend):
+
+```typescript
+{
+  model: McpServiceToken,
+  routePath: "/mcp-service-tokens",
+  displayName: "MCP service tokens",
+  group: "Platform",
+  listFields: ["name", "tokenPrefix", "userId", "lastUsedAt", "expiresAt", "revokedAt", "created"],
+  permissions: {create: [], update: [], delete: [Permissions.IsAdmin], list: [Permissions.IsAdmin], read: [Permissions.IsAdmin]},
+  // responseHandler strips tokenHash
+}
+```
+
+Admin **delete** sets `revokedAt` (override default hard delete in `preDelete` or use
+custom delete route).
+
+## UI
+
+### Example-frontend `/settings/mcp`
+
+- Linked from Profile (button "MCP connections" → `/settings/mcp`).
+- **Create:** name field, optional expiry date (`DateTimeField`), submit → modal with
+  **copy-once** `mcpUrl`, full `token`, and JSON snippet.
+- **List:** name, prefix, created, last used, expires, Revoke button.
+- Uses generated SDK hooks after `bun run sdk`.
+- Loading / error / empty states.
+
+### Admin
+
+Generic `AdminModelTable` via existing `[model]` routes — no new Expo screen.
+
+## TerrenoApp integration
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpServiceTokens: {
+    enabled: true,
+    publicMcpUrl: process.env.PUBLIC_API_URL, // optional; shown in create response
+  },
+});
+```
+
+Boolean `mcpServiceTokens: true` is shorthand for `{enabled: true}`.
+
+When enabled:
+
+1. Register self-serve routes (before or after `mountMCPServer` — order irrelevant).
+2. Pass `mcpServiceTokens: true` into `MCPAuthContext` so `extractUserFromHeaders` verifies tokens.
+
+`/mcp` mounting unchanged (still requires MCP tools). Token routes can mount even if no
+tools yet (harmless); example-backend already exposes MCP.
+
+## Phases
+
+| Phase | Delivers |
+| --- | --- |
+| 1 | Model, issue/verify/revoke, `extractUserFromHeaders` integration, unit tests |
+| 2 | Self-serve HTTP routes, `TerrenoApp` flag, OpenAPI |
+| 3 | Example-backend flag + `AdminApp` registration |
+| 4 | Example-frontend `/settings/mcp` + SDK + verification artifacts |
+| 5 | Docs (how-to connect Perplexity, reference, explanation cross-link) |
+
+## Feature Flags & Migrations
+
+- No feature flag beyond `mcpServiceTokens` opt-in.
+- New collection `mcpservicetokens` (mongoose default pluralization). No backfill.
+- Index: `{userId: 1, revokedAt: 1}`, unique `tokenHash`, TTL on `expiresAt` when present.
+
+## Activity Log & User Updates
+
+- Optional: `logger.info` on mint/revoke with `userId` + `tokenPrefix` (never log full token).
+- No email on mint in v1.
+
+## Not Included / Future Work
+
+- OAuth 2.1 ([app-mcp-server.md](app-mcp-server.md)) — use for Claude web connectors that cannot send static keys.
+- Scoped tokens (read-only MCP, named tool allowlist).
+- REST-wide personal access tokens.
+- Token rotation / regenerate keeping same id.
+- Audit log table for MCP calls per token.
+
+## Files to Create / Modify
+
+| Area | Files |
+| --- | --- |
+| Model | `api/src/models/mcpServiceToken.ts`, `api/src/types/mcpServiceToken.ts` |
+| Routes | `api/src/mcp/serviceTokens.ts`, `api/src/mcp/serviceTokens.test.ts` |
+| Auth | `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts` |
+| App | `api/src/terrenoApp.ts`, `api/src/index.ts` |
+| Example backend | `example-backend/src/server.ts` (flag + admin model) |
+| Example frontend | `example-frontend/app/settings/mcp.tsx`, `example-frontend/app/settings/_layout.tsx`, link from `profile.tsx`, SDK regen |
+| Docs | `docs/how-to/connect-mcp-service-token.md`, `docs/how-to/expose-mcp-tools.md`, `docs/reference/api.md`, `docs/explanation/authentication.md` |
+
+## Task List
+
+See [`docs/tasks/mcp-service-tokens.md`](../tasks/mcp-service-tokens.md).
+
+## Acceptance Criteria
+
+| Criterion | Verification |
+| --- | --- |
+| Flag off: no `/mcp/service-tokens` routes; `mcp_` bearer on `/mcp` is ignored | `api` unit + integration test |
+| Flag on: create returns `mcp_` plaintext once; list never includes it | Route tests |
+| Active cap 10 per user | Route test returns 400 on 11th create |
+| Optional expiry: expired token 401 on `/mcp` | Auth test + HTTP initialize |
+| Revoked token 401 on `/mcp` | Auth test |
+| Valid token: `tools/list` as owner user | Supertest MCP handler or `invokeMCPTool`-style test |
+| Session JWT cannot call self-serve routes with `mcp_` only | Route test |
+| Admin lists all users' tokens; admin revoke blocks MCP | Admin integration test |
+| Perplexity-shaped GET `/mcp` is JSON-RPC 405; POST `tools/call` with same Bearer acts as owner | HTTP integration test + how-to |
+| Example `/settings/mcp` create-copy-revoke flow | Manual UI + artifact |
+| Docs: Perplexity form fields + JSON snippet | Doc review |

package/dist/docs/versioned/57.15.0/implementationPlans/migrate-admin-to-syncdb.md

@@ -0,0 +1,211 @@
+# Implementation Plan: Migrate built-in admin to syncdb
+
+**Status:** Complete
+**Roadmap:** Area=`admin`, Target=`Released`, Impact=`Improvement`  
+**Branch:** `cursor/migrate-admin-to-syncdb-de61`
+**Owner:** Josh Gachnang
+**Created:** 2026-09-01
+**Grow run:** https://cursor.com/agents/bc-47350376-6566-4c5a-aee2-e6a28698de61
+
+## Goal
+
+Move **built-in admin model list/read/create/update/delete** for collections that already use **String `_id`** onto **windowed local-first syncdb**, with **REST remaining the membership source** (search, sort, pagination, RBAC). Remaining admin RPC (config, scripts, roles, comms, AI, consent, documents, version-config, background-tasks) leaves RTK `injectEndpoints` for a **tiny native `fetch` wrapper** with **host-injected auth**.
+
+Ship **great characterization coverage and CI first**, then protocol, then UI, then hosts. Dual-run RTK `api` for one release so existing hosts keep working; **deprecate `api` / `injectEndpoints` in docs in this IP**; **delete the inject path in the next Terreno major**.
+
+## Non-Goals
+
+- Migrating ObjectId `_id` models (`User`, `AdminAuditLog`, and any other ObjectId collection) onto syncdb. Those stay **fetch CRUD**. No schema migration in this IP.
+- Axios. Admin HTTP uses native `fetch` plus a small wrapper.
+- Full-stream `reconcile()` for admin collections. Admin subscribe is **window mode**: no snapshot of the entire owner/tenant/broadcast stream.
+- A second `sync:` registration on the admin `modelRouter`. One sync registration per model stays on the **app** router (`/todos`, not `/admin/todos`).
+- Changing app-user collections to broadcast. Users keep owner/tenant streams; admin is an extra fan-in (`adminBroadcast`).
+- Removing `injectEndpoints` in this release (next major).
+- Replacing generated OpenAPI SDK, Better Auth Redux, or feature-flag RTK with syncdb.
+
+## Decisions
+
+| # | Question | Decision |
+| --- | --- | --- |
+| Q1 | What data plane does admin use? | String-`_id` **model CRUD** → **syncdb** (windowed). Remaining admin **RPC is not RTK**; dedicated **fetch** hooks. |
+| Q2 | Coverage-first? | **A:** ≥95% line+function on admin packages; **fix CI coverage scope**; add embedded + SPA CRUD E2E **before** behavior migration. |
+| Q3 | HTTP client | Native **`fetch` + tiny wrapper** (AbortController timeout, credentials, JSON/FormData, `APIError`). **No axios**. |
+| Q4 | Auth injection | Host injects `{baseUrl, getAuthHeaders, credentials}`. SPA: `credentials: "same-origin"`. Embedded: Bearer. |
+| Q5 | Local-first shape | **Windowed local-first:** load more hydrates more; keep loaded rows synced. |
+| Q6 | Which models? | **B:** Sync only models that already have **String `_id`**. ObjectId models stay fetch CRUD. |
+| Q7 | RTK dual-run | **B:** Dual-run **this release** (`api` still works). Delete RTK inject path **next major**. |
+| Q8 | List membership vs store | **A:** REST list/search/sort/RBAC stays **membership**. Pages **upsert** into TinyBase. Writes + per-id via syncdb. **Full-stream reconcile OFF** for admin collections. |
+| Q9 | Deltas vs new matches | **A + Refresh:** deltas **update/delete known ids only**. New matches via load-more or **visible Refresh**. No surprise inserts. |
+| Q10 | Owner streams? | Admin needs a **cross-owner** view. Not the signed-in admin's owner stream. |
+| Q11 | Dual-run vs cutover | Land **both** in this IP. **Deprecate `api` in docs now**. Remove `injectEndpoints` **next Terreno major**. |
+| Q12 | Conflicts | **`ConflictSheet`** (`useServer` / `keepMine`) like the example app. |
+| Q13 | Fan-in | **`adminBroadcast: true`** on the **existing** collection `SyncConfig`. Deltas also to `{collection}\|admin`. Admin clients join in **window** mode: no full snapshot/reconcile; hydrate via REST ids + `GET /sync/entities`. |
+
+## Architecture
+
+### Today
+
+Admin CRUD is **RTK `injectEndpoints`** in `@terreno/admin-frontend` (`useAdminApi.ts` → `GET/POST/PATCH/DELETE /admin/{routePath}` plus bulk-patch). Config and other RPC are more inject hooks (`useAdminConfig`, scripts, roles, configuration, documents, comms, AI explorer, consent, version-config, background-tasks).
+
+The backend mounts a **separate** `modelRouter` under `/admin/...` **without** `sync:`. Example `Todo` is already synced on the **app** router (`example-backend/src/api/todos.ts`) with String `_id` + `syncPlugin`. Same Mongo model, different mount. Registry allows **one sync registration per model**; a second `sync` on the admin router is forbidden (`api/src/sync/registrationSideEffects.ts`).
+
+Canonical docs still say profile/admin stay on RTK (`docs/how-to/migrate-rtk-to-syncdb.md`).
+
+### Target data planes
+
+| Surface | After this IP | Auth |
+| --- | --- | --- |
+| String-`_id` model changelist + form | REST membership + TinyBase rows + `{collection}\|admin` window subscribe | Host-injected (cookie or Bearer) via fetch for REST; existing sync socket auth for deltas/mutate |
+| ObjectId model changelist + form | Fetch CRUD only (same `/admin/{routePath}` URLs) | Same fetch wrapper |
+| Admin RPC (config, scripts, roles, comms, …) | Fetch hooks; **not** RTK | Same fetch wrapper |
+| Host RTK `api` | Still accepted; dual-run. Deprecated in docs | Unchanged |
+
+### Windowed local-first (String `_id`)
+
+1. **Membership:** `GET /admin/{routePath}` (existing list/search/sort/RBAC) returns the **page of ids** (and enough fields to render immediately).
+2. **Hydrate:** those ids **upsert** into TinyBase. Missing entities come from `GET /sync/entities` (already exists) when the list payload is incomplete for sync seq / tombstones.
+3. **Subscribe:** admin client joins collection stream `{collection}|admin` in **window** mode. Socket handlers must **not** send a full snapshot or trigger client `reconcile()` of the whole user stream.
+4. **Deltas:** apply **update/delete only if the id is already in the local window**. Unknown ids are ignored (no surprise inserts).
+5. **Load more / Refresh:** load more requests the next REST page and hydrates those ids. **Refresh** re-runs the current REST query and upserts/removes to match membership (visible control).
+6. **Writes:** `useMutate` / `POST /sync/mutate` (same write path as the app) plus admin REST bulk-patch remaining on fetch until a later IP if bulk is not a sync mutation.
+
+Do **not** set collection `scope` to broadcast for the app. App clients keep owner/tenant streams. `adminBroadcast: true` is an **additive fan-in**: change-stream emit also publishes to `{collection}|admin`. Only clients that subscribe in admin window mode join that stream.
+
+### Why not a second sync registration
+
+`registerSync` throws if the model is already registered. Admin REST stays the **admin RBAC/list** surface. Sync stays on the **app** collection registration. Admin UI does not invent a second TinyBase table name; it uses the same collection tag as the app (`todos`), with an admin stream suffix.
+
+### Fetch wrapper
+
+New module in `@terreno/admin-frontend` (not axios, not `emptyApi` JWT refresh). Responsibilities:
+
+- `AbortController` timeout
+- `credentials` (`same-origin` for SPA cookies; `omit`/`include` as injected)
+- `getAuthHeaders()` for Bearer (embedded)
+- JSON body by default; `FormData` passthrough
+- Map non-2xx to `APIError` shape admin already understands
+
+Hosts pass `{baseUrl, getAuthHeaders, credentials}` into `AdminProvider` / existing admin context. SPA must keep cookie session working; embedded example-frontend must keep Bearer.
+
+### Dual-run
+
+`AdminModelTable` / `AdminModelForm` / related hooks:
+
+- If `syncDb` + `adminRequest` (fetch client) are present **and** the model is String `_id` + registered for sync with `adminBroadcast`, use the new path.
+- Else existing `useAdminApi(api, …)` RTK path.
+
+No host is forced to pass `syncDb` this release. Docs tell new/updated hosts to inject both.
+
+### Conflicts
+
+Same `ConflictSheet` as the example app: `useServer` / `keepMine`. Admin window does not invent a second conflict UX.
+
+## Models
+
+No new Mongo models. No `_id` type changes.
+
+| Model (example) | `_id` | This IP |
+| --- | --- | --- |
+| `Todo` | String | Tracer: windowed syncdb + adminBroadcast |
+| Other app models already String `_id` + `sync` | String | Same pattern once `adminBroadcast: true` |
+| `User`, `AdminAuditLog`, other ObjectId | ObjectId | Fetch CRUD only |
+
+`SyncConfig` gains:
+
+```ts
+adminBroadcast?: boolean;
+```
+
+Default `false`. When `true`, emitters also send deltas to `{collection}|admin`. Permission to join that stream is **admin-only** (reuse existing admin permission checks used by `/admin/*`, not owner-stream membership).
+
+## APIs
+
+### Additive protocol
+
+| Piece | Change |
+| --- | --- |
+| `SyncConfig.adminBroadcast` | Opt-in fan-in to `{collection}\|admin` |
+| `sync:subscribe` | Accept window/admin mode (exact payload field named in Pick; suggested `{mode: "window"}` or subscribe to `{tag}\|admin` without snapshot) |
+| `sync:subscribed` | Must not dump full stream snapshot for window subscribers |
+| `GET /sync/entities` | Hydrate known ids (already exists; pin tests) |
+| `GET /admin/{routePath}` | Unchanged membership/search/RBAC |
+| `POST /sync/mutate` | Writes for String `_id` synced models (already exists) |
+
+### Unchanged REST (still used)
+
+- `GET /admin/config`
+- `/admin/{routePath}` list/read/create/update/delete/bulk-patch (membership + ObjectId CRUD + bulk)
+- `/rbac/*`, scripts, configuration, documents, comms, AI, consent, version-config, background-tasks
+
+## Notifications
+
+None. No user-facing comms templates.
+
+## UI
+
+- **Changelist (`AdminModelTable`):** windowed rows from TinyBase for String `_id` synced models; REST pagination/search/sort unchanged; **Refresh** control; load more hydrates more ids; no rows appearing that were not in the last membership set.
+- **Form (`AdminModelForm`):** read/write via syncdb for those models; ObjectId stays fetch.
+- **Conflicts:** `ConflictSheet` when `useConflicts` reports for admin-loaded ids.
+- **Hosts:** `example-frontend` `/admin` and `admin-spa` `/console` both wired for the tracer.
+- Admin v2 `home.slots` unchanged.
+
+## Phases
+
+1. **Characterization + CI** — raise coverage, fix LCOV scope, add package CI jobs, pin URL goldens, add CRUD E2E. **No product behavior change.**
+2. **Fetch wrapper** — client + host injection; migrate RPC inject hooks onto fetch (dual-run until hosts pass the wrapper).
+3. **Protocol** — `adminBroadcast`, `{collection}|admin` emit, window subscribe, skip reconcile, known-id delta apply, entity hydrate tests.
+4. **Admin UI dual-run** — table/form/ConflictSheet/Refresh; ObjectId stays fetch.
+5. **Hosts** — example-frontend + admin-spa; cookie vs Bearer must both work.
+6. **Docs/skills** — stop saying admin collection CRUD stays RTK; deprecate `api` inject; changelog.
+
+Phase 1 is a **hard gate**. Protocol/UI tasks are blocked until Phase 1 acceptance is green.
+
+## Feature Flags & Migrations
+
+No feature flag. `adminBroadcast` is explicit per collection. Hosts opt into the new UI path by passing `syncDb` + fetch client.
+
+**Deprecation:** this release documents “do not add new `injectEndpoints` in admin-frontend.” Next major deletes `useAdminApi` RTK inject and the `api` prop requirement.
+
+## Activity Log & User Updates
+
+No end-user product changelog beyond admin operators. Framework changelog records protocol + deprecation.
+
+## Not Included / Future Work
+
+- ObjectId → String `_id` + `syncPlugin` for User / audit log (own IP; mongoose-schema-safety).
+- Delete RTK inject (next major).
+- Bulk-patch as sync mutations.
+- Admin-only collections with no app router (would still need one `sync:` registration, not a duplicate).
+
+## Files to Create / Modify
+
+**Phase 1:** `admin-frontend/**/*.test.*`, `admin-frontend/bunfig.toml`, `admin-backend` coverage config, `.circleci/continue-config.yml`, root `package.json` (`admin-frontend:test`), `example-frontend/e2e/admin*.spec.ts`, `admin-spa/e2e/**`.
+
+**Phase 2:** `admin-frontend/src/adminRequest.ts` (name at Pick), host context types, RPC hooks listed under Architecture.
+
+**Phase 3:** `api/src/sync/types.ts`, `streams.ts`, change-stream emit, `socketHandlers.ts`, `syncdb/src/client.ts` + subscribe/reconcile/delta applier, tests in `api/src/sync/*.test.ts` and `syncdb/src/sync/*.test.ts`.
+
+**Phase 4:** `AdminModelTable`, `AdminModelForm`, conflict wiring, `useAdminApi` dual-run.
+
+**Phase 5:** `example-frontend` store/syncdb + admin layout; `admin-spa` session fetch + SyncDbProvider.
+
+**Phase 6:** `docs/reference/admin-*.md`, `docs/reference/syncdb.md`, `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/admin-frontend.md` (if present), `terreno-data-fetching` skill (admin fetch exception), `verify-ui-changes`, changelog.
+
+## Task List
+
+[docs/tasks/migrate-admin-to-syncdb.md](../tasks/migrate-admin-to-syncdb.md)
+
+## Acceptance Criteria
+
+- [ ] `admin-frontend` and `admin-backend` report ≥95% line and function coverage on **package source** (not `@terreno/test/dist`). CircleCI runs both package jobs.
+- [ ] Embedded `/admin` and SPA `/console` have CRUD E2E for Todos (list, create, edit, delete, search/filter, bulk where already specified) **before** protocol/UI cutover, and they still pass after cutover.
+- [ ] Example **Todos** admin changelist is windowed local-first: REST membership, TinyBase rows, `{todos}|admin` deltas update known ids only, Refresh/load-more add membership, ConflictSheet works.
+- [ ] ObjectId models still CRUD via fetch; no `_id` migration.
+- [ ] SPA cookie auth and embedded Bearer auth both work; no axios in the new client.
+- [ ] Hosts that still pass only `api` keep working (dual-run).
+- [ ] Docs and skills no longer tell agents to keep admin **collection CRUD** on RTK; `api`/`injectEndpoints` marked deprecated; next-major removal called out.
+- [ ] `bun run lint` and focused package tests pass; `verify-ui-changes` for `/admin` and `/console` tracer.
+
+## Tracer
+
+Example **Todos** admin changelist: `example-frontend` `/admin` and `admin-spa` `/console`.

package/dist/docs/versioned/57.15.0/implementationPlans/migrate-cicd-to-circleci-research.md

@@ -0,0 +1,127 @@
+# Research: Migrate CI/CD to CircleCI
+
+**Status:** Research complete — decisions recorded in IP `migrate-cicd-to-circleci.md`  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1088
+**Date:** 2026-08-17  
+**Repo:** TerrenoLabs/terreno (`master` @ `1e3e79a6`)  
+**Branch:** `cursor/migrate-cicd-circleci-2b6d`
+
+## Scope statement
+
+Investigate what “migrate all CI/CD to CircleCI” means for Terreno: inventory every GitHub Actions workflow, classify what is portable vs GitHub-native, map secrets/OIDC/deploy targets, and surface **candidate** CircleCI architectures with tradeoffs. No implementation decisions are committed here.
+
+## Current state (findings)
+
+### Scale
+
+- **~36** hand-maintained `.github/workflows/*.yml` workflows
+- **4** agentic `*.lock.yml` pipelines (gh-aw / Copilot), compiled from `.md` sources
+- **No** `.circleci/` today
+- **No** `.github/actions/` composites — Bun setup + cache is copy-pasted per workflow
+- Helper scripts live under `.github/workflows/scripts/` (EAS/fingerprint) and `.github/scripts/`
+
+### Category inventory
+
+| Category | Examples | CircleCI portability |
+|----------|----------|----------------------|
+| Package CI | `api-ci`, `ui-ci`, `rtk-ci`, `ai-ci`, `comms-ci`, `mcp-server-ci`, example-* | High |
+| Web E2E | `e2e-ci`, `admin-spa-ci`, `admin-spa-integration` (Playwright + Mongo) | High–medium |
+| Mobile E2E | `demo-appium-ci` (Android + macos-15 iOS), `maestro-e2e` | Medium–low (macOS/Android emulator parity) |
+| Expo/EAS | `eas-pr`, `eas-dev-build`, `fingerprint-gate` | Medium (CLI portable; PR labels/comments GitHub-centric) |
+| Deploy GCP | `cd.yml`, `preview-cleanup` | Medium–hard (OIDC is GitHub-issuer only today) |
+| Deploy Netlify | `demo-deploy`, `frontend-example-deploy`, `docs-deploy` | High–medium |
+| Publish | `publish-on-tag`, `publish-feature-flags-manual` | Medium–hard (token push to master, Zoom, cross-workflow dispatch) |
+| Policy | `repo-policies`, `rulesync-check`, `dco` | High (DCO is GitHub-PR metadata) |
+| Security | `codeql-analysis` | Low (GitHub Code Scanning / Security tab) |
+| GitHub-native | `dependabot-auto-merge`, `triage`, `roadmap-generate` | Low–none |
+| Agentic | `architectural-pr-review`, `agentics-maintenance`, `*.lock.yml` | None (gh-aw, `pull_request_target`, Copilot) |
+
+### Shared CI patterns
+
+1. `oven-sh/setup-bun@v2` (`bun-version: latest`, sometimes pinned `1.4.0` for EAS)
+2. `actions/cache` on `~/.bun/install/cache` keyed by OS + ref + lockfile
+3. `bun install --frozen-lockfile` then package `lint` / `compile` / `test(:coverage|:ci)`
+4. Mongo via `supercharge/mongodb-github-action` (image `mirror.gcr.io/library/mongo`) for api/ai/example-backend/e2e
+5. Most package CI is **`on: push` with path filters**, not `pull_request` — checks appear when the PR head branch is pushed
+6. Path filtering also uses `dorny/paths-filter` inside larger workflows (`cd.yml`, deploys)
+
+### Deploy / release targets
+
+| Target | Mechanism |
+|--------|-----------|
+| GCP `flourish-terreno` | Cloud Run (backend, tasks, mcp), Artifact Registry, Infra Manager terraform |
+| Auth to GCP | Workload Identity Federation — issuer `https://token.actions.githubusercontent.com` (`terraform/modules/github_oidc`) |
+| Preview cleanup | Still uses `GCP_SA_KEY` JSON (not WIF) |
+| Netlify | demo, example-frontend, docs sites via `nwtgck/actions-netlify` |
+| npm | Tag-driven publish of ~12 `@terreno/*` packages |
+| EAS Cloud | PR updates/builds + manual workflow dispatch |
+| GitHub Deployments API | CD + Netlify preview environments |
+
+### Secrets / vars (union, migration-relevant)
+
+**Secrets:** `NPM_TOKEN`, `EXPO_TOKEN`, `NETLIFY_*`, `GCP_SA_KEY`, `MCP_SENTRY_DSN`, `E2E_*`, `CURSOR_API_KEY`, `REPO_ADMIN_TOKEN`, `ROADMAP_PROJECT_TOKEN`, `ZOOM_WEBHOOK_*`, plus gh-aw Copilot tokens on lockfiles.
+
+**Vars:** `GCP_WIF_PROVIDER_PROD`, `GCP_TF_ADMIN_SA_PROD`, `GCP_CD_DEPLOYER_SA_PROD`, `GCP_TF_PROJECT_ID_PROD`, `GCP_INFRA_MANAGER_LOCATION`, `ARCHITECTURAL_REVIEW_MODEL`, `TERRENO_PROJECT_NUMBER`.
+
+### Branch protection (documented)
+
+`docs/explanation/repository-settings.md`: require status checks including **Repository policies**, **package CI**, and **Rulesync Check** relevant to the change. Path-filtered checks are not always present — any CircleCI cutover must remap required checks carefully.
+
+### External / CircleCI platform notes
+
+- Official migration guide: map Actions → CircleCI jobs/workflows; Actions Marketplace ≈ Orb Registry ([CircleCI migrate from GitHub](https://circleci.com/docs/guides/migrate/migrating-from-github/)).
+- Monorepo best practice: **dynamic config** (`setup: true`) + **path-filtering** orb so only affected packages run ([2026 monorepo guidance](https://www.devopsness.com/blog/circleci-best-practices-2026-07-19)).
+- `circleci/node` orb **≥7.2.0** has first-class Bun (`install-bun`, frozen lockfile, cache) ([node-orb Bun support](https://github.com/oven-sh/bun/discussions/22830)).
+- GCP OIDC from CircleCI is supported but requires a **new** Workload Identity provider (not a drop-in for the current GitHub-only module).
+
+## Candidate options (not chosen)
+
+### A. Full cutover (literal “all”)
+
+Move every runnable pipeline to CircleCI; disable GHA workflows.
+
+- **Pros:** Single CI vendor; one secrets home; one config language.
+- **Cons:** Breaks CodeQL Security tab, Dependabot auto-merge, gh-aw agentic bots, issue triage, roadmap generate, `pull_request_target` review, GitHub Deployments UX unless reimplemented via API. Highest risk and cost.
+
+### B. Hybrid “CI/CD on CircleCI, GitHub stays for GitHub-native”
+
+Move package CI, E2E, Netlify, GCP CD, EAS triggers, publish to CircleCI. Keep CodeQL, Dependabot, DCO/triage/roadmap, and all gh-aw agentic workflows on GitHub Actions.
+
+- **Pros:** Matches “migrate CI/CD” intent without destroying OSS/agentic GitHub integrations; clear ownership split.
+- **Cons:** Two systems forever; dual required-check configuration; doc/contrib complexity.
+
+### C. Phased hybrid with long dual-run
+
+Same end-state as B, but phases: (1) mirror package CI, (2) Netlify, (3) EAS/fingerprint, (4) GCP OIDC + CD, (5) publish last. GHA remains required until each phase proves green.
+
+- **Pros:** Lowest blast radius; easy rollback; validates CircleCI org/contexts/credits before cutting release path.
+- **Cons:** Temporary double spend; longer calendar; discipline needed to delete GHA when done.
+
+### D. CircleCI for compute-heavy only; keep CD/publish on GHA
+
+Only migrate lint/test/Playwright/Appium; leave `cd.yml` + `publish-on-tag.yml` on Actions.
+
+- **Pros:** Avoids OIDC rewrite and release double-publish risk; still reduces GHA minute pressure if that is the pain.
+- **Cons:** Does not fulfill “all CI/CD”; two systems for the most critical paths.
+
+## Recommended research framing (for questions, not a plan decision)
+
+Option **C** is the lowest-risk path that still delivers a real CircleCI CD home; Option **A** is only viable if product/security accepts losing or re-homing GitHub-native surfaces. Option **D** is a scope cut, not a full migration.
+
+## Open questions (fed into Step 3)
+
+1. Literal “all” vs hybrid (what stays on GitHub)?
+2. Dual-run duration and when GHA workflows are deleted?
+3. CircleCI org/project already exist? Free vs Performance plan? Credit budget?
+4. In-scope: GCP CD + npm publish in v1, or defer?
+5. macOS Appium iOS — CircleCI macOS resource class vs keep on GHA?
+6. Who owns secrets migration and branch-protection remapping?
+7. Roadmap tracking issue after Approved?
+
+## References
+
+- Inventory of workflows: `.github/workflows/`
+- GCP OIDC: `terraform/modules/github_oidc/`
+- Deploy docs: `docs/explanation/deployment-architecture-gcp.md`, `terraform/README.md`
+- Branch protection: `docs/explanation/repository-settings.md`
+- CircleCI: [Migrating from GitHub](https://circleci.com/docs/guides/migrate/migrating-from-github/), node orb Bun support