@terreno/mcp 57.2.0 → 57.3.0

package/src/docs/versioned/next/tasks/mcp-service-tokens.md

@@ -0,0 +1,132 @@
+# Tasks: MCP service tokens
+
+Plan: [`docs/implementationPlans/mcp-service-tokens.md`](../implementationPlans/mcp-service-tokens.md)
+
+**Status:** Approved — all in-scope tasks Roast PASS. **next: brew**.
+
+## Instructions for the implementing agent
+
+- Load `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `update-docs`.
+- Phase 4+: `verify-ui-changes`, `building-admin-interfaces`, `generate-sdk`.
+- TDD: failing test first per task.
+- Run `bun test` in touched packages; `bun run lint` on `api/`, `example-backend/`, `example-frontend/` as applicable.
+- Never log or persist full `mcp_` tokens after the create response.
+- Do not implement OAuth, scopes, or REST bearer for service tokens.
+
+---
+
+### Phase 1: Model and MCP auth
+
+- [x] **Task 1.1**: `McpServiceToken` model + types
+  - Delivers: Mongoose model with issue/verify/revoke/count statics; SHA-256 hash; `mcp_` + 32-byte hex secret; field descriptions on every path
+  - Files: `api/src/models/mcpServiceToken.ts`, `api/src/types/mcpServiceToken.ts`, `api/src/models/mcpServiceToken.test.ts`, `api/src/index.ts`
+  - Blocked by: none
+  - Docs: `docs/reference/api.md` (exported model contract)
+  - Skills: `mongoose-schema-safety`, `terreno-backend-api`
+  - Acceptance: `issueFor` returns plaintext once; `verify` finds active token; respects `revokedAt` and `expiresAt`; `countActiveForUser` correct; duplicate hash impossible
+
+- [x] **Task 1.2**: Service token branch in `extractUserFromHeaders`
+  - Delivers: when `mcpServiceTokens` enabled and bearer starts with `mcp_`, resolve user via model verify; update `lastUsedAt`; order before Better Auth and JWT
+  - Files: `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts`, `api/src/mcp/types.ts` (extend `MCPAuthContext` if needed)
+  - Blocked by: Task 1.1
+  - Docs: none
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Acceptance: valid token resolves owner; revoked/expired/disabled user → undefined; non-`mcp_` bearer still uses existing JWT/session tests unchanged
+
+---
+
+### Phase 2: Self-serve routes and TerrenoApp flag
+
+- [x] **Task 2.1**: `/mcp/service-tokens` HTTP routes
+  - Delivers: POST create (cap 10), GET list (owner), DELETE revoke (owner); OpenAPI via `createOpenApiBuilder`; reject `mcp_` bearer on these routes
+  - Files: `api/src/mcp/serviceTokens.ts`, `api/src/mcp/serviceTokens.test.ts`, `api/src/index.ts`
+  - Blocked by: Task 1.1
+  - Docs: `docs/reference/api.md` (route table)
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: supertest covers happy path, cap, owner isolation, create response includes `mcpUrl` + one-time `token`; list omits hash and plaintext
+
+- [x] **Task 2.2**: `TerrenoAppOptions.mcpServiceTokens`
+  - Delivers: `{enabled, publicMcpUrl?}` or boolean shorthand; mounts routes when enabled; passes flag into `MCPAuthContext`
+  - Files: `api/src/terrenoApp.ts`, `api/src/terrenoApp.test.ts` (or service token integration test)
+  - Blocked by: Task 1.2, Task 2.1
+  - Docs: `docs/reference/api.md` (`TerrenoAppOptions`); `docs/how-to/connect-mcp-service-token.md` (create skeleton)
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: app with flag on serves routes and accepts `mcp_` on `/mcp`; flag off serves neither
+
+- [x] **Task 2.3**: End-to-end MCP call with service token
+  - Delivers: integration test — mint token, `POST /mcp` JSON-RPC `tools/call` with Bearer, assert the same owner-visible result as a session JWT
+  - Files: extend `api/src/mcp/server.test.ts` or `serviceTokens.test.ts`
+  - Blocked by: Task 2.2
+  - Docs: `docs/how-to/connect-mcp-service-token.md` (GET 405 probe + POST `initialize` / `tools/call`)
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: GET `/mcp` returns Streamable-HTTP JSON-RPC 405; POST `tools/call` with `mcp_` acts as the owner; invalid `mcp_` is denied
+
+---
+
+### Phase 3: Example-backend admin
+
+- [x] **Task 3.1**: Enable flag + admin model registration
+  - Delivers: `mcpServiceTokens: {enabled: true, publicMcpUrl: …}` on example `TerrenoApp`; `AdminApp` model entry — listFields, create/update disabled, admin delete → revoke; `responseHandler` strips `tokenHash`
+  - Files: `example-backend/src/server.ts`, `example-backend/src/api/mcpServiceTokensAdmin.ts` (if preDelete hook extracted), `example-backend/src/tests/mcpServiceTokens.admin.test.ts`
+  - Blocked by: Task 2.2
+  - Docs: `example-backend/README.md` (one paragraph + admin path)
+  - Skills: `building-admin-interfaces`, `terreno-backend-api`, `update-docs`
+  - Acceptance: admin user lists tokens for multiple users; revoke removes MCP access; non-admin cannot hit admin routes
+
+---
+
+### Phase 4: Example-frontend settings UI
+
+- [x] **Task 4.1**: SDK codegen for service-token routes
+  - Delivers: regenerated `openApiSdk` hooks for POST/GET/DELETE `/mcp/service-tokens`
+  - Files: `example-frontend/store/openApiSdk.ts` (generated), `example-frontend/openapi-config.ts` (only if path filter needed)
+  - Blocked by: Task 2.1
+  - Skills: `generate-sdk`
+  - Acceptance: TypeScript compiles; hooks callable from settings screen
+
+- [x] **Task 4.2**: `/settings/mcp` screen
+  - Delivers: create form (name, optional expiry), copy-once modal (URL + token + JSON snippet), list with revoke, link from Profile
+  - Files: `example-frontend/app/settings/_layout.tsx`, `example-frontend/app/settings/mcp.tsx`, `example-frontend/app/(tabs)/profile.tsx`
+  - Blocked by: Task 4.1
+  - Docs: none (how-to covers operator steps)
+  - Skills: `terreno-ui`, `verify-ui-changes`
+  - Acceptance: manual test — create, copy snippet, revoke; artifacts in `/opt/cursor/artifacts/`; web on port 8082
+
+---
+
+### Phase 5: Documentation
+
+- [x] **Task 5.1**: Operator docs + cross-links
+  - Delivers: complete `docs/how-to/connect-mcp-service-token.md` (Perplexity form table, JSON snippet, curl); update `docs/how-to/expose-mcp-tools.md` auth section; `docs/explanation/authentication.md` short subsection; note sibling OAuth in `app-mcp-server.md` cross-link only
+  - Files: docs listed above
+  - Blocked by: Task 2.3, Task 4.2
+  - Docs: same files
+  - Skills: `update-docs`
+  - Acceptance: stranger can connect Perplexity from docs alone; `bun run website:build` passes if pages are wired in sidebar
+
+---
+
+## Frontier
+
+Completed: 1.1, 1.2, 2.1, 2.2, 2.3, 3.1, 4.1, 4.2, 5.1. Frontier: none. **next: brew**.
+
+```
+1.1 → 1.2 → 2.2 → 2.3
+1.1 → 2.1 → 2.2
+2.1 → 4.1 → 4.2
+2.2 → 3.1
+2.3 + 4.2 → 5.1
+```
+
+## Acceptance → verification map
+
+| IP criterion | Task(s) |
+| --- | --- |
+| Flag off behavior | 2.2 |
+| Create once / list safe | 2.1 |
+| Cap 10 | 2.1 |
+| Expiry + revoke on `/mcp` | 1.2, 2.3 |
+| Admin all-users revoke | 3.1 |
+| Perplexity GET+POST | 2.3 |
+| Settings UI | 4.2 |
+| Docs | 5.1 |

package/src/docs/versioned/next/tasks/migrate-cicd-to-circleci.md

@@ -98,11 +98,12 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
 
 ## Phase 4: Netlify deploys
 
-- [ ] **Task 4.1**: Port demo / frontend-example / docs Netlify workflows
+- [x] **Task 4.1**: Port demo / frontend-example / docs Netlify workflows
   - Description: Build + `netlify-cli` deploy prod/preview; preserve alias naming (`pr-N`); recreate GitHub Deployment statuses via API if still desired.
   - Files: `.circleci/continue-config.yml`
   - Depends on: Task 0.2, Task 1.3
   - Acceptance: preview deploy URL posted or visible; prod deploy on master path filter.
+  - Note: Path filters and preview jobs exist. Live Netlify still runs on GHA until `terreno-netlify` is filled; CircleCI skips. Cleanup on PR close is GHA `preview-cleanup.yml`.
 
 - [ ] **Task 4.2**: Preview cleanup port
   - Description: On PR close, clean Netlify/GCP preview resources from CircleCI (webhook or GitHub App → pipeline). Prefer OIDC over `GCP_SA_KEY`.
@@ -144,11 +145,12 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Depends on: Task 0.1
   - Acceptance: `gcloud` auth from a CircleCI job succeeds with WIF (no JSON key).
 
-- [ ] **Task 6.2**: Port `cd.yml`
+- [x] **Task 6.2**: Port `cd.yml`
   - Description: Path-filtered terraform fmt/preview/apply + Docker build/push + Cloud Run deploys + mcp-test/deploy. Preserve concurrency semantics (do not cancel in-flight prod applies).
   - Files: `.circleci/continue-config.yml`
   - Depends on: Task 6.1
   - Acceptance: terraform preview on PR; apply+deploy on master for a safe test path; GitHub Deployment records optional but documented.
+  - Note: Path filters exist. Live GCP still runs on GHA until `terreno-gcp` is filled; CircleCI skips apply.
 
 - [ ] **Task 6.3**: Dual-run cutover for CD
   - Description: Single deployer: disable GHA `cd.yml` when CircleCI CD is required; remove GitHub OIDC provider only after GHA CD is gone (or keep read-only if other repos need it — document).
@@ -172,11 +174,11 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
 
 ## Phase 8: Mobile (post-v1, required for CC1)
 
-- [ ] **Task 8.1**: Port Maestro + Appium Android
-  - Description: Port `maestro-e2e` and Android half of `demo-appium-ci` to CircleCI Linux VM with emulator strategy documented.
-  - Files: `.circleci/continue-config.yml`
+- [x] **Task 8.1**: Port Maestro web E2E
+  - Description: Port `maestro-e2e` (Chrome + xvfb against example-frontend, optional demo smokes) to CircleCI `node22_browsers_mongo_rs`. Appium Android remains separate.
+  - Files: `.circleci/continue-config.yml`, `.circleci/config.yml`, `.github/workflows/maestro-e2e.yml`
   - Depends on: Task 5.2
-  - Acceptance: manual pipeline runs Android Appium and Maestro successfully.
+  - Acceptance: CircleCI `maestro-e2e` is the writer; GHA workflow is `on: []`.
 
 - [ ] **Task 8.2**: Port Appium iOS on CircleCI macOS
   - Description: Select macOS resource class/image with Working WDA; port iOS job; compare flake rate to GHA `macos-15`.
@@ -184,6 +186,12 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Depends on: Task 8.1
   - Acceptance: iOS Appium green on a representative run; then delete GHA Appium workflow.
 
+- [ ] **Task 8.3**: Port Appium Android
+  - Description: Linux VM with emulator strategy documented.
+  - Files: `.circleci/continue-config.yml`
+  - Depends on: Task 8.1
+  - Acceptance: Android Appium green on a representative run.
+
 ## Phase 9: GitHub-native + agentic replacements
 
 - [ ] **Task 9.1**: Replace CodeQL workflow
@@ -198,11 +206,17 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Depends on: Task 0.2
   - Acceptance: each former workflow’s acceptance behavior has an owner on CircleCI; GHA files deleted.
 
-- [ ] **Task 9.3**: Replace architectural review + gh-aw agentics
-  - Description: Per lockfile (`update-rules`, `update-docs`, daily improvers) and `architectural-pr-review` / `agentics-maintenance`: either port to CircleCI scheduled/PR pipelines with the same scripts or **retire** with maintainer sign-off. CC1 forbids leaving them on GHA.
-  - Files: `.github/workflows/*lock*`, `architectural-pr-review.yml`, `agentics-maintenance.yml`, `.circleci/continue-config.yml`
+- [x] **Task 9.3a**: Port architectural PR review
+  - Description: CircleCI `architectural-pr-review` runs `.github/scripts/architectural-pr-review.ts` after checking out `origin/master`. Skips forks and missing `CURSOR_API_KEY` / `GITHUB_TOKEN`. GHA workflow is `on: []`.
+  - Files: `.circleci/continue-config.yml`, `.github/workflows/architectural-pr-review.yml`, `.github/scripts/architectural-pr-review.ts`
+  - Depends on: Task 0.2
+  - Acceptance: CircleCI job is the writer; Cursor Approval Agent stays on GitHub.
+
+- [ ] **Task 9.3b**: Replace remaining gh-aw agentics
+  - Description: Per lockfile (`update-rules`, `update-docs`, daily improvers) and `agentics-maintenance`: either port to CircleCI scheduled pipelines or retire with maintainer sign-off.
+  - Files: `.github/workflows/*lock*`, `agentics-maintenance.yml`, `.circleci/continue-config.yml`
   - Depends on: Task 0.2
-  - Acceptance: written retire-or-port decision for each; no gh-aw workflows remain if ported/retired.
+  - Acceptance: written retire-or-port decision for each remaining lock workflow.
 
 ## Phase 10: Cleanup
 

package/src/docs/versioned/next/tasks/password-reset-and-email-verification.md

@@ -4,12 +4,12 @@ IP: [password-reset-and-email-verification](../implementationPlans/password-rese
 
 ## Phase 1 — Token infrastructure
 
-- [ ] **Task 1.1**: `AuthToken` model + issue/consume statics
+- [x] **Task 1.1**: `AuthToken` model + issue/consume statics
   - Description: hashed single-use tokens with TTL expiry per IP
   - Files: `api/src/authTokens.ts`, type files
   - Depends on: none
   - Acceptance: atomic single-use test (parallel consumes → one winner); expiry test
-- [ ] **Task 1.2**: `emailVerificationPlugin`
+- [x] **Task 1.2**: `emailVerificationPlugin`
   - Description: `emailVerified` field plugin for user schemas
   - Files: `api/src/plugins.ts`
   - Depends on: none
@@ -17,17 +17,17 @@ IP: [password-reset-and-email-verification](../implementationPlans/password-rese
 
 ## Phase 2 — JWT routes + mail
 
-- [ ] **Task 2.1**: forgot/reset routes
+- [x] **Task 2.1**: forgot/reset routes
   - Description: 202-always forgot; reset validates+consumes token, `setPassword`, invalidates refresh tokens; RTK client path/shape contract verified
   - Files: `api/src/authRecovery.ts`, `api/src/auth.ts`
   - Depends on: 1.1, comms-abstraction
   - Acceptance: enumeration-safety + happy-path supertest; RTK-shape test
-- [ ] **Task 2.2**: verification routes + `requireEmailVerification` option
+- [x] **Task 2.2**: verification routes + `requireEmailVerification` option
   - Description: sendVerification/verifyEmail; 403 `email-not-verified` gating on login when enabled
   - Files: `api/src/authRecovery.ts`, `api/src/auth.ts`
   - Depends on: 1.2, 2.1
   - Acceptance: gating on/off supertest
-- [ ] **Task 2.3**: Mail templates
+- [x] **Task 2.3**: Mail templates
   - Description: `resetPassword` + `verifyEmail` templates with app-override hook and `publicAppUrl` links
   - Files: `comms/src/templates.ts`
   - Depends on: comms-abstraction Phase 1
@@ -35,7 +35,7 @@ IP: [password-reset-and-email-verification](../implementationPlans/password-rese
 
 ## Phase 3 — Better Auth parity
 
-- [ ] **Task 3.1**: Better Auth hooks
+- [x] **Task 3.1**: Better Auth hooks
   - Description: `sendResetPassword`/`sendVerificationEmail` wired to the same templates
   - Files: `api/src/betterAuthSetup.ts`
   - Depends on: 2.3
@@ -43,17 +43,17 @@ IP: [password-reset-and-email-verification](../implementationPlans/password-rese
 
 ## Phase 4 — Client + docs
 
-- [ ] **Task 4.1**: example-frontend reset screen + verify banner
+- [x] **Task 4.1**: example-frontend reset screen + verify banner
   - Description: `/resetPassword` route + profile banner with re-send; SDK regen
   - Files: `example-frontend/app/resetPassword.tsx`, `app/(tabs)/profile.tsx`, `store/openApiSdk.ts`
   - Depends on: Phase 2
   - Acceptance: end-to-end flow with console adapter; UI verification evidence per verify-ui-changes
-- [ ] **Task 4.2**: `LoginScreen` forgot-password link prop
+- [x] **Task 4.2**: `LoginScreen` forgot-password link prop
   - Description: optional `onForgotPassword` on `@terreno/ui` LoginScreen
   - Files: `ui/src/login/LoginScreen.tsx` + tests + demo story
   - Depends on: none
   - Acceptance: renders only when provided; story added
-- [ ] **Task 4.3**: Docs
+- [x] **Task 4.3**: Docs
   - Description: how-to + env reference + rulesync
   - Files: `docs/how-to/password-reset.md`, `docs/reference/environment-variables.md`, `.rulesync/**`
   - Depends on: Phase 2

package/src/docs/versioned/next/tasks/positioning-django-rails-universal.md

@@ -33,19 +33,19 @@ See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../imple
 
 ## Phase 2: README restructure
 
-- [ ] **Task 2.1**: Restructure the README's opening
+- [x] **Task 2.1**: Restructure the README's opening
   - Description: Rewrite `README.md` above the packages list to this order: title with badges (preserve existing npm badges and the license badge from the governance IP), the `tagline` block as the subtitle, the `elevator` block, the three `pillars`, then a "Quickstart" section, then "Packages". Preserve the existing Vision and Philosophy content but fold it into the pillars rather than repeating it. Per IP question PO5, replace the "Where Terreno is headed" list with a two-line summary linking `ROADMAP.md`.
   - Files: `README.md`
   - Depends on: Task 1.1
   - Acceptance: "Django/Rails for TypeScript" appears within the first two sentences; the pillars appear in the IP's order; the roadmap section is two lines plus a link; no feature claimed that is not shipped.
 
-- [ ] **Task 2.2**: Move maintainer content out of the README
+- [x] **Task 2.2**: Move maintainer content out of the README
   - Description: Move these README sections to their correct homes: local development / bootstrap / linking instructions → `CONTRIBUTING.md`; the "Feature flags: OpenFeature migration" walkthrough → a new or existing page under `docs/how-to/` (check `docs/how-to/add-feature-flags.md` first — it may already cover this, in which case delete the README copy and link it); GCP project names, Cloud Run URLs, and Netlify hosts → `infra/flourish/README.md` (created by [`deploy-to-gcp`](../implementationPlans/deploy-to-gcp.md)) or a short "Live examples" list with URLs only and no infra detail; release instructions → `CONTRIBUTING.md`. After moving, grep the repo and `website/` for links to the removed anchors and fix them.
   - Files: `README.md`, `CONTRIBUTING.md`, `docs/how-to/add-feature-flags.md`, `infra/flourish/README.md`
   - Depends on: Task 2.1
   - Acceptance: `rg -i "flourish-terreno|a\.run\.app|Slack" README.md` returns nothing; no content was deleted without a new home; `bun run website:build` reports no new broken links.
 
-- [ ] **Task 2.3**: `[RTK]` Update the README architecture and package list
+- [x] **Task 2.3**: `[RTK]` Update the README architecture and package list
   - Description: Confirm the architecture diagram and published-package list reflect syncdb (this may already be done by `rtk-to-syncdb-migration-docs` Task 6.5 — check first and skip if so). Ensure every package in `publish-on-tag.yml` appears in the list exactly once with a one-line description matching its `package.json` description.
   - Files: `README.md`
   - Depends on: Task 2.2, `rtk-to-syncdb-migration-docs` Task 6.5
@@ -53,13 +53,13 @@ See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../imple
 
 ## Phase 3: Docs site
 
-- [ ] **Task 3.1**: `[RTK]` Rewrite `docs/README.md`
+- [x] **Task 3.1**: `[RTK]` Rewrite `docs/README.md`
   - Description: Replace the opening line ("shared packages for full-stack applications with React Native and Express/Mongoose") with the `tagline` + `elevator` + `pillars` blocks. Keep the Diátaxis structure section. Rebuild the package table so it contains every published package including `@terreno/ai`, `@terreno/syncdb`, `@terreno/admin-spa`, and `@terreno/feature-flags`, with `rtk` under a Legacy heading. Update the Quick links section: remove the `.cursorrules` link if that file no longer exists, add `positioning.md`, `ROADMAP.md`, and `CONTRIBUTING.md`.
   - Files: `docs/README.md`
   - Depends on: Task 1.1, `rtk-to-syncdb-migration-docs` Task 2.3
   - Acceptance: tagline appears in the first two sentences; package table complete and matching `publish-on-tag.yml`; every Quick link resolves to an existing file.
 
-- [ ] **Task 3.2**: Update the docs site configuration
+- [x] **Task 3.2**: Update the docs site configuration
   - Description: In `website/docusaurus.config.ts`, set `tagline` to the canonical tagline and confirm `title`, `themeConfig.metadata` (og description), and navbar title read consistently. Check whether `website/src/pages/index.tsx` exists; if it does, update the hero to use the tagline, the three pillars, and one short code sample (a `modelRouter` registration plus the matching generated hook usage). If there is no custom landing page, note that in the PR body and skip the hero work.
   - Files: `website/docusaurus.config.ts`, `website/src/pages/index.tsx` (if present)
   - Depends on: Task 1.1
@@ -67,13 +67,13 @@ See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../imple
 
 ## Phase 4: Agent surfaces
 
-- [ ] **Task 4.1**: `[RTK]` Update root agent context files
+- [x] **Task 4.1**: `[RTK]` Update root agent context files
   - Description: In `.rulesync/rules/00-root.md` (the source for `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/00-root.mdc`, and the copilot instructions), replace the opening "A monorepo containing shared packages…" with the `tagline` + `elevator` + `pillars`. Keep all existing conventions content unchanged. Apply the same opening to `CLAUDE-consumer.md`. Then run `bun run rules` and commit every generated mirror. Note: `CLAUDE.local.md` appears to be a stale duplicate of `CLAUDE.md` — verify and either update or delete it, reporting which you chose and why.
   - Files: `.rulesync/rules/00-root.md`, `CLAUDE-consumer.md`, possibly `CLAUDE.local.md`, generated mirrors
   - Depends on: Task 1.1
   - Acceptance: `bun run rules:check` exits 0; `AGENTS.md` and `CLAUDE.md` both open with the positioning; no conventions content was lost (diff review); the `CLAUDE.local.md` decision is explained in the PR body.
 
-- [ ] **Task 4.2**: Update the MCP overview resource
+- [x] **Task 4.2**: Update the MCP overview resource
   - Description: Update `mcp-server/src/docs/resources/overview.md` to open with the positioning blocks so agents reading `terreno://docs/overview` describe Terreno consistently. Check the other resource bundles (`api`, `ui`, `rtk`/`syncdb`, `patterns`) for stale positioning language in their intros and fix those too.
   - Files: `mcp-server/src/docs/resources/*.md`
   - Depends on: Task 4.1
@@ -81,7 +81,7 @@ See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../imple
 
 ## Phase 5: Metadata
 
-- [ ] **Task 5.1**: Standardize `package.json` descriptions
+- [x] **Task 5.1**: Standardize `package.json` descriptions
   - Description: For every package published by `publish-on-tag.yml`, set `description` to the pattern `<what it does> — part of Terreno, the batteries-included TypeScript framework for universal apps.` Keep the first clause specific and accurate per package (do not make them all identical). Also confirm `keywords`, `repository`, `homepage`, and `bugs` fields are present and correct on every published package — missing `repository` fields hurt npm discoverability.
   - Files: every published `package.json`
   - Depends on: Task 1.1
@@ -93,7 +93,7 @@ See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../imple
   - Depends on: Task 1.1
   - Acceptance: the exact description string and full topic list are present and marked as a manual maintainer step.
 
-- [ ] **Task 5.3**: Consistency sweep
+- [x] **Task 5.3**: Consistency sweep
   - Description: Grep the repo for stale positioning language and fix every hit: `rg -n "monorepo containing shared packages"`, `rg -ni "cross-platform"` (should be "universal app" in prose; library-internal technical uses are fine — judge case by case), and `rg -n "88\+ components|90\+ components"` (component counts drift; either verify the number against `ui/src/index.tsx` exports or replace with "a large component library"). Report the count of fixes in the PR body.
   - Files: various
   - Depends on: Task 4.1, Task 3.1

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

@@ -0,0 +1,70 @@
+# Tasks: API rate limiting
+
+IP: [rate-limiting.md](../implementationPlans/rate-limiting.md)  
+**Closes:** https://github.com/FlourishHealth/terreno/issues/1187
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (memory, TerrenoApp)
+
+- [x] **Task 1.1**: Rate-limit module + TerrenoApp mount
+  - Delivers: `rateLimit: {}` on `TerrenoApp` limits HTTP; omitted option is a no-op; `POST /auth/login` uses the auth bucket (20 / 15 min); modelRouter list uses `api` (600 / 15 min); skip `/health` and `/openapi.json`; 429 `APIError` `code: "rate-limit-exceeded"` with `Retry-After` and IETF `RateLimit` / `RateLimit-Policy`; memory store; `trust proxy` default `1` when enabled
+  - Files: `api/src/rateLimit/types.ts`, `api/src/rateLimit/store.ts`, `api/src/rateLimit/memoryStore.ts`, `api/src/rateLimit/policies.ts`, `api/src/rateLimit/middleware.ts`, `api/src/rateLimit/rateLimit.test.ts`, `api/src/terrenoApp.ts`, `api/src/index.ts`, `api/src/api.ts` (remove `TODO add rate limit`)
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `backend-test-env`, `update-docs`
+  - Docs: stub section in `docs/reference/api.md` (`rateLimit` option) so the tracer is documented when it lands
+  - Acceptance: bun tests — default off (burst login no 429); auth 20 then 429; 21st list GET still 200; 601st list 429; `/health` never 429; 429 body/headers; login classified auth
+
+## Phase 2 — Shared stores
+
+- [x] **Task 2.1**: Redis store
+  - Delivers: `store: "redis"` uses `VALKEY_URL` then `REDIS_URL`; missing URL fails startup with a clear `APIError`; consume contract matches memory
+  - Files: `api/src/rateLimit/redisStore.ts`, tests with a fake client; optional skip-if-no-redis integration
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`
+  - Docs: store table in `docs/how-to/rate-limiting.md` (create page if 4.1 not started — Pick may write the Redis rows into the how-to started in 1.1/4.1)
+  - Acceptance: unit tests against the store interface; startup failure without URL
+
+- [x] **Task 2.2**: Mongo store
+  - Delivers: `store: "mongo"` uses the process mongoose connection and `rateLimitHits` with TTL expiry; same consume contract
+  - Files: `api/src/rateLimit/mongoStore.ts` (+ schema/types if a model is used), tests against in-memory Mongo via existing `@terreno/test` harness
+  - Blocked by: 1.1
+  - Skills: `mongoose-schema-safety` (if a Mongoose schema is added), `backend-test-env`
+  - Docs: Mongo collection / TTL note on the how-to
+  - Acceptance: two keys isolated; expiry/window reset; no public modelRouter for hits
+
+## Phase 3 — Paths and proxy
+
+- [x] **Task 3.1**: Auth path table + Better Auth / GitHub
+  - Delivers: GitHub OAuth start/callback on auth bucket; Better Auth `basePath` sign-in/sign-up/forget-password on auth; `/auth/me` on api; extra `skip` callback honored
+  - Files: `api/src/rateLimit/policies.ts`, tests
+  - Blocked by: 1.1
+  - Acceptance: supertest (or middleware unit tests with req.url) for each classified prefix
+
+- [x] **Task 3.2**: Trust-proxy keying
+  - Delivers: with `trustProxy: 1`, `X-Forwarded-For` client IP is the unauthenticated key; `trustProxy: false` ignores spoofed forwarded-for; override hop count works
+  - Files: `api/src/rateLimit/*.ts`, `api/src/terrenoApp.ts`, tests
+  - Blocked by: 1.1
+  - Acceptance: two tests (trust on vs off) with distinct `X-Forwarded-For` values
+
+## Phase 4 — Docs and example
+
+- [x] **Task 4.1**: Diátaxis + changelog + rules
+  - Delivers: operator how-to, reference, auth explanation, env reference (no enable env), replace misleading `RATE_LIMIT_*` snippet in configuration-system, Terreno 58 default-on note, `.rulesync/rules/api/00-api.mdc`, `CHANGELOG.md` Added
+  - Files: `docs/how-to/rate-limiting.md`, `docs/reference/api.md`, `docs/reference/environment-variables.md`, `docs/explanation/authentication.md`, `docs/explanation/configuration-system.md`, `.rulesync/rules/api/00-api.mdc`, `CHANGELOG.md`; `bun run rules` / `skills:sync` if required after rulesync
+  - Blocked by: 1.1 (content can land with 2.x/3.x; must match shipped stores)
+  - Skills: `update-docs`
+  - Acceptance: a stranger can enable Redis on Cloud Run from the how-to; 58 default-on is explicit; `bun run website:build` if docs site is in the slice
+
+- [x] **Task 4.2**: example-backend snippet (limiter stays off)
+  - Delivers: commented `rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined` (or equivalent) showing app-owned env
+  - Files: `example-backend/src/server.ts` (or `index`/`terrenoApp` bootstrap)
+  - Blocked by: 1.1
+  - Acceptance: default example server still has no limiter; comment compiles if uncommented
+
+- [x] **Task 4.3**: Roadmap seed + 58 upgrade stub
+  - Delivers: `docs/explanation/roadmap-seed-issues.md` `rate-limiting` section points at IP/task GitHub URLs and `IP=rate-limiting`; how-to or `mcp-server/src/docs/upgrades/` notes that Terreno 58 defaults the limiter on
+  - Files: `docs/explanation/roadmap-seed-issues.md`; upgrade note path named in how-to until 58 exists
+  - Blocked by: 4.1
+  - Skills: `update-docs`
+  - Acceptance: seed `Implementation plan` / `Tasks` links are not `*(not yet written)*`

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

@@ -0,0 +1,59 @@
+# Task List: Remove legacy RTK realtime in Terreno 58
+
+See: [`docs/implementationPlans/remove-legacy-realtime.md`](../implementationPlans/remove-legacy-realtime.md)
+
+**Target:** Terreno **58.0.0**. Do not execute Phase 2 on the 57.x line.
+
+`RealtimeApp` is **not** in this deletion. It remains the Socket.io / change-stream host for `@terreno/syncdb`.
+
+## Phase 1: Deprecate on 57.x (current)
+
+- [x] **Task 1.1**: Runtime and JSDoc deprecation for `modelRouter` `realtime`
+  - Delivers: one-time `logger.warn` per model/path; `@deprecated` on `ModelRouterOptions.realtime`, `RealtimeConfig`, and `RealtimeEvent`
+  - Files: `api/src/realtime/deprecation.ts`, `api/src/api.ts`, `api/src/realtime/types.ts`, `api/src/realtime/deprecation.test.ts`
+  - Blocked by: none
+  - Acceptance: tests prove one warning per model/path; message names Terreno 58 and `@terreno/syncdb`
+
+- [x] **Task 1.2**: Runtime and JSDoc deprecation for RTK cache-patching helpers
+  - Delivers: one-time `console.warn`; `@deprecated` on `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`, `RealtimeEvent`
+  - Files: `rtk/src/realtime.ts`, `rtk/src/realtime.test.ts`
+  - Blocked by: none
+  - Acceptance: tests prove a single warning across the three helpers; message names Terreno 58 and `@terreno/syncdb`
+
+- [x] **Task 1.3**: Docs, changelog, and agent skills
+  - Delivers: consumers can find the sunset date and replacement without reading source
+  - Files: `docs/reference/api.md`, `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/legacy/rtk.md`, `changelog/unreleased/`, `.rulesync/skills/`
+  - Blocked by: Task 1.1, Task 1.2
+  - Acceptance: docs say `RealtimeApp` stays; `modelRouter` `realtime` and RTK helpers go away in 58
+
+## Phase 2: Delete in Terreno 58
+
+- [ ] **Task 2.1**: Remove `modelRouter` `realtime` registration
+  - Delivers: passing `realtime` is a type error; no `registerRealtime` from `modelRouter`
+  - Files: `api/src/api.ts`, `api/src/realtime/types.ts`, `api/src/realtime/deprecation.ts`, `api/src/index.ts`, `api/src/api.test.ts`
+  - Blocked by: Terreno 58 major
+  - Acceptance: TypeScript and tests fail if a router still passes `realtime`; `sync` registration is unchanged
+
+- [ ] **Task 2.2**: Stop emitting legacy `sync` (RTK) websocket events
+  - Delivers: change streams emit `sync:delta` only for synced models; no RTK `sync` payload
+  - Files: `api/src/realtime/changeStreamWatcher.ts`, `api/src/realtime/realtimeApp.ts`, `api/src/realtime/registry.ts`, related tests
+  - Blocked by: Task 2.1
+  - Acceptance: a model with only `sync` still emits `sync:delta`; no `sync` events for collection CRUD; `admin:model.changed` still works when `admin.realtime` is true
+
+- [ ] **Task 2.3**: Remove `@terreno/rtk` cache-patching helpers
+  - Delivers: `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket` are gone from the package
+  - Files: `rtk/src/realtime.ts`, `rtk/src/realtime.test.ts`, `rtk/src/index.ts`, `rtk/README.md`
+  - Blocked by: Task 2.1
+  - Acceptance: package compile fails if those symbols are imported; `useSocketConnection` still exists
+
+- [ ] **Task 2.4**: Remove example and bootstrap usage
+  - Delivers: example-backend/example-frontend/MCP bootstrap do not configure RTK realtime
+  - Files: `example-backend/src/api/todos.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/_layout.tsx`, MCP bootstrap templates
+  - Blocked by: Task 2.3
+  - Acceptance: todos stay on `sync` + syncdb; `setRealtimeSocket` / `realtimeList` / `realtimeDocument` are gone; `RealtimeApp` remains registered
+
+- [ ] **Task 2.5**: Docs, skills, changelog, 58.0.0 upgrade note
+  - Delivers: upgrade note lists every removed symbol and the syncdb replacement
+  - Files: `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/api.md`, `.rulesync/skills/terreno-data-fetching/references/realtime.md`, `.rulesync/skills/terreno-backend-api/references/model-router.md`, `mcp-server/src/docs/upgrades/58.0.0.md`, changelog
+  - Blocked by: Task 2.4
+  - Acceptance: `bun run check:changelog` passes for 58.0.0; upgrade note exists; no skill tells agents to set `modelRouter` `realtime` for collection CRUD

package/src/docs/versioned/next/tasks/ui-performance.md

@@ -0,0 +1,134 @@
+# Task List: UI Render and Startup Performance
+
+**Feature profile:** true
+
+## Durable contract
+
+- **Destination:** `@terreno/ui` avoids unnecessary render, parse, and layout work on common app
+  paths without changing visible output, interactions, accessibility, or public root imports.
+- **Completed foundation:** P0 primitives and theme work landed in PR #1131. P1 table-update,
+  icon-update, and package-subpath work is covered by `bun run performance:p1` and
+  `docs/reference/ui-performance.md`.
+- **Scope:** the remaining static-audit priorities below, in priority order. Each optimization must
+  add a representative example renderer or import workload, capture a same-machine baseline, and
+  add behavior regression coverage before production code changes.
+- **Non-goals:** visual redesigns, public API removals, root-barrel removal, or benchmark-driven
+  changes without a measured improvement.
+- **Decisions:** keep `@terreno/ui` root imports supported; use Luxon for date work; preserve
+  React Native Web; treat changed-prop/theme work as required behavior rather than overhead to hide.
+- **Tracer:** one real demo story and one benchmark workload per task, exercised before and after
+  the optimization.
+- **Verification seam:** focused Bun regressions, `bun run ui:test`, `bun run lint`,
+  `bun run compile`, the relevant performance script, and a running demo video.
+
+## Instructions for the implementing agent
+
+- Work one task per PR. Do not combine unrelated hot paths.
+- Add regression coverage and record the baseline before changing production code.
+- Report initial, equivalent-prop, and changed-prop medians. Startup tasks must use fresh-process or
+  bundle-graph measurements so module caches do not invalidate the comparison.
+- A faster result with changed output, lost keyboard behavior, stale theme data, or stale layout is
+  a failure.
+- Update `docs/reference/ui-performance.md` with the final same-machine measurements.
+
+### Phase 1: Finish omitted and deferred high-priority work
+
+- [x] **Task 1.1**: Stabilize `OpenAPIProvider` context values (leftover P0)
+  - Delivers: unrelated parent renders no longer fan out through unchanged OpenAPI model metadata.
+  - Files: `ui/src/OpenAPIContext.tsx`, focused regression tests, `ui/benchmarks/`, `ui/package.json`,
+    `docs/reference/ui-performance.md`
+  - Blocked by: none
+  - Acceptance: benchmark an example tree with many OpenAPI consumers; memoize provider actions and
+    value with complete dependencies; unchanged metadata skips consumer renders; replacing the spec
+    updates field lookups immediately; existing form/admin behavior and the full UI suite pass.
+
+- [x] **Task 1.2**: Virtualize large `DataTable` row sets without changing table behavior
+  - Delivers: initial mount cost and mounted row count scale with the viewport instead of total rows.
+  - Files: `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`, P1 regressions and benchmark,
+    `demo/stories/DataTable.stories.tsx`, `docs/reference/ui-performance.md`
+  - Blocked by: none
+  - Acceptance: benchmark at least 1,000 rows with pinned and unpinned columns; mounted rows remain
+    viewport-bounded; sorting, pagination, alternating/highlight colors, custom cells, row test IDs,
+    header/body scroll sync, pinned columns, and row-detail modals match current behavior on web and
+    native; changed rows render correctly after scrolling.
+
+- [ ] **Task 1.3**: Keep optional `DataTable` markdown off the default import path
+  - Delivers: tables without `infoModalText` do not parse or evaluate the markdown renderer.
+  - Files: `ui/src/DataTable.tsx`, a focused header-info component, tests, import benchmark,
+    `docs/reference/ui-performance.md`
+  - Blocked by: Task 1.2
+  - Acceptance: a fresh-process or bundle-graph measurement proves markdown is absent from the
+    default table path; opening header info still renders identical markdown with an explicit
+    loading/error state; table snapshots and interactions remain unchanged.
+
+- [x] **Task 1.4**: Measure and isolate remaining heavy root-import modules
+  - Delivers: startup guidance and lazy boundaries for heavy optional widgets while the root import
+    remains compatible.
+  - Files: `ui/src/index.tsx`, heavy components identified by the measurement, `ui/package.json`,
+    import benchmark, `docs/reference/ui.md`, `docs/reference/ui-performance.md`
+  - Blocked by: none
+  - Acceptance: compare fresh root and subpath imports by evaluated module count, output bytes, and
+    elapsed time; isolate only measured heavy optional paths; `import {Button} from "@terreno/ui"`
+    remains valid; every existing `@terreno/ui/*`, `src/*`, and `dist/*` path still resolves.
+
+- [ ] **Task 1.5**: Decide whether table chrome needs a smaller icon path
+  - Delivers: an evidence-based keep-or-change decision for FontAwesome table chrome.
+  - Files: `ui/src/Icon.tsx`, `ui/src/DataTable.tsx`, icon/import benchmarks, tests,
+    `docs/reference/ui-performance.md`
+  - Blocked by: Task 1.3
+  - Acceptance: measure current glyph import and render cost first; if a smaller path materially
+    improves it, preserve icon names, sizes, weights, colors, custom-icon precedence, font loading,
+    and accessibility; otherwise make no production change and record the measured no-change
+    decision.
+
+### Phase 2: P2 component hot paths
+
+- [ ] **Task 2.1**: Stabilize `DateTimeField` sheet identity and cold platform paths
+  - Delivers: rerenders retain the same sheet ref, and unused desktop/mobile date-picker paths stay
+    cold.
+  - Files: `ui/src/DateTimeField.tsx`, date-time sheet modules, tests, benchmark/example renderer,
+    `docs/reference/ui-performance.md`
+  - Blocked by: Task 1.4
+  - Acceptance: replace render-time `createRef` with a stable ref; benchmark closed and open states;
+    date, time, datetime, timezone, validation, open/close, and imperative behavior match on web and
+    native; first-open loading and import failures have tested states.
+
+- [ ] **Task 2.2**: Load emoji data only when `EmojiSelector` opens
+  - Delivers: apps that do not open the selector avoid parsing `emoji-datasource`.
+  - Files: `ui/src/EmojiSelector.tsx`, tests, import benchmark/example renderer,
+    `docs/reference/ui-performance.md`
+  - Blocked by: Task 1.4
+  - Acceptance: fresh-process or bundle-graph results prove emoji data is absent before open;
+    first open has tested loading/error states; search, categories, selection, skin-tone behavior,
+    reopen behavior, and web/native rendering remain unchanged.
+
+- [x] **Task 2.3**: Stabilize plain and confirmation `Button` render paths
+  - Delivers: debounce identity and plain-button renders stay stable without weakening duplicate
+    submission protection.
+  - Files: `ui/src/Button.tsx`, button tests, benchmark/example renderer,
+    `docs/reference/ui-performance.md`
+  - Blocked by: none
+  - Acceptance: equivalent props skip avoidable work; plain buttons do not allocate confirmation
+    state or load the modal path; rapid presses, delayed handlers, unmount cleanup, loading,
+    disabled, keyboard, haptic, and confirmation behavior match current tests and running stories.
+
+- [x] **Task 2.4**: Replace synchronous responsive dimension reads with reactive breakpoints
+  - Delivers: responsive `Box` props read one shared window state and update correctly on rotation
+    and resize.
+  - Files: `ui/src/MediaQuery.ts`, `ui/src/Box.tsx`, provider/hook files if needed, tests,
+    benchmark/example renderer, `docs/reference/ui-performance.md`
+  - Blocked by: none
+  - Acceptance: benchmark a large responsive `Box` tree; remove per-box synchronous
+    `Dimensions.get` calls; native `sm`/`md`/`lg`/`xl` (320/375/600/1024) and web `lg`/`xl`
+    (1024/1280) boundaries match the product spec; resize, rotation, SSR hydration, web, and
+    native behavior have regressions and running-demo proof.
+
+- [ ] **Task 2.5**: Close the measured hot-style allocation backlog
+  - Delivers: only proven hot leaves reuse style objects without stale theme values.
+  - Files: measured hotspots in `DataTable`, `Button`, `Modal`, `Filter`, `Text`, or `Box`; focused
+    tests and benchmarks; `docs/reference/ui-performance.md`
+  - Blocked by: Tasks 1.2, 2.3, 2.4
+  - Acceptance: profile first and list the selected hotspots; cache styles with every theme/layout
+    dependency represented; equivalent renders improve measurably; changed themes, dimensions,
+    highlights, disabled states, and animations remain visually identical; do not perform a
+    library-wide style rewrite.