@terreno/mcp 57.2.0 → 57.3.0

package/src/docs/versioned/next/implementationPlans/rate-limiting.md

@@ -0,0 +1,212 @@
+# Implementation Plan: API rate limiting
+
+**Status:** Approved  
+**Branch:** `cursor/api-rate-limiting-d03a`  
+**Owner:** —  
+**Created:** 2026-08-30  
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1187 (this feature **closes** that issue; implementation PRs use `Fixes #1187`)  
+**Task list:** [rate-limiting.md](../tasks/rate-limiting.md)  
+**Depends on:** —  
+**RTK deprecation flag:** None  
+
+## Goal
+
+Opt-in HTTP rate limiting on `TerrenoApp` covering modelRouter and the other framework HTTP surfaces (JWT login/signup/refresh, Better Auth credential routes, GitHub OAuth, admin, AI HTTP, in-process `POST /mcp`, custom OpenAPI routes). Default store is in-process memory. Operators may switch to Redis or Mongo for a shared bucket across replicas. Login uses a stricter `auth` bucket than general CRUD. Terreno **58** flips the default to on (documented now; not this release).
+
+## Non-Goals
+
+- Default-on in this release (Terreno 58).
+- Framework auto-read of `RATE_LIMIT_ENABLED` (apps may pass `process.env` into `rateLimit` themselves).
+- Per-org keys (`org-management-ui` is not shipped).
+- Replacing the existing sync mutation limiter in `api/src/sync/syncBatch.ts` (per-user in-process mutation budget + `rate_limited` nacks).
+- Hosted `@terreno/mcp` JSON-RPC rate limiting (`ai-dev-loop-boost` Task 5.3).
+- example-frontend / `@terreno/rtk` UI for 429.
+- IETF `RateLimit` headers on successful responses.
+- Account lockout / captcha.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Default | **Off.** `rateLimit` omitted or `undefined` → no limiter. Terreno 58 defaults to on; record that in how-to + upgrade notes now. |
+| Enable API | Object only: `rateLimit: { store?, limits?, trustProxy?, skip? }`. Empty `{}` enables defaults. Framework does **not** read an enable env var. |
+| Coverage | Global Express middleware after auth populates `req.user`. Skip `/health`, `/openapi.json`, `/swagger`. Keep sync mutation limiter and realtime subscribe caps as-is. |
+| Key | Authenticated `req.user.id` (or `_id`), else Express `req.ip`. |
+| Auth vs API | `auth`: 20 requests / 15 min. `api`: 600 / 15 min. Overridable via `rateLimit.limits`. |
+| Auth paths | JWT `POST /auth/login`, `/signup`, `/refresh_token`; GitHub OAuth start/callback; Better Auth sign-in/sign-up/forget-password under `basePath` (default `/api/auth`); future password-reset/OTP routes join this list when they land. `/auth/me` is `api`. |
+| Proxy | When limiter is enabled, `app.set("trust proxy", 1)` unless `rateLimit.trustProxy` is set (`false` \| hop count \| IP/subnet list). Key unauthenticated traffic with `req.ip` only — never parse `X-Forwarded-For` / `Forwarded` unless trust proxy is on. |
+| Stores | `memory` (default, per process) \| `redis` (`VALKEY_URL` then `REDIS_URL`, same as realtime) \| `mongo` (app mongoose connection, `rateLimitHits` collection + TTL). |
+| 429 | `APIError` status 429, `code: "rate-limit-exceeded"`, `title: "Too many requests"`. Headers: `Retry-After` plus IETF `RateLimit` / `RateLimit-Policy` (`limit`, `remaining`, `reset`) on the 429 only. |
+| Frontend | No client work this slice. |
+| Tests | Burst tests enable the limiter in-process. Existing suites stay green because default is off. |
+
+## Architecture
+
+```
+TerrenoApp({ rateLimit: { store, limits, trustProxy } })
+  → after JWT / Better Auth session middleware
+  → skip health / openapi / swagger
+  → policy = auth path ? auth : api
+  → key = userId || req.ip
+  → store.consume(key, policy)
+  → next() or APIError 429 + headers
+```
+
+Mount **after** `setupAuth` / Better Auth session so authenticated CRUD shares a user bucket. Login has no user yet → IP key (correct for password spray).
+
+Do not add per-route middleware on each `modelRouter` verb. The `TODO add rate limit` on `GET /` in `api/src/api.ts` is deleted once global middleware exists.
+
+### Config shape
+
+```typescript
+interface RateLimitLimits {
+  windowMs?: number; // default 15 * 60 * 1000
+  authMax?: number;  // default 20
+  apiMax?: number;   // default 600
+}
+
+interface RateLimitOptions {
+  store?: "memory" | "redis" | "mongo";
+  limits?: RateLimitLimits;
+  trustProxy?: boolean | number | string | string[];
+  skip?: (req: Request) => boolean; // extra skips; health/openapi/swagger always skipped
+}
+```
+
+`TerrenoAppOptions.rateLimit?: RateLimitOptions`.
+
+App-owned env example (not implemented inside `@terreno/api`):
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "redis"} : undefined,
+});
+```
+
+### Stores
+
+| Store | When | Semantics |
+|-------|--------|-----------|
+| `memory` | default | Per Node process. Document Cloud Run: N instances = N independent buckets. |
+| `redis` | `store: "redis"` | Optional peer / lazy import matching realtime (`VALKEY_URL` \|\| `REDIS_URL`). Fail startup if URL missing. |
+| `mongo` | `store: "mongo"` | Uses existing mongoose connection. Collection `rateLimitHits` with TTL on window expiry. Not a public modelRouter model. |
+
+Prefer a small `RateLimitStore` interface (`consume({key, max, windowMs}) → {allowed, remaining, resetAt}`) so Redis/Mongo adapters are testable without Express. `express-rate-limit` is allowed if the store interface still holds and 429 goes through `APIError`.
+
+### Skip list (always)
+
+- `GET /health` (and common aliases if already mounted, e.g. `/healthz`)
+- `GET /openapi.json`
+- `/swagger` prefix when Swagger is enabled
+
+Sync HTTP (`POST /sync/mutate`) is **not** skipped: it is `api` bucket HTTP *plus* the existing mutation nack limiter. That is intentional (HTTP flood vs mutation budget).
+
+### Trust proxy
+
+Express `req.ip` is the load-balancer address until `trust proxy` is set. Cloud Run is one hop (GFE). Default `1` when the limiter is on. Operators behind extra proxies set `trustProxy: 2` (or a subnet). `trustProxy: false` keeps the socket address (tests, local). Spoofing `X-Forwarded-For` without trust proxy must not change the key.
+
+## Models
+
+No public CRUD model. Mongo store may use an internal schema (`key`, `hits`, `expiresAt`) with field `description`s if it is a Mongoose model; otherwise a raw collection with a TTL index. Follow `mongoose-schema-safety` if a schema is added. No user-facing migration.
+
+## APIs
+
+| Method | Path | Policy |
+|--------|------|--------|
+| POST | `/auth/login` | auth |
+| POST | `/auth/signup` | auth |
+| POST | `/auth/refresh_token` | auth |
+| GET | `/auth/github`, `/auth/github/callback` | auth |
+| * | `{betterAuth.basePath}/sign-in/*`, `sign-up/*`, `forget-password` | auth |
+| GET/PATCH | `/auth/me` | api |
+| * | modelRouter, admin, AI HTTP, `POST /mcp` | api |
+| GET | `/health`, `/openapi.json` | skip |
+
+429 body is the existing JSONAPI `APIError` serializer (`TooManyRequestsError` name already mapped in `errors.ts`).
+
+## Notifications
+
+None.
+
+## UI
+
+None this slice. example-backend: commented or docs-only snippet showing how to enable; **do not** turn the limiter on in the default example server.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/how-to/rate-limiting.md` | **New.** Enable object, stores, trust proxy, auth vs api numbers, Terreno 58 default-on, memory vs replica warning. |
+| `docs/reference/api.md` | `rateLimit` on `TerrenoApp`; skip list; 429. |
+| `docs/reference/environment-variables.md` | Redis URLs reused; no new required enable env. |
+| `docs/explanation/authentication.md` | Replace “implement rate limiting” with the opt-in `auth` bucket. |
+| `docs/explanation/configuration-system.md` | Replace the fake `RATE_LIMIT_MAX` `express-rate-limit` snippet so it is not the HTTP limiter. |
+| `docs/explanation/roadmap-seed-issues.md` | IP + task URLs for `rate-limiting`. |
+| `mcp-server/src/docs/upgrades/` (next minor or a **58** stub section in how-to) | Default-on when Terreno 58 is cut; this slice documents the promise. |
+| `.rulesync/rules/api/00-api.mdc` | `rateLimit` option. |
+| `CHANGELOG.md` | Added opt-in rate limiting. |
+
+## Testing
+
+Tracer: `TerrenoApp` with `rateLimit: {}` → 21st `POST /auth/login` in 15 min → 429 + headers; 21st list GET still allowed until 601.
+
+Cases:
+
+- Default off: 100 logins succeed (no 429).
+- Auth bucket: 20 allowed, 21st 429; `api` still has remaining.
+- API bucket: 600 allowed, 601st 429 on a modelRouter list.
+- Skip: `/health` never 429.
+- Authenticated user: two IPs, same user, share `api` budget.
+- Unauthenticated: two users behind one IP share `auth` login budget.
+- `trustProxy: 1` + `X-Forwarded-For`: key is client IP; without trust proxy, spoofed header ignored.
+- Memory store isolation between keys.
+- Redis/Mongo: unit tests with fake store; optional integration if env present, skip otherwise.
+- Existing `api/` suite unchanged with limiter off.
+
+Skills: `backend-test-env` if any test mutates env (Redis URL). `mongoose-schema-safety` if Mongo store uses a schema.
+
+## Risks
+
+| Risk | Mitigation |
+|-------|-----------|
+| Default-on later breaks burst tests | 58 upgrade note + test helper `disableRateLimit` or omit option; current tests stay off. |
+| Memory store on Cloud Run | Docs: shared store required for a global bucket. |
+| Trust proxy spoofing | Never honor forwarded headers unless `trust proxy` is set. |
+| Auth path drift (Better Auth) | Central path table + tests against default `basePath`; configurable extra prefixes. |
+| Double limit with sync mutate | Documented; HTTP `api` + mutation nack are different units. |
+
+## Phases
+
+1. Store interface + memory + 429 + skip + auth/api classification + TerrenoApp mount (tracer).
+2. Redis + Mongo adapters.
+3. Trust-proxy tests + GitHub/Better Auth path coverage.
+4. Docs, changelog, rulesync, example-backend snippet, seed-issue links.
+
+## Files to Create / Modify
+
+| File | Role |
+|------|--------|
+| `api/src/rateLimit/*.ts` | Options, middleware, stores, path tables |
+| `api/src/terrenoApp.ts` | `rateLimit` option + mount + trust proxy |
+| `api/src/api.ts` | Remove list-GET TODO |
+| `api/src/index.ts` | Export types |
+| `api/src/rateLimit/*.test.ts` | Tracer + cases above |
+| `example-backend/src/server.ts` | Commented enable snippet |
+| Docs listed above | Same slice |
+
+## Task List
+
+[docs/tasks/rate-limiting.md](../tasks/rate-limiting.md)
+
+## Acceptance Criteria
+
+- [ ] Limiter off by default; existing `bun run api:test` does not 429 from this feature.
+- [ ] `rateLimit: {}` enforces auth 20 / api 600 per 15 min with documented keys.
+- [ ] `POST /auth/login` is on the auth bucket.
+- [ ] Redis and Mongo stores implement the same consume contract.
+- [ ] Trust proxy 1 + `req.ip` behind a forwarded-for header; spoofing ignored when trust is off.
+- [ ] 429 is `APIError` with `Retry-After` and `RateLimit` headers.
+- [ ] Docs how-to + reference + auth explanation + Terreno 58 default-on note exist.
+- [ ] Sync mutation limiter behavior unchanged (existing sync tests still pass).
+- [ ] Merging the implementation PR closes https://github.com/FlourishHealth/terreno/issues/1187 (`Fixes #1187`).

package/src/docs/versioned/next/implementationPlans/remove-legacy-realtime.md

@@ -0,0 +1,58 @@
+# Implementation Plan: Remove legacy RTK realtime in Terreno 58
+
+**Status:** Approved  
+**Branch:** `cursor/deprecate-realtime-for-58`  
+**Owner:** unassigned  
+**Created:** 2026-08-25  
+**Target:** Terreno **58.0.0** (breaking)
+
+## Goal
+
+Delete the **legacy RTK cache-patching realtime path** in Terreno 58. Collection live updates go through `@terreno/syncdb` (`sync` on `modelRouter` + `sync:delta`). This IP does **not** remove `RealtimeApp`: that plugin still hosts Socket.io, change streams, and the syncdb socket channel.
+
+The current minor ships deprecation warnings so apps can migrate before 58.
+
+## Non-Goals
+
+- Removing `RealtimeApp`, Socket.io, change streams, or `sync:delta`.
+- Removing `admin.realtime` (admin `admin:model.changed` events).
+- Removing `useSocketConnection` or feature-flag sockets.
+- Unpublishing `@terreno/rtk` (separate RTK deprecation window).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| What is “realtime” here? | `modelRouter` `realtime`, the `sync` event (not `sync:delta`), and `@terreno/rtk` `realtimeList` / `realtimeDocument` / `setRealtimeSocket` / `getRealtimeSocket`. |
+| What stays? | `RealtimeApp`, `SyncApp`, `modelRouter.sync`, admin `realtime` boolean, socket auth, session revalidation. |
+| When is it removed? | Terreno 58.0.0. Deprecation warnings ship on the 57.x line. |
+| Replacement | `@terreno/syncdb` and [migrate-rtk-to-syncdb.md](../how-to/migrate-rtk-to-syncdb.md). |
+
+## Architecture
+
+Today a model can enable both `realtime` (RTK `sync` events + cache patching) and `sync` (`sync:delta` for syncdb). 58 keeps only the syncdb path.
+
+`TerrenoApp({ realtime: true })` / `new RealtimeApp()` stay as the socket host. Do not treat those constructors as deprecated.
+
+## Phases
+
+1. **57.x (this slice):** JSDoc `@deprecated` + one-time runtime warnings; changelog; upgrade-note copy for the next 57.x release; task list for 58.
+2. **58.0.0:** Delete the APIs, registry, client helpers, example wiring, and docs; keep `RealtimeApp` for sync.
+
+## Files to Create / Modify
+
+- `api/src/api.ts`, `api/src/realtime/types.ts`, `api/src/realtime/deprecation.ts` (57.x warnings)
+- `rtk/src/realtime.ts` (57.x warnings)
+- `docs/tasks/remove-legacy-realtime.md` (58 deletion checklist)
+- 58: `api/src/realtime/registry.ts` consumers, change-stream legacy `sync` emit, `rtk/src/realtime.ts`, examples, skills
+
+## Task List
+
+[`docs/tasks/remove-legacy-realtime.md`](../tasks/remove-legacy-realtime.md)
+
+## Acceptance Criteria
+
+- [x] Using `modelRouter` `realtime` logs a one-time warning that names Terreno 58 and syncdb.
+- [x] Using `realtimeList` / `realtimeDocument` / `setRealtimeSocket` logs a one-time warning that names Terreno 58 and syncdb.
+- [x] Task list describes 58 deletion without removing `RealtimeApp`.
+- [ ] Terreno 58 removes the deprecated APIs (later).

package/src/docs/versioned/next/implementationPlans/syncdb-codegen.md

@@ -1,6 +1,6 @@
 # Implementation Plan: @terreno/syncdb-codegen
 
-**Status:** In progress
+**Status:** Complete — shipped as `syncdb/src/codegen` + `terreno-syncdb-codegen`
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1087
 **Branch:** cursor/syncdb-codegen-in-package-746d
 **Owner:**

package/src/docs/versioned/next/implementationPlans/syncdb-local-first.md

@@ -2,7 +2,7 @@
 
 *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.*
 
-**Status:** Shaped, ready for review
+**Status:** Complete
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1081
 **Priority:** High
 **Effort:** Large

package/src/docs/versioned/next/implementationPlans/terreno-langfuse-integration.md

@@ -1,6 +1,10 @@
 # @terreno/langfuse
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1093
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1093  
+**Status:** Approved
+
+> **See also:** Native in-app observability (prompts, traces, evals, experiments, review queue) is specified in [ai-observability.md](./ai-observability.md). This IP remains the **Langfuse Cloud/self-host vendor plugin**. Both plugins may be registered; traces/scores fan out (see that IP).
+
 A TerrenoApp plugin that integrates [Langfuse](https://langfuse.com) into Terreno backends and frontends. Provides prompt management with MongoDB caching, OpenTelemetry tracing, Vercel AI SDK helpers, React hooks, and an admin UI — all wired up via `.install()`.
 
 > **Prerequisite:** This package relies on the new TerrenoApp plugin system (see [PR #149](https://github.com/FlourishHealth/terreno/pull/149)). TerrenoApp must support `.install()` before this package can be used.

package/src/docs/versioned/next/implementationPlans/terreno-syncdb-2.md

@@ -1,6 +1,9 @@
 # SyncDB Hardening Plan (terreno-syncdb-2)
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1081
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1081  
+**Status:** Complete  
+**Parent IP:** [syncdb-local-first.md](syncdb-local-first.md) — this plan hardens that IP and shares its roadmap issue
+
 Implementation plan for hardening PR #869 (`@terreno/syncdb` local-first data layer,
 branch `worktree-ip-syncdb`). This plan is self-contained: it restates each defect,
 the exact fix, the files involved, and the tests that prove it. Work happens on a

package/src/docs/versioned/next/implementationPlans/unified-mutation-executors.md

@@ -0,0 +1,129 @@
+# Unified mutation executors (MCP → executors)
+
+**Status:** Complete — 2026-08-25  
+**Branch:** `cursor/architecture-ips-a7ec`  
+**Owner:** —  
+**Created:** 2026-08-24  
+**Architecture source:** [model-router-actions.md](../explanation/model-router-actions.md), [model-router-mcp.md](model-router-mcp.md), [pluggable-database-sqlite.md](pluggable-database-sqlite.md)  
+**Task list:** [unified-mutation-executors.md](../tasks/unified-mutation-executors.md)  
+**Depends on:** none  
+**Unlocks:** [can-as-permission-seam.md](can-as-permission-seam.md), [collection-registry.md](collection-registry.md)
+
+## Goal
+
+One write pipeline for create, update, and delete. REST and Sync already call `executeCreate` / `executeUpdate` / `executeDelete` in `api/src/sync/executors.ts`. MCP `handleCreate` / `handleUpdate` / `handleDelete` in `api/src/mcp/handlers.ts` still run permissions, transformers, hooks, and `model.create` / `doc.save` themselves.
+
+When this ships, MCP write tools call those executors. A permission, hook, field-view, or soft-delete fix lands once.
+
+## Non-Goals
+
+- List/read unification (MCP list/read stay handlers; they are not duplicated against executors).
+- Replacing executors with a new `WriteService` class.
+- Implementing the SQLite `DatabaseAdapter` (executors will later call the adapter; this IP does not introduce it). See [pluggable-database-sqlite.md](pluggable-database-sqlite.md).
+- Changing MCP tool names, JSON-RPC transport, or `excludeFields` config shape.
+- Compiling RBAC `access` away from `PermissionMethod[]` (that is [can-as-permission-seam.md](can-as-permission-seam.md)).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Interface shape | **A — MCP adapters call existing executors.** Not B (a new `WriteService` wrapping both). Smallest interface: three functions already used by REST and Sync. |
+| Error contract | Executors keep throwing `APIError`. MCP maps `APIError` (and hook failures) onto the existing MCP error `textResult` / `errorResult` envelope. No new error type. |
+| Request object | Pass a real Express `req` when HTTP; otherwise the existing executor `{user}` stub via `createMCPRequest` fields (`user`, `body`). Do not invent a second hook request type. |
+| MCP-only behavior | Keep MCP `excludeFields`, `mcpResponseHandler`, and tool-result JSON wrapping in the handler **after** the executor returns `{doc}`. Executors stay transport-agnostic. |
+| `skipPostHooks` | MCP uses the REST path (`skipPostHooks` unset). Sync keeps the ledger-safe skip. |
+| Compatibility | No app-facing API break. MCP tool argument schemas and success JSON `{data}` stay the same. Error **strings** may align to `APIError.title` where they currently diverge; tests that pin MCP wording update in this slice. |
+| Sequencing | Land before collection-registry and can-as-permission-seam so those IPs do not have to touch two write implementations. |
+
+## Interface shapes considered
+
+**A (chosen).** `handleCreate(entry, args, user)` → `executeCreate({model, options: entry.options, user, body, req: mcpStubReq})` → map `{doc}` / `APIError` to `MCPToolResult`.
+
+**B (rejected).** `class MutationService { create; update; delete }` that REST, Sync, and MCP all call. Deletes the executor module only by renaming it; REST already has the deep module.
+
+## Architecture
+
+```
+Before:
+  MCP handlers ──duplicate──► Mongoose + permissions + hooks
+  REST / Sync ──────────────► executors ──► Mongoose
+
+After:
+  MCP ──map args/errors──► executors ◄── REST / Sync
+                              │
+                              ▼
+                           Mongoose (later: DatabaseAdapter)
+```
+
+`executeCreate` already: `checkPermissions` → `transform` → `preCreate` → `model.create` → populate → `postCreate` (unless skipped). MCP `handleCreate` repeats that and calls `model.create` directly (`api/src/mcp/handlers.ts`).
+
+Handler leftover after this IP:
+
+1. Auth / anonymous gate that is MCP-transport specific.
+2. `omitDeniedWriteFields` / MCP `excludeFields` (if not already covered by executor field views — prove with tests; if executor already strips write-denied fields, delete the MCP copy).
+3. Call executor.
+4. `mcpResponseHandler` / `serializeResponse`.
+5. `APIError` → MCP error result.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/explanation/model-router-actions.md` | Writes (CRUD, not named actions) go through executors for REST, Sync, and MCP. |
+| `docs/reference/api.md` (MCP tools) | MCP create/update/delete share REST permission and hook semantics; errors are `APIError` titles. |
+| `docs/implementationPlans/model-router-mcp.md` | Note: write path now executors (status note, not a rewrite of that shipped IP). |
+
+Skip operator how-to: no new env, CLI, or app setup.
+
+## Testing
+
+Public seam: `executeCreate` / `executeUpdate` / `executeDelete` (existing `executors.test.ts`) plus MCP integration tests that assert **behavior** (denied create, preCreate null, hook throw, field omit) against the same fixtures as REST.
+
+Add one MCP test that fails if `handleCreate` uses `model.create` instead of `executeCreate` (spy or shared side-effect: `preCreate` called once with the stub request).
+
+Do not weaken executor tests. MCP tests that duplicate permission matrices can shrink after the adapter is thin.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| MCP error strings differ from `APIError.title` | Golden-file or explicit map in handler; update MCP tests in-slice. |
+| `createMCPRequest` missing Express fields hooks read | Inventory hook usage in `api` tests and example-backend; extend stub only for fields executors already pass on HTTP. |
+| Double field-stripping | Single test: write-denied field absent from DB for both REST and MCP. |
+
+## Phases
+
+1. Map MCP create to `executeCreate`; MCP create tests green and share preCreate/permission behavior with REST.
+2. Map update and delete the same way.
+3. Delete duplicated MCP write bodies; keep transport mapping. Docs + changelog fragment.
+
+## Feature Flags & Migrations
+
+None. Internal call-graph change.
+
+## Not Included / Future Work
+
+- Executor calls `DatabaseAdapter` ([pluggable-database-sqlite.md](pluggable-database-sqlite.md)).
+- MCP list/read through a shared query executor.
+- `access.can()` as the permission engine ([can-as-permission-seam.md](can-as-permission-seam.md)).
+
+## Files to Create / Modify
+
+- `api/src/mcp/handlers.ts` — write handlers become adapters
+- `api/src/mcp/handlers.ts` tests / `api/src/mcp/integration.test.ts`
+- `api/src/sync/executors.ts` — only if a missing hook/request field is required for MCP parity; prefer not
+- Docs listed above
+- Changelog fragment for `@terreno/api`
+
+## Acceptance Criteria
+
+- [ ] MCP create/update/delete call `executeCreate` / `executeUpdate` / `executeDelete`.
+- [ ] MCP write handlers contain no `model.create` / `doc.save` / delete persistence.
+- [ ] A `preCreate` / `preUpdate` / `preDelete` hook runs for MCP the same as REST (existing hook tests or new shared cases).
+- [ ] Permission denial for MCP writes matches executor denial (status/title mapped into MCP error result).
+- [ ] `bun test` in `api` covering `mcp/` and `sync/executors` passes.
+- [ ] Docs in this slice match the shipped call graph.
+
+## Task List
+
+[docs/tasks/unified-mutation-executors.md](../tasks/unified-mutation-executors.md)

package/src/docs/versioned/next/implementationPlans/upgrade-guides-and-skill.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Upgrade Guides and the `upgrading-terreno` Skill
 
-**Status:** Draft — blocked on PR #869
+**Status:** Approved
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1013
 **Priority:** High
 **Effort:** Big batch

package/src/docs/versioned/next/implementationPlans/web-ssr-and-admin-spa.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Server-Side Rendering for Universal Web (and Admin SPA)
 
-**Status:** Draft — blocking questions open
+**Status:** Approved
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1017
 **Priority:** Medium
 **Effort:** Epic

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

@@ -17,17 +17,20 @@ Technical reference for Terreno packages and APIs. Information-oriented, precise
 - [@terreno/mcp](mcp-server.md) — AI coding assistant integration (MCP)
 - [@terreno/test](test.md) — Bun test helpers and in-memory MongoDB
 
-## Migrating from RTK
+## Legacy
 
-`@terreno/rtk` is deprecated for **data synchronization**. New apps should use [`@terreno/syncdb`](syncdb.md). Existing RTK consumers: follow [Migrate from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md). Archived RTK reference: [legacy/rtk.md](legacy/rtk.md).
+`@terreno/rtk` is deprecated for **data synchronization**. New apps should use [`@terreno/syncdb`](syncdb.md). Existing RTK consumers: follow [Migrate from @terreno/rtk to @terreno/syncdb](../how-to/migrate-rtk-to-syncdb.md). Archived RTK reference: [legacy/rtk.md](legacy/rtk.md). `modelRouter` `realtime` and the RTK cache-patching helpers are removed in Terreno 58.
 
 ## Configuration
 
 - [Environment Variables](environment-variables.md) — Complete environment variable reference for all packages
+- [Admin configuration](admin-config.md) — `modelRouter` `admin` object fields
 
 ## Other references
 
+- [UI performance](ui-performance.md) — Component render benchmarks
 - [Lifecycle plugin](lifecycle-plugin.md) — Grow/Pick/Roast/Brew/Taste contracts, results, and transitions
 - [Install agent skills](../how-to/install-agent-skills.md) — Published `skills/` tree for `npx skills`
+- [GitHub issue lifecycle](../how-to/github-issue-lifecycle.md) — Pick-ready issues and Pick plan comments
 - Root [package.json](https://github.com/flourishhealth/terreno/blob/master/package.json) — Workspace scripts and catalog
 - Per-package `package.json` in each package directory — Commands and dependencies

package/src/docs/versioned/next/reference/admin-backend.md

@@ -2,6 +2,9 @@
 
 Backend plugin that auto-generates admin CRUD endpoints for Mongoose models. Works with `@terreno/admin-frontend` to provide a complete admin panel solution.
 
+Screens, sidebar, and host wiring: [How admin interfaces are shaped](../explanation/admin-interface.md)
+and [Build admin screens](../how-to/build-admin-screens.md).
+
 ## Quick Start
 
 ``````typescript
@@ -93,13 +96,15 @@ For each model, creates standard modelRouter CRUD endpoints:
 ``````
 
 Field metadata includes:
-- `type` — Field type (string, number, boolean, date, objectid, etc.)
+- `type` — Field type (string, number, boolean, date, objectid, array, etc.)
 - `required` — Whether field is required
 - `description` — From schema (ensure all fields have descriptions!)
 - `enum` — Enum values if applicable
 - `default` — Default value
 - `ref` — Referenced model name for ObjectId refs
 
+Field metadata is built from `describeModel()` via `modelDescriptionToAdminFields()` — not from a second OpenAPI property walk. Widget overrides (`fieldOverrides`) remain admin-backend configuration.
+
 ## Permissions
 
 `admin:access` is the only permission that opens the admin page. `GET /admin/config` returns 403

package/src/docs/versioned/next/reference/admin-frontend.md

@@ -2,15 +2,21 @@
 
 React Native components for building admin panels that connect to `@terreno/admin-backend`.
 
+**Build a screen or change nav:** [How admin interfaces are shaped](../explanation/admin-interface.md)
+and [Build admin screens](../how-to/build-admin-screens.md).
+
 ## Quick Start
 
+Home is `AdminHome` inside `AdminProvider` + `AdminShellLayout`. Generic models use
+`AdminScreenRouter` on `[model]/index`. See the how-to for `apiBase` vs `routeBase`.
+
 ``````typescript
 // app/admin/index.tsx
-import {AdminModelList} from "@terreno/admin-frontend";
+import {AdminHome} from "@terreno/admin-frontend";
 import {api} from "@/store/openApiSdk";
 
 export default function AdminScreen() {
-  return <AdminModelList baseUrl="/admin" api={api} />;
+  return <AdminHome api={api} apiBase="/admin" routeBase="/admin" />;
 }
 ``````
 
@@ -223,3 +229,35 @@ Expects backend to provide:
 When RBAC is enabled, `/admin/config` is filtered for the current user. `AdminShell` uses its
 `platformTools` flags to hide denied Scripts, Roles, Version, and Configuration links, and only
 renders model or custom-screen links returned by the server.
+
+### Custom screen page chrome
+
+Wrap custom admin screen content in `AdminScreenPage`. It renders the standard `Page` header with a back arrow by default; the arrow navigates to `/admin` via `router.push`, not `router.back()`, because sidebar navigation does not always leave a reliable history entry on web. Pass the host's `routeBase` as `backHref` when admin uses a different prefix; an empty standalone-admin base resolves to `/`. Detail screens can target their parent route (for example `/admin/comms`). Pass `backButton={false}` only when the host supplies equivalent navigation.
+
+```typescript
+import {AdminScreenPage} from "@terreno/admin-frontend";
+
+<AdminScreenPage title="Operations" scroll>
+  <OperationsDashboard />
+</AdminScreenPage>
+```
+
+### Comms dashboard
+
+`COMMS_ADMIN_WIDGETS.comms` is registered in the built-in screen registry. `CommsApp` contributes
+custom screen `name: "comms"`. Hosts should also add message detail routes so `/comms/:id` is not
+handled as a generic model form:
+
+```typescript
+import {CommsDashboardScreenWidget, CommsMessageDetail} from "@terreno/admin-frontend";
+
+// list: /admin/comms
+<CommsDashboardScreenWidget api={api} config={config} routeBase="/admin" screenName="comms" />
+
+// detail: /admin/comms/[id]
+<CommsMessageDetail api={api} messageId={id} routeBase="/admin" />
+```
+
+The list screen persists filters in the URL (`channel`, `provider`, `status`, `errorClass`, `q`,
+`startDate`, `endDate`, `page`) and calls `/comms/messages`, `/comms/stats`, and
+`/comms/messages/retryMany`.

package/src/docs/versioned/next/reference/admin-spa.md

@@ -2,6 +2,9 @@
 
 Standalone Expo Router admin web SPA plus an Express plugin (`AdminSpaServeApp`) that serves the pre-built static export from a Terreno backend on the same origin.
 
+How screens and nav work (including `routeBase=""`): [How admin interfaces are shaped](../explanation/admin-interface.md).
+How to add a screen: [Build admin screens](../how-to/build-admin-screens.md).
+
 ## Table of Contents
 
 - [Install](#install)