@terreno/mcp 57.2.0 → 57.4.0

package/dist/docs/versioned/next/implementationPlans/knip-cleanup.md

@@ -0,0 +1,136 @@
+# Implementation Plan: Remove the Knip baseline
+
+**Status:** Complete  
+**Created:** 2026-09-09  
+**Owner:** unassigned  
+**Primary packages:** repo-wide (`knip.jsonc`, `scripts/static-analysis/`, every workspace Knip currently fingerprints)  
+**RTK deprecation flag:** None
+
+## Goal
+
+`bun run analyze:full` stays green and Knip has no baseline file. Every finding that existed on 2026-09-08 (~1076 fingerprints: 529 default + 547 production) is either **gone from the live Knip report** (fixed) or **declared in `knip.jsonc` with a one-line reason** (disabled).
+
+Inventory snapshot (do not treat as the live list — Pick re-runs Knip):
+
+| Class | Default count (approx.) | Typical cause |
+| --- | --- | --- |
+| unused files | 123 | missing entries (`*.isolated.*`, `scripts/**/*.test.ts`, mcp tests, generated skill copies) |
+| unused exports / types | 212 / 81 | internals still `export`ed; scripts libs not in graph; public API unused in-monorepo |
+| unused dependencies | 62 | Expo autolink / Metro peers Knip cannot see; a few true leftovers |
+| unused devDependencies | 34 | `sinon`, codegen CLIs, types for removed libs |
+| unlisted | 13 | `expo-system-ui` in `app.json`, `jspdf` in metro stubs, optional `ioredis` |
+| binaries / catalog / optional peers | 5 | `eas`, `maestro`, catalog `@sentry/react-native` |
+
+## Non-Goals
+
+- Shrinking published `@terreno/*` public APIs (package `index` re-exports stay).
+- Deleting Expo native, autolink, or Metro packages because Knip cannot see them.
+- Running `knip --fix`.
+- Changing dependency-cruiser rules except regenerating its baseline if a deleted file is listed there.
+- Rewriting Biome or hook wiring.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Knip baseline when done? | None. Survivors live only in `knip.jsonc`. |
+| Unused published exports | Unexport or delete symbols **not** on the public package entry. Ignore leftover public API in `knip.jsonc`. |
+| Expo / native `dependencies` Knip cannot see | `ignoreDependencies` / ignore globs with a reason. Do not remove from `package.json`. |
+| Dead in-repo app/demo code | Delete or stop exporting when nothing in-repo uses it. Keep (then ignore as an entry) only what docs, E2E, or codegen still invoke. |
+| Shape | One IP. Tasks by finding class, not one IP per package. |
+
+## Architecture
+
+Knip has an incomplete **entry graph**. Most “unused files” are tests, isolated suites, Metro stubs, codegen configs, and generated skill copies that are never imported. Fix the graph first so later delete/unexport work is not guessing.
+
+```
+knip.jsonc
+  entries     → isolated tests, scripts tests, e2e, codegen, stubs
+  ignore*     → Expo autolink, binaries, public API leftovers
+code          → delete dead files; unexport internal unused symbols
+check:knip    → fail on any finding not handled above
+```
+
+### Disposition rules (Pick must apply in this order)
+
+1. **Entry** — file is executed by Bun/Playwright/Expo/codegen/CI but Knip does not see it. Add `entry` / plugin / workspace config. Do not delete.
+2. **Ignore** — tool-blind (autolink, `app.json` plugins, optional native peers) **or** published public API unused in this monorepo. Add `ignore` / `ignoreDependencies` / `ignoreBinaries` / `ignoreIssues` with a comment naming the reason. Do not delete Expo native deps.
+3. **Unexport** — symbol is `export`ed from an internal module and is not on the package public entry. Drop `export` or move to a non-exported binding.
+4. **Delete** — file or dependency unused after (1)–(3), including in-repo-dead example/demo hooks and leftover `devDependencies` such as `sinon` once the graph is honest.
+
+Never use `knip --fix`. Delete the old JSON baseline only after the live report is empty.
+
+### Public vs internal export
+
+A symbol is **public** if a published package `src/index.ts` / `src/index.tsx` (or documented extra export path in that package’s `package.json` `exports`) re-exports it. All other unused exports are **internal**.
+
+### Expo / Metro ignore set (starting list; Pick verifies)
+
+Apps (`demo`, `admin-spa`, `example-frontend`) and `ui` declare packages for autolinking, fonts, haptics, pickers, Skia, Metro polyfills (`crypto-browserify`, `stream-browserify`), and `jspdf` stubs. `app.json` / `app.config.ts` name `expo-system-ui` (and similar) without a JS import. Those stay in `package.json` and are ignored in Knip.
+
+## Models
+
+None.
+
+## APIs
+
+None. Operator surface is `knip.jsonc`, `bun run check:knip`, and `bun run analyze:full`.
+
+## Notifications
+
+None.
+
+## UI
+
+None. Example-frontend / demo file deletes must not remove screens still routed or documented. Frontend verification applies only to tasks that delete or unwire UI modules: launch the affected app, exercise the related screen, save artifacts.
+
+## Phases
+
+| Phase | Outcome |
+| --- | --- |
+| 1 Entry graph | Isolated tests, `scripts/**/*.test.ts`, mcp tests, e2e, codegen, Metro stubs, generated skill script copies are entries or ignored globs. Unused-file count drops sharply. |
+| 2 Documented ignores | Expo/autolink deps, binaries (`eas`, `maestro`), unlisted `app.json` plugins, catalog-only packages. |
+| 3 True unused packages | Remove `devDependencies` / dependencies that are unused after the graph is honest (`sinon`, stale `@types/*`, etc.). |
+| 4 Dead files | Delete in-repo-dead modules (example hooks, unused stories, unused scripts). |
+| 5 Internal exports | Unexport unused internals. Ignore remaining public unused exports/types. |
+| 6 Contract | Live Knip report empty. Delete the baseline. Rewrite the enforcement docs. |
+
+Keep the existing fat baseline until Phase 6, then delete it once the live report is empty.
+
+## Feature Flags & Migrations
+
+None.
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- Teaching Knip Expo autolinking for real (upstream / custom compiler).
+- Publishing previously unused public exports with in-repo callers (out of scope; ignore is enough).
+
+## Files to Create / Modify
+
+| File | Role |
+| --- | --- |
+| `knip.jsonc` | Entries, ignores, workspace plugin fixes |
+| `scripts/static-analysis/knip-baseline.json` | Delete after reaching zero findings |
+| `scripts/static-analysis/full.ts` / `lib.test.ts` | Enforce zero findings directly |
+| `docs/explanation/static-analysis.md` | Policy: no Knip baseline; ignore vs delete |
+| Package `package.json` files | Remove true unused deps only |
+| Dead source files listed by live Knip after Phase 1 | Delete or unexport |
+
+## Task List
+
+[`docs/tasks/knip-cleanup.md`](../tasks/knip-cleanup.md)
+
+## Acceptance Criteria
+
+- [ ] `bun run analyze:full` exits 0.
+- [ ] `scripts/static-analysis/knip-baseline.json` does not exist.
+- [ ] Every `ignore` / `ignoreDependencies` / `ignoreBinaries` / `ignoreIssues` entry in `knip.jsonc` has a comment stating why it cannot be a code fix.
+- [ ] No published `@terreno/*` `index` export was removed.
+- [ ] No Expo autolink/native package was removed from an app or `ui` `package.json` solely because Knip flagged it.
+- [ ] `docs/explanation/static-analysis.md` describes the no-baseline policy and forbids `knip --fix`.
+- [ ] `bun test scripts/static-analysis/lib.test.ts` still passes.

