@terreno/mcp 58.0.0 → 58.0.2

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

@@ -0,0 +1,249 @@
+# Implementation Plan: MCP Server — Boost Parity (Docs Search, Local Runtime Tools, Per-Package Guidelines, Upgrade Prompts)
+
+**Roadmap issue:** https://github.com/TerrenoLabs/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
+
+[laravel/boost](https://github.com/laravel/boost) is Laravel's MCP server for AI-assisted development. Its value comes from runtime context: it runs *inside* each app (stdio) and gives agents database schema, logs, last error, browser console output, and version-aware doc search. Terreno's MCP server is the opposite shape — a hosted, stateless codegen/docs service with no visibility into the consuming app.
+
+This plan closes the gap with five additions, ordered by value:
+
+1. **Docs search tools** on the hosted server (`terreno_search_docs`, `terreno_get_component_docs`) — agents call tools; they rarely read passive MCP resources.
+2. **A local stdio companion** (`@terreno/mcp`, `terreno-mcp-local` bin) that runs inside consumer apps and exposes runtime introspection: package versions, Mongo schema, read-only queries, backend logs, last error.
+3. **Unified log capture (backend + app + bundler)** — one `read_logs` tool merging backend winston logs, the running app's console output (read over Chrome DevTools Protocol from Metro — no app code changes), Metro build errors, and a POST-based fallback logger for cases CDP can't reach. Boost's most original feature, and arguably more valuable for React Native where agents can't see the simulator.
+4. **Per-package guidelines and skills** — move AI guideline content out of the monolithic `mcp-server/src/bootstrap.ts` (~2,900 lines) into each package's `.ai/` directory, composed at build time and shipped in published npm packages.
+5. **Upgrade prompts** — per-release upgrade notes plus a `terreno_upgrade` prompt. Frontend/Expo SDK work delegates to the official [`upgrading-expo` skill](https://github.com/expo/skills/tree/main/plugins/expo/skills/upgrading-expo) from `expo/skills`; the prompt handles the Terreno-specific parts (`@terreno/ui`, `@terreno/rtk`, `@terreno/api`).
+6. **Simulator/web app control** — compose existing MCP servers (official `expo-mcp` for simulator tap/screenshot, Playwright MCP for web, Maestro for E2E flows) via bootstrap wiring rather than building UI automation ourselves, and add a small set of Terreno-differentiated runtime tools (RTK state inspection, expo-router navigation, opt-in JS evaluate) over CDP. See the ecosystem survey in Phase 6.
+
+**Key design decisions:**
+
+- The hosted server stays stateless and unauthenticated; everything project-specific lives in the new local stdio server.
+- `mcp-server` becomes a published package (`@terreno/mcp`) so consumers can run `bunx terreno-mcp-local` — it joins the nine lockstep-versioned packages in `publish-on-tag.yml`.
+- Search is in-process BM25 (e.g. `minisearch`) over markdown chunked by heading — no external search service, works on Cloud Run with the index built at startup from bundled docs.
+- The local server never imports consumer code. It reads `package.json`/`bun.lock`, connects to Mongo via the consumer's `.env`, and tails log files. This avoids version conflicts between the MCP's dependencies and the app's.
+- Mongo query tool is read-only by allowlist (`find`, `aggregate` without `$out`/`$merge`, `countDocuments`, `distinct`), mirroring Boost's SQL allowlist.
+- Log tools require `@terreno/api` to gain an opt-out dev-only file transport (`.terreno/logs/app.log`) since the winston logger is currently console-only (`api/src/logger.ts`).
+- 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. 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)
+
+### New files
+
+```
+mcp-server/src/search/
+├── chunker.ts      # Split markdown into heading-level chunks with breadcrumb titles
+├── index.ts        # Build minisearch index at startup from docs dir
+└── search.ts       # Query API: multi-query, score merge, token-limited markdown output
+```
+
+### Tools (added in `mcp-server/src/tools.ts`)
+
+```typescript
+terreno_search_docs({
+  queries: string[];      // multiple queries, like Boost ("toggle" vs "switch")
+  packages?: string[];    // filter to @terreno/api, @terreno/ui, etc.
+  tokenLimit?: number;    // default 3000, capped
+})
+// Returns ranked markdown chunks with source attribution.
+
+terreno_get_component_docs({
+  component: string;      // e.g. "Button"
+})
+// Returns the full props table for one @terreno/ui component from
+// ui-types-documentation.json, plus any matching markdown docs.
+```
+
+### Corpus
+
+- `mcp-server/src/docs/resources/*.md` (existing five bundles)
+- `docs/**/*.md` from the monorepo (Diátaxis tree) — extend the `sync-ui-docs` script in `mcp-server/package.json` into a `sync-docs` script that copies both
+- `ui-types-documentation.json` component entries, rendered to markdown chunks (one per component)
+
+### Notes
+
+- Update tool descriptions to instruct agents: "use this tool before guessing at Terreno APIs" (Boost's `search-docs` description does this aggressively and it works).
+- Keep the existing static resources; they cost nothing.
+- Tests in `mcp-server/src/__tests__/search.test.ts`: chunking, ranking sanity ("button" finds Button component), token truncation, package filtering.
+
+## Phase 2: Per-Package Guidelines & Skills
+
+### Structure
+
+Each published package gains an `.ai/` directory:
+
+```
+api/.ai/
+├── guidelines/core.md          # modelRouter, permissions, TerrenoApp patterns
+└── skills/mongoose-schema-safety/SKILL.md   # moved from .rulesync/skills (consumer-relevant parts)
+ui/.ai/guidelines/core.md
+rtk/.ai/guidelines/core.md
+admin-backend/.ai/guidelines/core.md
+...
+```
+
+- Add `.ai` to each package's `files` in `package.json` so guidelines ship to `node_modules` (the Boost pattern: vendor packages carry their own guidelines).
+- `mcp-server` gains a build step (`sync-package-guidelines`) that collects `*/.ai/**` into `src/docs/guidelines/<package>/`.
+
+### Behavior changes
+
+- `terreno_bootstrap_ai_rules` composes its output from the collected per-package files instead of inline strings in `bootstrap.ts`. Add an optional `packages` input (the agent passes the consumer's `@terreno/*` deps from `package.json`) so apps without e.g. `admin-backend` don't get admin guidelines.
+- `bootstrap.ts` shrinks to orchestration + app-scaffold templates; guideline content lives next to the code it describes and is reviewed in the same PRs.
+- The `improve-rulesync` skill should be updated to point contributors at the per-package `.ai/` dirs.
+
+### Versioned guidelines (forward-looking)
+
+Boost keys guidelines by package major version (`.ai/laravel/11/`, `12/`). Terreno releases in lockstep, so a flat `core.md` is fine until a breaking release; at that point add `.ai/guidelines/<major>/core.md` and have the composer pick by the consumer's installed version.
+
+## Phase 3: Local Stdio Companion (`terreno-mcp-local`)
+
+### Packaging
+
+- Rename/publish `mcp-server` as `@terreno/mcp` with two bins:
+  - `terreno-mcp` — existing HTTP entry (`src/index.ts`), unchanged
+  - `terreno-mcp-local` — new stdio entry (`src/local/index.ts`) using `StdioServerTransport`
+- Add to `publish-on-tag.yml` (depends on `publish-api` since it imports the logger).
+- `terreno_bootstrap_app` writes both servers into the generated `.cursor/mcp.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "terreno": { "type": "http", "url": "https://mcp.terreno.app/mcp" },
+    "terreno-local": { "command": "bunx", "args": ["terreno-mcp-local"] }
+  }
+}
+```
+
+### Tools
+
+```
+src/local/tools/
+├── applicationInfo.ts   # application_info
+├── databaseSchema.ts    # database_schema
+├── databaseQuery.ts     # database_query
+├── readLogs.ts          # read_logs, last_error (Phase 4)
+└── runtime.ts           # evaluate, get_rtk_state, navigate (Phase 6, CDP)
+```
+
+- **`application_info`** — parse the consumer's root + workspace `package.json` and `bun.lock`; report `@terreno/*` versions, expo, react-native, mongoose, bun. Tool description copies Boost's trick: *"Use this tool at the start of each chat and write version-specific code."*
+- **`database_schema`** — connect using `MONGO_URI` from the consumer backend's `.env`; list collections, indexes, and document counts; additionally parse `backend/src/models/*.ts` (static, no imports) to report declared fields, types, refs, and plugins. Summary mode + name filter, like Boost.
+- **`database_query`** — read-only allowlist: `find`, `aggregate` (rejecting `$out`/`$merge`/`$function`), `countDocuments`, `distinct`. Hard result cap (default 50 docs), JSON output.
+
+### Required `@terreno/api` change
+
+`api/src/logger.ts` gains a dev-only file transport: when `NODE_ENV !== "production"` (or `TERRENO_LOG_FILE` is set), winston also writes JSONL to `.terreno/logs/app.log` with rotation (cap ~5MB). `.terreno/` is added to the generated app's `.gitignore` by bootstrap.
+
+### Project-root discovery
+
+The local server resolves the consumer project root by walking up from `cwd` to the nearest `package.json` with a `backend`/`frontend` workspace (the bootstrap layout), with a `TERRENO_PROJECT_ROOT` override.
+
+## Phase 4: Unified Log Capture (backend + app + bundler)
+
+One tool instead of Boost's three (`read-log-entries`, `browser-logs`, `last-error` split):
+
+- **`read_logs({ sources?, entries, level?, since? })`** — merges entries chronologically across sources, each tagged with its origin:
+  - `backend` — `.terreno/logs/app.log` JSONL written by the winston file transport (Phase 3), including request logs from `@terreno/api`'s request logging middleware.
+  - `app` — console output from the running native app, captured over CDP (below).
+  - `metro` — bundler build errors (`build_failed`, `bundling_error`) from Metro's `/events` WebSocket.
+  - `browser` — fallback file `.terreno/logs/browser.log` fed by the POST logger (below).
+- **`last_error({ sources? })`** — most recent `error`-level entry with stack across backend and app sources. The agent's first stop after "it broke".
+
+### App console capture via CDP (primary, zero app code)
+
+Metro exposes the Chrome DevTools Protocol through `@react-native/dev-middleware`: `GET /json/list` returns debuggable targets with a `webSocketDebuggerUrl`; attaching and enabling the `Runtime` domain streams `Runtime.consoleAPICalled` events (all console levels, with stack traces, symbolicated via the source map). `terreno-mcp-local` keeps a ring buffer of these events. This is the approach proven by [`metro-mcp`](https://github.com/steve228uk/metro-mcp) and [`expo-metro-mcp`](https://github.com/synnode/expo-metro-mcp).
+
+**Hermes constraint:** Hermes accepts a single CDP debugger connection. Opening React Native DevTools (pressing `j` in Metro) steals it. v1 mitigation: connect lazily, buffer, and release cleanly, with the connection status reported by the tool; if contention proves painful, adopt metro-mcp's CDP-proxy multiplexing approach (or take `metro-mcp` as a dependency) rather than building our own proxy first.
+
+### POST fallback logger (secondary, covers CDP gaps)
+
+CDP reaches dev builds connected to Metro. It does not cover web browsers (when the agent isn't driving them via Playwright, which exposes console messages itself) or device builds not attached to a dev server. For those, a `DevConsoleLogger` module (no-op unless `__DEV__`): patches `console.error`/`console.warn`, registers `ErrorUtils.setGlobalHandler` (native) and `window.onerror` + `unhandledrejection` (web), batches entries to the backend. `TerrenoApp` auto-registers `POST /__terreno/browser-logs` only when `NODE_ENV === "development"`, appending JSONL to `.terreno/logs/browser.log` (route 404s in production). Wired into the bootstrap frontend template; existing apps add one import.
+
+## Phase 5: Upgrade Prompts
+
+### Upgrade notes as release artifacts
+
+- New directory `mcp-server/src/docs/upgrades/<version>.md` — one note per release that has breaking or notable changes (what changed, codemod-style instructions, before/after snippets).
+- Update `.rulesync/skills/release/SKILL.md`: when the release skill flags breaking changes, writing `upgrades/<version>.md` becomes a required step before tagging.
+
+### Prompt and tool
+
+- **Tool `terreno_get_upgrade_guide({ fromVersion, toVersion })`** — concatenates all upgrade notes in the version range (lockstep versioning makes the range unambiguous). Usable by agents without prompt support.
+- **Prompt `terreno_upgrade({ targetVersion? })`** — workflow:
+  1. Determine current `@terreno/*` versions (local `application_info` or `package.json`).
+  2. Call `terreno_get_upgrade_guide` for current → target.
+  3. **Backend:** apply note instructions; bump `@terreno/api`, `@terreno/ai`, etc.; run backend tests.
+  4. **Frontend/Expo:** install and invoke the official `upgrading-expo` skill (`bunx skills add expo/skills` if not present) for the Expo SDK/dependency portion — `npx expo install expo@latest`, `expo install --fix`, `expo-doctor`, cache clearing, breaking-change checklist. Do not duplicate that content in our notes.
+  5. **Terreno frontend:** apply `@terreno/ui` / `@terreno/rtk` note instructions, regenerate the SDK (`generate-sdk` skill), verify with `compile` + lint.
+- `terreno_bootstrap_ai_rules` adds a pointer to `expo/skills` in the generated frontend rules so consumer agents discover `upgrading-expo` organically.
+
+## Phase 6: Simulator & Web App Control
+
+Goal: the agent can drive the running app — tap, type, screenshot, navigate, inspect state — not just read its logs.
+
+### Ecosystem survey (what already exists)
+
+| Project | What it controls | Mechanism | Notes for Terreno |
+|---|---|---|---|
+| [`expo-mcp` (official Expo MCP)](https://docs.expo.dev/eas/ai/mcp/) | Running Expo app in simulator/emulator | Hosted server (`https://mcp.expo.dev/mcp`, OAuth) + local capabilities via `expo-mcp` package and `EXPO_UNSTABLE_MCP_SERVER=1 npx expo start` | `automation_tap` (x/y or `testID`), `automation_take_screenshot` (full or by `testID`), `automation_find_view`, `open_devtools`, `collect_app_logs`, expo-router sitemap; plus hosted docs search and EAS build/log/crash inspection. First-party fit for Terreno apps; flag-gated "unstable", free plan has usage limits on hosted tools |
+| [`microsoft/playwright-mcp`](https://github.com/microsoft/playwright-mcp) | Web app (Expo web export / `expo start --web`) | Accessibility-tree-driven browser automation | The standard for web control; also surfaces browser console messages and network, covering web log capture |
+| [Maestro MCP](https://docs.maestro.dev/get-started/maestro-mcp) (`maestro mcp`, bundled in CLI) | iOS sim, Android emulator, real devices, Chromium | Maestro engine: `list_devices`, `inspect_screen` (view hierarchy), `tap_on`, `input_text`, `run_flow` (YAML), screenshots, embedded device Viewer | Works on compiled apps with no instrumentation; natural bridge from agent exploration to durable E2E flows |
+| [`mobile-next/mobile-mcp`](https://github.com/mobile-next/mobile-mcp) | iOS/Android sims, emulators, and real devices | Accessibility APIs, WebDriverAgent (iOS), ADB/UI Automator (Android) | Framework-agnostic, strongest real-device story; heavier prerequisites (Xcode/Android SDK) |
+| [`steve228uk/metro-mcp`](https://github.com/steve228uk/metro-mcp) | RN runtime via Metro | CDP: console, network, errors, evaluate, Redux state + dispatch, component tree, AsyncStorage, expo-router state, deep links, simulator control, profiler, test recorder; CDP proxy multiplexes Hermes's single connection | Closest existing project to what Phase 4/6 builds; reference implementation, or candidate dependency |
+| [`synnode/expo-metro-mcp`](https://github.com/synnode/expo-metro-mcp), [`jeffdhooton/expo-agent-bridge`](https://github.com/jeffdhooton/expo-agent-bridge) | RN logs/runtime | CDP log buffer + flag-gated `evaluate`; agent-bridge adds an in-app plugin for nav/store/network state | Smaller validations of the same CDP pattern |
+
+### Decision: compose for UI automation, build only Terreno-differentiated runtime tools
+
+**Compose (bootstrap wiring, no new automation code):**
+
+- `terreno_bootstrap_app` adds `expo-mcp` to the frontend dev dependencies, sets `EXPO_UNSTABLE_MCP_SERVER=1` in the generated dev script, and writes the Expo MCP and Playwright MCP entries into the generated `.cursor/mcp.json` alongside the two Terreno servers. Generated AI rules explain which server to use for what (simulator interaction → expo-mcp; web → Playwright; Mongo/logs/codegen → terreno).
+- Generated rules recommend Maestro MCP (opt-in, requires Maestro CLI) when the user asks for E2E tests — the agent explores with expo-mcp, then captures the flow as Maestro YAML via `run_flow`/test generation.
+- `mobile-mcp` documented as the real-device option; not wired by default.
+
+**Build (in `terreno-mcp-local`, reusing the Phase 4 CDP connection):**
+
+- **`evaluate({ code })`** — `Runtime.evaluate` in the app's Hermes runtime. Opt-in via `TERRENO_MCP_EVAL=1`, mirroring Boost's config-gated Tinker tool. Supports async expressions; results JSON-serialized.
+- **`get_rtk_state({ slice?, query? })`** — inspect the Redux store: auth slice, RTK Query cache entries (endpoint, args, status, error), pending mutations. Reliable rather than heuristic because `@terreno/rtk` will expose the store on a dev-only global (`globalThis.__TERRENO_STORE__`, set inside `generateAuthSlice` when `__DEV__`) — this is the small `@terreno/rtk` change this phase needs.
+- **`navigate({ path })`** — expo-router navigation via evaluated `router.push(path)`, plus a deep-link fallback (`xcrun simctl openurl` / `adb shell am start`) when no CDP target is attached. Combined with expo-mcp's screenshot tool, this gives the agent "go to screen X and look at it" in two calls.
+
+### What we deliberately do not build
+
+Tap/swipe/type/screenshot/view-hierarchy tools, device lifecycle management, and test recording — all covered by the composed servers above, with Expo now shipping the core interactions first-party.
+
+## Notifications
+
+None.
+
+## UI
+
+No new UI surfaces. Phase 4 adds the invisible `DevConsoleLogger` fallback to the frontend template; Phase 6 adds a dev-only store global to `@terreno/rtk`.
+
+## Phases & Dependency Order
+
+| Phase | Scope | Depends on |
+|-------|-------|------------|
+| 1. Docs search tools | `mcp-server` only | — |
+| 2. Per-package guidelines | all packages + `mcp-server` | — (parallel with 1) |
+| 3. Local stdio server | `mcp-server` packaging, `@terreno/api` logger | publish pipeline change |
+| 4. Unified logs (backend + app + Metro) | local MCP CDP client, `@terreno/api`, template fallback logger | 3 |
+| 5. Upgrade prompts | `mcp-server`, release skill | 1 (notes searchable), benefits from 3 |
+| 6. App control | bootstrap wiring (`expo-mcp`, Playwright), local MCP runtime tools, `@terreno/rtk` dev global | 4 (shares the CDP connection) |
+
+## Feature Flags & Migrations
+
+- No data migrations.
+- File logging and the browser-logs endpoint are dev-only by environment check, with `TERRENO_LOG_FILE` / `TERRENO_BROWSER_LOGS` env overrides to disable.
+- Publishing `@terreno/mcp` is additive; the hosted Cloud Run deployment is unchanged.
+
+## Risks
+
+- **Read-only enforcement on Mongo** is allowlist-based; `aggregate` stage filtering must be tested against bypass attempts (`$out` nested in `$facet`, etc.).
+- **Local server vs. consumer env drift**: reading `.env` directly can miss values injected by other tooling; document `TERRENO_PROJECT_ROOT` and `MONGO_URI` overrides.
+- **Doc search quality**: BM25 over chunks is keyword-level, not semantic. Acceptable for v1; the docs-site plan's search index is the upgrade path.
+- **Hermes single CDP connection**: the log/runtime tools contend with React Native DevTools for the one debugger slot. Lazy connect/release is the v1 answer; a CDP multiplexing proxy (metro-mcp's approach) is the fallback if contention is a real-world problem.
+- **`expo-mcp` instability**: Expo gates local capabilities behind `EXPO_UNSTABLE_MCP_SERVER=1` and warns the tool list may change; hosted tools meter usage per Expo account (OAuth). Bootstrap wiring should treat it as optional and degrade gracefully.
+- **`evaluate` is arbitrary code execution** in the user's app runtime — opt-in env flag, never enabled by bootstrap defaults, mirroring Boost's Tinker posture.

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

@@ -0,0 +1,216 @@
+# 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
+
+> **Terreno 58 follow-up (done):** the dual-run window closed. `useAdminApi`, admin
+> `injectEndpoints`, and the admin `api` prop were removed (umbrella issue #1252).
+> ObjectId and API-only admin CRUD now use the `AdminProvider` fetch client through
+> `useAdminModelApi`. The plan below is kept as written for history.
+
+## 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/58.0.0/implementationPlans/native-module-baseline.md

@@ -0,0 +1,129 @@
+# Implementation Plan: Native module baseline for the next major release
+
+**Status:** In progress (Phase 1 and diagnostics story landed on `release-58.0.0`; EAS builds pending)
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1026
+**Priority:** High
+**Effort:** Small batch (code) — coordination cost is the release itself
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** decisions D1/D3/D7 (resolved 2026-08-09)
+**RTK deprecation flag:** None
+
+## Goal
+
+Adding a native module to an Expo app invalidates every existing dev-client and store
+binary, so each addition after a release costs consumers a rebuild cycle. This IP lands
+**all** native dependencies the B2B program needs in one breaking (major) release, so every
+subsequent program feature — billing UI, MFA, dark mode, SSO, push, mobile IAP — ships as a
+JS/OTA update against the same binary.
+
+## Non-Goals
+
+- Implementing any feature that uses these modules (their own IPs).
+- Expo SDK version upgrades (separate effort; this IP targets the current SDK).
+- `@10play/tentap-editor` — excluded by decision D3 (markdown stays).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Manifest (D7, resolved) | `@stripe/stripe-react-native`, `react-native-purchases` + `react-native-purchases-ui`, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, `react-native-otp-verify` (dropped at implementation; see below) |
+| Where dependencies live | Root catalog entries; linked in `example-frontend` and `demo` app manifests; `@terreno/ui`/feature packages reference them only when their feature IPs land (this IP is binary readiness, not usage) |
+| Stripe Android constraints | Pin Kotlin 2.x / `compileSdkVersion` via `expo-build-properties` per stripe-react-native requirements. Implemented as Kotlin `2.2.21` (Stripe's default, in Expo's KSP table) and `compileSdkVersion` `37`: React Native 0.88 already compiles against 37, so pinning 36 would downgrade it. Stripe needs at least 36 |
+| Expo Go story | Document which flows degrade in Expo Go (purchases → RevenueCat Preview API mode; stripe/local-auth → dev build required); CI smoke keeps web unaffected |
+| Release process | Follows the `release` skill + the upgrade-notes-for-breaking-releases CI gate (PR #987): major tag, upgrade note required |
+
+## Implementation notes (Terreno 58)
+
+Versions, chosen against Expo SDK 58 (`bundledNativeModules.json` from `expo@58.0.14`):
+
+| Package | Pin | Source |
+| --- | --- | --- |
+| `@stripe/stripe-react-native` | `0.81.0` | Expo 58 bundled version |
+| `react-native-purchases`, `react-native-purchases-ui` | `10.12.2` | Newest release past the 7-day publish cooldown; peers `react-native >= 0.73` |
+| `expo-device` | `~58.0.5` | Expo 58 bundled version |
+| `expo-crypto` | `~58.0.2` | Existing catalog pin, unchanged |
+| `expo-local-authentication` | `~58.0.2` | Expo 58 bundled version |
+| `expo-system-ui` | `~58.0.6` | Expo 58 bundled version |
+| `expo-build-properties` | `~58.0.11` | Expo 58 bundled version |
+
+**Dropped: `react-native-otp-verify`.** `expo-doctor` reports it as unsupported on the New
+Architecture (React Native Directory metadata), and React Native 0.88 runs only the New
+Architecture. The latest release (1.2.0) is a legacy bridge module with no iOS sources. One-time
+codes use `TextInput` `textContentType="oneTimeCode"` (iOS) and `autoComplete="sms-otp"`
+(Android), which need no native module. Android SMS Retriever auto-read needs a New
+Architecture module in a later binary if a feature requires it.
+
+`expo-local-authentication` also gets its config plugin (`faceIDPermission`) so Face ID works
+on iOS without another binary.
+
+## Architecture
+
+Changes are dependency + config only:
+
+1. **Root `package.json` catalog:** add the seven packages (sorted), per the dependency
+   catalog rule (shared by `example-frontend` + `demo`).
+2. **`example-frontend/app.json` + `demo/app.json` plugins:**
+   `@stripe/stripe-react-native` (merchantIdentifier placeholder, `enableGooglePay:
+   true`), `react-native-purchases`, and `expo-build-properties` with the Kotlin/compileSdk
+   pins.
+3. **EAS builds:** refresh dev-client profiles via the existing `eas-dev-build` workflow;
+   verify Android + iOS builds compile with the new pods/gradle deps.
+4. **Upgrade note:** `docs` upgrade note describing the new binary requirement and the
+   consumer checklist (rebuild dev clients, add config plugins, set merchant id when using
+   Stripe).
+
+## Models / APIs / Notifications
+
+None.
+
+## UI
+
+None visible — binary-only change. `demo` gains a hidden diagnostics story listing
+resolved native module versions so builds are verifiable at runtime.
+
+## Phases
+
+1. **Dependencies + config:** catalog entries, app.json plugins, build-properties pins,
+   `bun install` + compile green, web export unaffected.
+2. **Builds + verification:** EAS dev builds for iOS/Android; diagnostics story confirms
+   modules resolve on device; Expo Go degradation documented.
+3. **Release:** upgrade note, coordinate the major tag via the release process.
+
+## Feature Flags & Migrations
+
+None. Runtime behavior is unchanged until feature IPs consume the modules.
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- TenTap (revisit in a later major if WYSIWYG is adopted — decision D3).
+- Any feature wiring of the added modules.
+
+## Files to Create / Modify
+
+- Root `package.json` (catalog), `example-frontend/package.json`, `demo/package.json`
+- `example-frontend/app.json`, `demo/app.json`
+- `demo` diagnostics story
+- `docs/` upgrade note for the major release
+- (No `@terreno/ui` source changes)
+
+## Task List
+
+See [docs/tasks/native-module-baseline.md](../tasks/native-module-baseline.md).
+
+## Acceptance Criteria
+
+- [x] `bun install`, full compile, and `example-frontend` web export succeed with the
+      seven packages added (`react-native-otp-verify` dropped; see Implementation notes).
+- [ ] iOS and Android EAS dev builds compile; the diagnostics story shows all seven
+      modules resolved on device.
+- [ ] Android build carries the Kotlin 2.x / compileSdk 36 pins without breaking
+      gesture-handler or other existing native deps.
+- [ ] Expo Go still launches the app with documented degradations only.
+- [ ] The release PR carries the required upgrade note and the breaking-release CI gate
+      passes.