package/dist/docs/versioned/next/implementationPlans/mcp-boost-parity.md

@@ -1,6 +1,8 @@
 # Implementation Plan: MCP Server — Boost Parity (Docs Search, Local Runtime Tools, Per-Package Guidelines, Upgrade Prompts)
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1085
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1085  
+**Status:** In progress
+
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 
 ## Overview
@@ -27,7 +29,7 @@ This plan closes the gap with five additions, ordered by value:
 - App console logs are read over the Chrome DevTools Protocol that Metro already exposes (`/json/list` + `/inspector/debug` from `@react-native/dev-middleware`) instead of patching `console` in app code. This is zero-instrumentation and also unlocks `Runtime.evaluate` for the control tools in Phase 6. A POST-to-backend fallback logger covers what CDP can't reach (web browsers when not driven by Playwright, non-dev builds on physical devices).
 - For UI automation we compose existing MCP servers (official `expo-mcp`, Playwright MCP, Maestro) instead of building tap/screenshot tools — that space is mature and Expo now ships it first-party. We only build runtime tools where Terreno has an information advantage: we control store creation (`generateAuthSlice`) and routing conventions, so RTK state inspection and expo-router navigation can be reliable rather than heuristic.
 
-**Related work:** `docs/implementationPlans/model-router-mcp.md` adds MCP tools to consumer apps' own APIs — that is the *app's* MCP surface; this plan is about the *development-time* MCP surface. The companion plan `docs-site-and-versioning.md` covers versioned documentation, which `terreno_search_docs` will consume once it exists.
+**Related work:** `docs/implementationPlans/model-router-mcp.md` adds MCP tools to consumer apps' own APIs — that is the *app's* MCP surface; this plan is about the *development-time* MCP surface. Completing that app surface (prompts, resources, named servers, OAuth, Inspector/test DX, Streamable HTTP client, hosted generators) is [`app-mcp-server.md`](app-mcp-server.md). The companion plan `docs-site-and-versioning.md` covers versioned documentation, which `terreno_search_docs` will consume once it exists.
 
 ## Phase 1: Docs Search Tools (hosted server)
 

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

@@ -0,0 +1,281 @@
+# Implementation Plan: MCP service tokens
+
+**Status:** Approved  
+**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/next/implementationPlans/migrate-admin-to-syncdb.md

@@ -0,0 +1,210 @@
+# Implementation Plan: Migrate built-in admin to syncdb
+
+**Status:** Approved
+**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`.