@terreno/mcp 57.15.0 → 57.16.1

package/src/docs/versioned/57.15.0/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.

package/src/docs/versioned/57.15.0/tasks/unified-mutation-executors.md

@@ -0,0 +1,35 @@
+# Tasks: Unified mutation executors
+
+IP: [unified-mutation-executors.md](../implementationPlans/unified-mutation-executors.md)
+
+## Phase 1 — MCP create → `executeCreate`
+
+- [x] **Task 1.1**: MCP create uses `executeCreate`
+  - Delivers: `handleCreate` calls `executeCreate`; `model.create` gone from create path; MCP error mapping for `APIError`
+  - Files: `api/src/mcp/handlers.ts`, `api/src/mcp/integration.test.ts`, `api/src/sync/executors.test.ts` (only if a shared hook case is missing)
+  - Blocked by: none
+  - Docs: none yet (behavior still MCP-only on create)
+  - Skills: `backend-test-env` if tests touch `process.env`; `update-docs` not required until Phase 3
+  - Acceptance: existing MCP `handleCreate` tests pass; one test proves `preCreate` runs for MCP create; `rg "model.create" api/src/mcp/handlers.ts` is empty on the create path
+
+## Phase 2 — Update and delete
+
+- [x] **Task 2.1**: MCP update uses `executeUpdate`
+  - Delivers: `handleUpdate` adapter only
+  - Files: `api/src/mcp/handlers.ts`, `api/src/mcp/integration.test.ts`
+  - Blocked by: 1.1
+  - Acceptance: MCP update tests pass; no `doc.save()` in `handleUpdate`
+- [x] **Task 2.2**: MCP delete uses `executeDelete`
+  - Delivers: `handleDelete` adapter only (soft-delete semantics from executor)
+  - Files: `api/src/mcp/handlers.ts`, `api/src/mcp/integration.test.ts`
+  - Blocked by: 1.1
+  - Acceptance: MCP delete tests pass; persistence only inside executor
+
+## Phase 3 — Contract and docs
+
+- [x] **Task 3.1**: Docs + changelog
+  - Delivers: explanation/reference match the single write pipeline
+  - Files: `docs/explanation/model-router-actions.md`, `docs/reference/api.md`, `docs/implementationPlans/model-router-mcp.md` (pointer), changelog fragment
+  - Blocked by: 2.1, 2.2
+  - Skills: `update-docs`
+  - Acceptance: a stranger can find “MCP writes use executors” from docs without reading the PR

package/src/docs/versioned/57.15.0/tasks/upgrade-banner.md

@@ -0,0 +1,75 @@
+# Task List: Upgrade Banner
+
+**Status:** Closed (2026-08-20) — IP complete. Shipped via `VersionCheckPlugin`, `AdminVersionConfig`, `useUpgradeCheck`, and `UpgradeRequiredScreen`. Open tasks below were not executed.
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+## Phase 1: Backend + Admin
+
+- [ ] **Task 1.1**: Create VersionConfig Mongoose model
+  - Description: Create the VersionConfig model with schema, interface, and TypeScript types in `@terreno/api`. Fields: webWarningVersion, webRequiredVersion, mobileWarningVersion, mobileRequiredVersion, warningMessage, requiredMessage, updateUrl. All version fields default to 0, messages have sensible defaults.
+  - Files: `api/src/models/versionConfig.ts` (create), `api/src/index.ts` (export)
+  - Depends on: none
+  - Acceptance: Model can be imported from `@terreno/api`, compiles cleanly, schema matches spec
+
+- [ ] **Task 1.2**: Add public `GET /version-check` endpoint
+  - Description: Add a built-in public route via VersionCheckPlugin (TerrenoPlugin) that handles `GET /version-check?version=N&platform=web|mobile`. Fetches the singleton VersionConfig, compares the client's build number against the platform-specific thresholds, and returns a JSON object including status and, when a config exists, version threshold fields: `{status, message?, updateUrl?, requiredVersion?, warningVersion?}`. Returns `{status: "ok"}` if no config document exists.
+  - Files: `api/src/versionCheckPlugin.ts` (create - exports VersionCheckPlugin)
+  - Depends on: Task 1.1
+  - Acceptance: Endpoint returns correct status for all combinations: no config → ok, version >= warning → ok, version < warning → warning, version < required → required. No auth required.
+
+- [ ] **Task 1.3**: Add admin `GET/PUT /admin/version-config` routes
+  - Description: Add admin-only routes for reading and upserting the singleton VersionConfig document. GET returns the current config (or defaults if none exists). PUT upserts the document. Both require `Permissions.IsAdmin`. Wire into AdminApp or as standalone admin routes.
+  - Files: `admin-backend/src/adminApp.ts` (modify) or `api/src/routes/versionCheck.ts` (extend)
+  - Depends on: Task 1.1
+  - Acceptance: Authenticated admin can GET and PUT the config. Non-admin gets 403. PUT creates if not exists, updates if exists.
+
+- [ ] **Task 1.4**: Add admin frontend Version Config screen
+  - Description: Create a custom admin screen in `@terreno/admin-frontend` for editing the singleton VersionConfig. Form with all fields, "Save" button that PUTs to `/admin/version-config`. Add it as a special entry in the admin model list or as a standalone screen.
+  - Files: `admin-frontend/src/AdminVersionConfig.tsx` (create), `admin-frontend/src/index.tsx` (export)
+  - Depends on: Task 1.3
+  - Acceptance: Admin can view and edit all version config fields. Save persists to backend. Form loads existing values on mount.
+
+- [ ] **Task 1.5**: Write unit tests for version check logic
+  - Description: Test the version check endpoint logic: no config returns ok, version comparisons for web and mobile platforms, edge cases (version = 0, version = threshold exactly, missing query params).
+  - Files: `api/src/__tests__/versionCheck.test.ts` (create)
+  - Depends on: Task 1.2
+  - Acceptance: All test cases pass covering ok/warning/required status for both platforms.
+
+- [ ] **Task 1.6**: Wire up example backend
+  - Description: Ensure the example backend includes the VersionConfig model and version-check endpoint. Verify the admin panel shows the version config screen.
+  - Files: `example-backend/src/server.ts` (modify if needed)
+  - Depends on: Task 1.3, Task 1.4
+  - Acceptance: Running the example backend exposes `/version-check` and `/admin/version-config`. Admin panel shows the config screen.
+
+## Phase 2: Client + CI
+
+- [ ] **Task 2.1**: Create `UpgradeRequiredScreen` component
+  - Description: Build a full-screen blocking component in `@terreno/ui`. Centered layout with warning icon, configurable message text, and an "Update" button. The button calls an `onUpdate` callback prop. No dismiss, no navigation escape. Props: `message: string`, `onUpdate: () => void`.
+  - Files: `ui/src/UpgradeRequiredScreen.tsx` (create), `ui/src/index.ts` (export)
+  - Depends on: none
+  - Acceptance: Component renders full-screen with message and button. Button triggers onUpdate. No way to dismiss or navigate away.
+
+- [ ] **Task 2.2**: Create `useUpgradeCheck` hook
+  - Description: Build a hook in `@terreno/rtk` that checks `GET /version-check` on mount. Gets build number from `Constants.expoConfig.extra.buildNumber`, platform from existing `IsWeb` util. On "warning": shows persistent toast with message + "Update" button + dismiss X. On "required": returns `{isRequired: true, requiredMessage, onUpdate}`. The `onUpdate` function handles platform logic: web → `window.location.reload()`, mobile → try `expo-updates` `fetchUpdateAsync()`/`reloadAsync()`, fall back to `Linking.openURL(updateUrl)`. Skips check if build number is undefined.
+  - Files: `rtk/src/useUpgradeCheck.ts` (create), `rtk/src/index.ts` (export)
+  - Depends on: Task 1.2
+  - Acceptance: Hook returns correct state for ok/warning/required. Toast appears for warning. isRequired flag set for required. onUpdate triggers appropriate platform action.
+
+- [ ] **Task 2.3**: Add `app.config.ts` build number injection
+  - Description: Create or update `app.config.ts` in the example frontend to dynamically set `expo.extra.buildNumber` from `git rev-list --count HEAD` at build time. Document the pattern for consuming apps.
+  - Files: `example-frontend/app.config.ts` (create/modify), `example-frontend/app.json` (may need adjustment)
+  - Depends on: none
+  - Acceptance: Running `expo start` or `expo build` sets `Constants.expoConfig.extra.buildNumber` to the current git commit count.
+
+- [ ] **Task 2.4**: Wire up example frontend
+  - Description: Add `useUpgradeCheck()` to the example frontend's root layout. When `isRequired` is true, render `UpgradeRequiredScreen` instead of normal app content.
+  - Files: `example-frontend/app/_layout.tsx` (modify)
+  - Depends on: Task 2.1, Task 2.2, Task 2.3
+  - Acceptance: Example app checks version on mount. Warning shows toast. Required shows blocking screen. Normal operation when version is ok or build number is missing.
+
+- [ ] **Task 2.5**: Document GitHub Actions build number pattern
+  - Description: Add a CI snippet or documentation showing how to inject the build number in GitHub Actions workflows using `git rev-list --count HEAD`. Include examples for both EAS Build and web deployments.
+  - Files: `docs/how-to/upgrade-banner.md` (create) or inline in example-frontend README
+  - Depends on: Task 2.3
+  - Acceptance: Clear instructions for consuming apps to set up automatic build numbering in CI.

package/src/docs/versioned/57.15.0/tasks/upgrade-guides-and-skill.md

@@ -0,0 +1,118 @@
+# Task List: Upgrade Guides and the `upgrading-terreno` Skill
+
+See: [`docs/implementationPlans/upgrade-guides-and-skill.md`](../implementationPlans/upgrade-guides-and-skill.md)
+
+**RTK deprecation flag:** **Blocked.** The RTK → syncdb upgrade is the primary use case for this skill. Do not start until PR #869 merges and [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) Phase 3 has produced the migration guide the skill will delegate to. Tasks marked `[RTK]` specifically handle that migration.
+
+## Instructions for the implementing agent
+
+- Derive upgrade-note content from evidence: `gh release view <tag>`, `git log <prev>..<tag>`, and diffs of public API surfaces (`*/src/index.ts`). Do not write "possibly breaking" — determine whether it breaks by reading the diff.
+- Read `.rulesync/skills/upgrading-expo/SKILL.md` before writing the new skill. Do not duplicate its content; invoke it.
+- The skill must never leave a consumer's repo in a half-upgraded state without saying so. Every failure path must report what succeeded, what failed, and how to roll back.
+- Run `bun run mcp:build` after changing anything under `mcp-server/`. Run `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 1: Note format and backfill
+
+- [x] **Task 1.1**: Define the upgrade note format
+  - Description: Create `mcp-server/src/docs/upgrades/README.md` documenting the required note format from the IP: frontmatter-style header (`Action required`, `Affected packages`) then `Summary`, `Breaking changes` (each with What changed / Why / Migration with before-and-after code), `Deprecations`, `New capabilities`, `Verification`. Explain that notes are concatenated by `terreno_get_upgrade_guide` across a version range, so each must be self-contained and must not assume the reader read an adjacent note. Include a copy-paste template. Read the existing `0.20.0.md` and `0.21.0.md` first and keep the format compatible with them.
+  - Files: `mcp-server/src/docs/upgrades/README.md` (new)
+  - Depends on: none
+  - Acceptance: the format is compatible with the two existing notes; the template includes every required section; the self-contained requirement is stated with its reason.
+
+- [x] **Task 1.2**: Research what changed between 0.21.0 and the current version
+  - Description: For each release from 0.22.0 through the current version, run `gh release view <tag>` and `git log --oneline <prev>..<tag>`, and diff the public surface of each published package (`git diff <prev>..<tag> -- '*/src/index.ts'`). Identify actual breaking changes, deprecations, and notable additions. Record findings per version in the PR body. Pay particular attention to the OpenFeature feature-flag migration, which the README documents as requiring consumer action — that is a breaking change with no upgrade note.
+  - Files: none (findings in the PR body)
+  - Depends on: Task 1.1
+  - Acceptance: every version from 0.22.0 to current is covered; each finding cites a commit or diff; the feature-flag migration is captured.
+
+- [x] **Task 1.3**: Write the consolidated backfill note
+  - Description: Per IP question U1, write a single consolidated note covering 0.21.0 → current (name it for the current version). Include everything from Task 1.2 that requires consumer action, organized by concern rather than by version. Open with an honest note that per-release notes were not maintained for this range and that this note consolidates them. Move the OpenFeature feature-flag migration content out of `README.md` into this note (or into `docs/how-to/add-feature-flags.md`) and link it, rather than leaving a migration guide in the README.
+  - Files: `mcp-server/src/docs/upgrades/<current-version>.md` (new), `README.md`, `docs/how-to/add-feature-flags.md`
+  - Depends on: Task 1.2
+  - Acceptance: every action-requiring change from Task 1.2 appears; the feature-flag migration is no longer in `README.md`; `terreno_get_upgrade_guide` with the range 0.21.0 → current returns this note's content.
+
+- [x] **Task 1.4**: Improve the empty-range response
+  - Description: Update `terreno_get_upgrade_guide` in `mcp-server/src/tools.ts` so that a range with no recorded notes returns an explicit message naming the versions with no notes, rather than empty output — an agent seeing empty output concludes nothing changed, which is the opposite of the truth. Also have it list which versions in the range *did* have notes. Add tests for: range fully covered, range partially covered, range with no notes, and an invalid range.
+  - Files: `mcp-server/src/tools.ts`, tests under `mcp-server/src/`
+  - Depends on: Task 1.3
+  - Acceptance: all four test cases pass; the no-notes response names the specific versions; `bun run mcp:build` succeeds.
+
+## Phase 2: Versioning policy
+
+- [x] **Task 2.1**: Write `docs/explanation/versioning-policy.md`
+  - Description: Document: what lockstep versioning means (all `@terreno/*` packages share a version; you upgrade them together and mixing versions is unsupported — verify this claim against `publish-on-tag.yml` and any peer-dependency constraints before asserting it); the pre-1.0 policy (breaking changes may land in minor releases, always with an upgrade note); the deprecation window from IP question U6 (minimum three minor releases, with the RTK deprecation as the worked example); where to find upgrade notes and the changelog; and what 1.0 will mean when it happens (link program question P9). Keep it short and concrete — this document is a promise, so every sentence must be one the team will keep.
+  - Files: `docs/explanation/versioning-policy.md` (new), `docs/explanation/README.md`
+  - Depends on: Task 1.3
+  - Acceptance: the lockstep claim is verified against the publish workflow and peer deps; the deprecation window is a specific number; the RTK deprecation is used as the example; linked from the explanation index.
+
+- [x] **Task 2.2**: `[RTK]` Write `docs/how-to/upgrade-terreno.md`
+  - Description: The human-facing upgrade guide. Cover: checking your current versions; finding the notes for your range (both via `terreno_get_upgrade_guide` and by browsing the notes directory); the correct ordering with the reasoning for each step (backend before frontend because the OpenAPI spec is the contract; Expo before Terreno frontend packages because `@terreno/ui` pins peers against Expo versions — verify both claims); the manual steps for each phase; verification; and rollback. Add a prominent section for the RTK → syncdb upgrade linking `docs/how-to/migrate-rtk-to-syncdb.md` as a larger, separate operation that should not be combined with a routine version bump.
+  - Files: `docs/how-to/upgrade-terreno.md` (new), `docs/how-to/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: both ordering claims verified against source or `package.json` peer deps and cited; the RTK migration is explicitly separated from routine upgrades; rollback steps present.
+
+## Phase 3: The skill
+
+- [x] **Task 3.1**: Author the `upgrading-terreno` skill
+  - Description: Create `.rulesync/skills/upgrading-terreno/SKILL.md`. Frontmatter: `name: upgrading-terreno`, a `description` naming trigger phrases ("upgrade Terreno", "bump @terreno packages", "update to the latest Terreno", "upgrade terreno version"), `targets: ['*']`. Body: Preconditions (clean git tree — refuse to start otherwise; on a branch, not the default branch; tests currently passing so failures are attributable); Determine versions (`application_info` from the local MCP server, or read `package.json` files); Fetch notes (`terreno_get_upgrade_guide`); **Plan and confirm** — print current version, target version, the notes found, the packages affected, and the ordered steps, then stop for confirmation; then the ten-step ordering from the IP with a verification gate between each phase; Expo delegation (invoke the `upgrading-expo` skill at step 6 rather than duplicating it); Failure handling (report what succeeded, what failed, and the rollback command; on a multi-version jump failure, retry version by version to isolate); and a final report. Include an explicit prohibition on continuing past a failed compile or test run.
+  - Files: `.rulesync/skills/upgrading-terreno/SKILL.md` (new)
+  - Depends on: Task 2.2
+  - Acceptance: the clean-tree precondition is a hard refusal, not a warning; the confirmation gate precedes the first mutation; step 6 invokes `upgrading-expo` by name; the failure path names a rollback command; the ordering matches the how-to guide exactly.
+
+- [x] **Task 3.2**: Add the ordering reference
+  - Description: Create `.rulesync/skills/upgrading-terreno/references/ordering.md` containing the dependency reasoning in detail: why backend precedes frontend, why the typed client is regenerated only after the backend is upgraded and running, why Expo precedes `@terreno/ui`, which packages are backend versus frontend (enumerate them from `publish-on-tag.yml`), and what breaks if the order is violated — with the specific symptom for each violation (for example: regenerating the client against an old backend produces a client missing the new routes, which fails at compile time in the consumer's screens).
+  - Files: `.rulesync/skills/upgrading-terreno/references/ordering.md` (new)
+  - Depends on: Task 3.1
+  - Acceptance: every package is classified backend or frontend and the list matches `publish-on-tag.yml`; each ordering rule has a concrete violation symptom.
+
+- [x] **Task 3.3**: `[RTK]` Add the syncdb migration branch
+  - Description: Add a section to the skill for the case where the upgrade range crosses the syncdb release. The skill must detect this (the range includes the syncdb version), stop, and tell the user that this is a platform migration rather than a version bump, pointing at `docs/how-to/migrate-rtk-to-syncdb.md` and offering to perform the routine version bump first and the migration as a separate operation. Do not attempt to automate the full migration inside a version-bump flow.
+  - Files: `.rulesync/skills/upgrading-terreno/SKILL.md`
+  - Depends on: Task 3.1, `rtk-to-syncdb-migration-docs` Phase 3
+  - Acceptance: the skill detects a range crossing the syncdb version and stops with the two-option choice; it does not attempt the data-layer migration automatically.
+
+- [x] **Task 3.4**: Wire the MCP prompt to the skill
+  - Description: Update the `terreno_upgrade` prompt in `mcp-server/src/prompts.ts` so it points at the `upgrading-terreno` skill as the executor, keeping the prompt as the discovery surface for agents without skill support. Ensure the prompt's ordering matches the skill's exactly so the two cannot drift into disagreement — ideally the prompt references the ordering rather than restating it.
+  - Files: `mcp-server/src/prompts.ts`
+  - Depends on: Task 3.1
+  - Acceptance: the prompt names the skill; the two do not state conflicting orderings; `bun run mcp:build` succeeds.
+
+- [x] **Task 3.5**: Generate skill mirrors
+  - Description: Run `bun run rules` and commit all generated files.
+  - Files: generated skill mirrors
+  - Depends on: Task 3.1, Task 3.2, Task 3.3
+  - Acceptance: `bun run rules:check` exits 0; `upgrading-terreno` appears under every configured target directory.
+
+## Phase 4: Enforcement
+
+- [x] **Task 4.1**: Require upgrade notes in the release skill
+  - Description: Add a required step to `.rulesync/skills/release/SKILL.md`: after assembling the changelog section for the release, if it contains a `Breaking`, `Deprecated`, `Removed`, or `Changed` entry, write `mcp-server/src/docs/upgrades/<version>.md` using the template from Task 1.1 before tagging. Reference the note from the changelog section. Regenerate mirrors.
+  - Files: `.rulesync/skills/release/SKILL.md`, generated mirrors
+  - Depends on: Task 1.1
+  - Acceptance: the step lists the four triggering changelog headings; `bun run rules:check` exits 0.
+
+- [x] **Task 4.2**: Add the CI enforcement check
+  - Description: Add a check (script plus a job in `.github/workflows/repo-policies.yml`, or a step in `publish-on-tag.yml` that runs before publishing) that reads the changelog section for the tag being released and fails if it contains a breaking/deprecated/removed/changed entry while `mcp-server/src/docs/upgrades/<version>.md` does not exist. Write it as a Bun TypeScript script with `const` arrow functions and explicit return types, following the repo's script conventions. Include tests for: note present and required, note missing and required, note not required.
+  - Files: `scripts/check-upgrade-notes.ts` (new), `package.json`, `.github/workflows/repo-policies.yml` or `.github/workflows/publish-on-tag.yml`, tests
+  - Depends on: Task 4.1
+  - Acceptance: all three test cases pass; the check fails a simulated release with a breaking changelog entry and no note; `bun run lint` passes.
+
+- [x] **Task 4.3**: Link notes from the changelog
+  - Description: Update `CHANGELOG.md` so each version section with an upgrade note links it. Add a line to the changelog header explaining that upgrade notes live in `mcp-server/src/docs/upgrades/` and are also available through the MCP server's `terreno_get_upgrade_guide` tool.
+  - Files: `CHANGELOG.md`
+  - Depends on: Task 1.3
+  - Acceptance: every version with a note links it; the header explains where notes live and how to fetch them.
+
+## Phase 5: Validation
+
+- [x] **Task 5.1**: Perform a real multi-version upgrade with the skill
+  - Description: Create a consumer app pinned to an older Terreno version (at least two minors behind current — scaffold with `terreno_bootstrap_app` from that version, or check out `example-frontend`/`example-backend` at the older tag into a scratch directory). Run the `upgrading-terreno` skill to bring it to current. Verify: the clean-tree precondition fires when the tree is dirty, the confirmation gate fires, each phase's verification runs, and the app compiles and runs afterward. Record every gap and fix the skill, the notes, or the how-to as appropriate. Capture the transcript and the running upgraded app to `/opt/cursor/artifacts/`.
+  - Files: `.rulesync/skills/upgrading-terreno/SKILL.md`, `mcp-server/src/docs/upgrades/*`, `docs/how-to/upgrade-terreno.md`, generated mirrors
+  - Depends on: Task 3.5, Task 1.3
+  - Acceptance: the upgrade succeeds and the app runs; both gates observed firing; every gap fixed; artifacts captured; `bun run rules:check` exits 0.
+
+- [x] **Task 5.2**: Verify the failure-isolation path
+  - Description: Deliberately create a failing upgrade (for example by pinning a consumer file to an API removed in the range) and confirm the skill stops at the failing phase, names it, reports what succeeded, offers rollback, and — for a multi-version range — retries version by version to isolate the breaking version. Fix the skill if any of those behaviors is missing.
+  - Files: `.rulesync/skills/upgrading-terreno/SKILL.md`, generated mirrors
+  - Depends on: Task 5.1
+  - Acceptance: all four failure behaviors observed in the transcript; the isolation retry correctly identifies the breaking version; `bun run rules:check` exits 0.

package/src/docs/versioned/57.15.0/tutorials/README.md

@@ -0,0 +1,7 @@
+# Tutorials
+
+Learning-oriented, hands-on lessons. Start here if you are new to Terreno.
+
+## Contents
+
+- [Getting started](getting-started.md) — Scaffold a new app with `create-terreno-app`, run it locally, or explore monorepo examples

package/src/docs/versioned/57.15.0/tutorials/getting-started.md

@@ -0,0 +1,84 @@
+# Getting Started
+
+Create a new Terreno app with the scaffolding CLI, then run it locally.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) installed
+- MongoDB as a **replica set** (required for sync and realtime — see [deployment baseline](../explanation/deployment-baseline.md))
+
+## 1. Scaffold a new app
+
+From an empty parent directory:
+
+```bash
+bunx create-terreno-app my-app --display-name "My App"
+```
+
+npm alternative:
+
+```bash
+npm create terreno-app my-app -- --display-name "My App"
+```
+
+This writes `my-app/backend` and `my-app/frontend` plus deploy and agent config. The CLI does not install dependencies or seed data.
+
+Full flag reference, layout, and deploy notes: [Create a Terreno app](../how-to/create-a-terreno-app.md).
+
+## 2. Install dependencies
+
+```bash
+cd my-app
+(cd backend && bun install)
+(cd frontend && bun install)
+```
+
+## 3. Start MongoDB
+
+Use Atlas or a local single-node replica set. The scaffolded `backend/.env` points at `mongodb://127.0.0.1:27017/my_app?replicaSet=rs0` (database name derived from `appName`).
+Follow [Start MongoDB (replica set)](../how-to/create-a-terreno-app.md#3-start-mongodb-replica-set) for local commands.
+
+## 4. Seed and start the backend
+
+```bash
+(cd backend && bun run seed)
+(cd backend && bun run dev)
+```
+
+Backend runs at `http://localhost:4000`. OpenAPI spec at `/openapi.json`.
+
+Seed users: `test@example.com` and `admin@example.com`, password `testpassword123`.
+
+## 5. Start the frontend
+
+Keep the backend running while generating the SDK.
+
+```bash
+(cd frontend && bun run sdk)
+(cd frontend && bun run web)
+```
+
+Frontend runs at `http://localhost:8082`. Sign in with `test@example.com` / `testpassword123`.
+
+## Explore the Terreno monorepo examples
+
+If you are contributing to Terreno or want reference implementations inside this repository:
+
+```bash
+git clone https://github.com/TerrenoLabs/terreno.git
+cd terreno && bun run bootstrap
+```
+
+| Service | Port | Command (from repo root) |
+| --- | --- | --- |
+| example-backend | 4000 | `bun run backend:dev` |
+| example-frontend web | 8082 | `EXPO_PUBLIC_API_URL=http://localhost:4000 bun run frontend:web` |
+
+The example backend needs `MONGO_URI` (replica set) and auth secrets — see the repository [AGENTS.md](https://github.com/TerrenoLabs/terreno/blob/master/AGENTS.md) (Cursor Cloud section). Seed with `bun run backend:seed` from the repo root.
+
+## Next steps
+
+- [Create a Terreno app](../how-to/create-a-terreno-app.md) — CLI flags, layout, deploy, MCP write path
+- [How to create a model](../how-to/create-a-model.md) — Model conventions including required field descriptions
+- [How-to guides](../how-to/) — Task-focused guides
+- [Reference](../reference/) — Package and API details

package/src/docs/versioned/next/explanation/deployment-architecture-gcp.md

@@ -66,6 +66,15 @@ flowchart TD
 
 Native iOS and Android apps call Cloud Run directly; only the web client uses the CDN origin.
 
+## gcloud quickstart vs Terraform
+
+| Approach | Tradeoff |
+|----------|----------|
+| **gcloud commands** | Fastest first deploy; nothing to install beyond the CLI, but resources drift and are hard to recreate |
+| **`terreno-backend` Terraform module** | Reviewable, repeatable infrastructure for production; adds Terraform state to manage |
+
+With the module, Terraform owns the structure (registry, identities, secrets, service settings) and the deploy step owns the payload (image, env vars, secret mounts). The module ignores image and env changes after creation so the two never fight.
+
 ## Durable jobs and PR isolation
 
 Cloud Tasks is a push service; it does not expose a pull-consumer API. Cloud Run worker

package/src/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -57,7 +57,7 @@ duplicating sprint planning.
 **Title:** `Deploy to GCP (generalized)`
 
 **Labels:** `area:deploy`, `type:docs`  
-**Project fields:** Area=`deploy`, Target=`Next`, Impact=`Improvement`, IP=`deploy-to-gcp`, Status=`Planned`
+**Project fields:** Area=`deploy`, Target=`Next`, Impact=`Improvement`, IP=`deploy-to-gcp`, Status=`In progress`
 
 Turns Terreno's GCP deployment story from Flourish-specific infrastructure into a reusable
 guide any Terreno app can follow. It documents Cloud Run backend hosting, GCS plus CDN for

package/src/docs/versioned/next/how-to/circleci.md

@@ -169,7 +169,7 @@ non-PR branch builds.
 | `example-frontend/**`, `admin-frontend/**`, `rtk/**`, `ui/**`, `ai/**`, `blocks/**`, `syncdb/**`, `bun.lock` | `run-deploy-frontend` | `deploy-frontend-preview` | `deploy-frontend` |
 | `docs/**`, `website/**` | `run-deploy-docs` | `deploy-docs-preview` | `deploy-docs` |
 | `example-backend/**`, `api/**`, `comms/**`, `jobs/**`, `admin-spa/**`, `feature-flags/**`, `announcements/**`, plus every frontend path above | `run-cd-backend` | `gcp-cd-preview` | `gcp-cd-prod` |
-| `terraform/**` | `run-cd-terraform` | `gcp-cd-preview` | `gcp-cd-prod` |
+| `terraform/**`, `infra/**` | `run-cd-terraform` | `gcp-cd-preview` | `gcp-cd-prod` |
 | `mcp-server/**`, `ui/**` | `run-cd-mcp` | _(none)_ | `gcp-cd-prod` (runs `mcp-server` `test:ci` first) |
 
 The backend image bundles the admin SPA (ui, rtk, admin-frontend, syncdb), so
@@ -267,7 +267,7 @@ the `deploy-docs` run that commit starts can unpack the archive under
 
 `terreno-gcp` uses CircleCI OIDC (`CIRCLE_OIDC_TOKEN_V2`), never a JSON service
 account key. Set `circleci_org_id`, `circleci_project_id`, and
-`circleci_gcp_context_id` in `terraform/terraform.tfvars`, apply once with an
+`circleci_gcp_context_id` in `infra/flourish/terraform.tfvars`, apply once with an
 existing Terraform admin identity, then copy `circleci_workload_identity_provider`
 into the context as `GCP_WIF_PROVIDER_PROD`. The WIF condition requires the
 `terreno-gcp` context UUID so a PR job without that context cannot exchange the

package/src/docs/versioned/next/how-to/deploy-backend-to-cloud-run.md

@@ -4,6 +4,8 @@ Deploy a Terreno `@terreno/api` backend (for example `example-backend`) to Googl
 
 Replace placeholders: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$REPOSITORY`.
 
+Steps 1, 3, and 4 create infrastructure with `gcloud`, which suits a first deploy. For production, create the same resources with Terraform instead — see [Manage with Terraform](#manage-with-terraform).
+
 ## Prerequisites
 
 - [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
@@ -97,6 +99,22 @@ curl -s "$SERVICE_URL/health" | jq .
 
 Expect `"healthy": true`.
 
+## Manage with Terraform
+
+The [`terreno-backend` module](https://github.com/TerrenoLabs/terreno/tree/master/terraform/modules/terreno-backend) replaces steps 1, 3, and 4. It creates the Artifact Registry repository, the runtime service account, empty secrets with the names used above, and the Cloud Run service with session affinity, a 3600s timeout, and one minimum instance.
+
+```hcl
+module "backend" {
+  source = "github.com/TerrenoLabs/terreno//terraform/modules/terreno-backend?ref=<release-tag>"
+
+  project_id   = "your-project-id"
+  region       = "us-central1"
+  service_name = "your-service-name"
+}
+```
+
+After `terraform apply`, add a version to **every** secret in the module's `secret_ids` output, including `better-auth-secret` (the module creates it by default; `gcloud run deploy` fails while any mounted secret has no version). Then build, push, and deploy (steps 2 and 5), using the `registry_path`, `service_account_email`, and `set_secrets_flag` outputs. Terraform ignores the image and env vars after creation, so deploys never conflict with `terraform apply`. Set `github_deploy` to add a keyless GitHub Actions deployer through Workload Identity Federation. Leave `--allow-unauthenticated` off in CI deploys: the module already makes the service public, and that flag needs IAM permissions the deployer does not have.
+
 ## Production constraints
 
 | Symptom | Cause | Fix |

package/src/docs/versioned/next/how-to/deploy-to-gcp.md

@@ -18,6 +18,10 @@ Read the [deployment baseline](../explanation/deployment-baseline.md) — seven
 
 [GCP deployment architecture](../explanation/deployment-architecture-gcp.md) — topology diagram, component roles, and tradeoffs (Cloud Run vs GKE, static vs SSR).
 
+## Terraform
+
+- [`terraform/modules/terreno-backend`](https://github.com/TerrenoLabs/terreno/tree/master/terraform/modules/terreno-backend) — Cloud Run, Artifact Registry, secrets, and service accounts for one backend. See [Manage with Terraform](deploy-backend-to-cloud-run.md#manage-with-terraform).
+
 ## Scripts
 
 - [`scripts/setup-gcs-hosting.sh`](https://github.com/TerrenoLabs/terreno/blob/master/scripts/setup-gcs-hosting.sh) — parameterized GCS + CDN provisioning for one site
@@ -28,7 +32,7 @@ Read the [deployment baseline](../explanation/deployment-baseline.md) — seven
 
 ## Operator-specific deployment
 
-Vendor-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives outside these generalized guides. New deployments should follow the guides above with your own `$PROJECT_ID` and bucket names.
+Vendor-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives outside these generalized guides. Terreno's own deployment of its example backend and hosted MCP server is in [`infra/flourish/`](https://github.com/TerrenoLabs/terreno/tree/master/infra/flourish) and is not a template. New deployments should follow the guides above with your own `$PROJECT_ID` and bucket names.
 
 ## Related
 

package/src/docs/versioned/next/implementationPlans/deploy-to-gcp.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Deploy to GCP (Generalized) + `deploy-gcp` Skill
 
-**Status:** Approved — decisions recorded (2026-07-29)
+**Status:** In progress — Phases 1–4 done; Phase 5 (live validation) deferred per GC8
 **Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1005
 **Priority:** High
 **Effort:** Big batch
@@ -34,6 +34,8 @@ Turn Terreno's GCP deployment story from "how Flourish deploys Terreno" into "ho
 | GC5 | Flourish infra location (→ P5) | **C** — `infra/flourish/` now; **migrate to B** (private repo) post-launch |
 | GC6 | `deploy-gcp` skill deploys? | **C** — full deploy behind explicit confirmation gate |
 | GC7 | Secret management | **A** — Secret Manager for secrets; plain env for non-secrets |
+| GC8 | Live scratch-project validation (Tasks 4.1, 4.2) — run now or later? (asked 2026-10-12) | **Later** — ship Tasks 2.1–2.2 first; run 4.1/4.2 in a session with GCP access and a scratch project. Acceptance criteria 4 (module applies to a scratch project) and 8 (full deploy) stay open until then; the module is proven by mocked-provider tests only |
+| GC9 | How does `infra/flourish/` reach the shared modules? | **Stopgap:** an `infra/flourish/modules` symlink to `../../terraform/modules`; CI stages a dereferenced copy because Infra Manager uploads only `--local-source`. When GC5 moves `infra/flourish/` to a private repo, switch module sources to a pinned git source and drop the staging step |
 
 ## Architecture
 
@@ -137,7 +139,9 @@ No product flags. Moving `terraform/` to `infra/flourish/` breaks paths referenc
 - `docs/how-to/deploy-backend-to-cloud-run.md`
 - `docs/how-to/deploy-web-to-gcs-cdn.md`
 - `docs/explanation/deployment-architecture-gcp.md`
-- `terraform/modules/terreno-backend/{main.tf,variables.tf,outputs.tf,README.md}`
+- `terraform/modules/terreno-backend/{main.tf,variables.tf,outputs.tf,versions.tf,README.md}` and `tests/terreno_backend.tftest.hcl`
+- `infra/flourish/**` (moved from `terraform/`, plus the `modules` symlink and README)
+- `terraform/README.md` (generic module index)
 - `.rulesync/skills/deploy-gcp/SKILL.md`
 - `.rulesync/skills/deploy-gcp/references/troubleshooting.md`
 
@@ -146,7 +150,8 @@ No product flags. Moving `terraform/` to `infra/flourish/` breaks paths referenc
 - `docs/how-to/deploy-to-gcp.md` (becomes an index pointing at the two new guides, or is deleted with redirects)
 - `docs/how-to/README.md`
 - `scripts/setup-gcs-hosting.sh` (parameterize)
-- `terraform/README.md` (split generic vs Flourish)
+- `terraform/modules/{cloud_run_service,secret,artifact_registry}` (`session_affinity` input; test-only outputs `runtime_settings`, `accessors`, `writers`)
+- `.circleci/config.yml`, `.circleci/continue-config.yml`, `scripts/ci/gcp-deploy.sh` (infra/ path filter, fmt, module tests, Infra Manager staging)
 - `.github/workflows/cd.yml`, `.github/workflows/demo-deploy.yml`, `.github/workflows/frontend-example-deploy.yml` (path updates if terraform moves)
 - `example-backend/Dockerfile` (created by [`deployment-foundation`](deployment-foundation.md); referenced here)
 
@@ -156,12 +161,12 @@ See [`docs/tasks/deploy-to-gcp.md`](../tasks/deploy-to-gcp.md).
 
 ## Acceptance Criteria
 
-- [ ] `docs/how-to/deploy-backend-to-cloud-run.md` contains no `flourish` string and no hardcoded project ID, bucket name, or service URL.
-- [ ] The backend guide documents session affinity, request timeout, min-instances, and the replica-set requirement, each with the symptom that occurs when it is missed.
-- [ ] The web guide covers `expo export -p web`, bucket configuration with `notFoundPage=index.html`, CDN setup, cache invalidation, and setting `EXPO_PUBLIC_API_URL` at build time.
+- [x] `docs/how-to/deploy-backend-to-cloud-run.md` contains no `flourish` string and no hardcoded project ID, bucket name, or service URL.
+- [x] The backend guide documents session affinity, request timeout, min-instances, and the replica-set requirement, each with the symptom that occurs when it is missed.
+- [x] The web guide covers `expo export -p web`, bucket configuration with `notFoundPage=index.html`, CDN setup, cache invalidation, and setting `EXPO_PUBLIC_API_URL` at build time.
 - [ ] `terraform/modules/terreno-backend/` applies cleanly against a scratch project with only variables supplied, creating Cloud Run + Artifact Registry + secrets + service accounts.
-- [ ] `scripts/setup-gcs-hosting.sh` accepts project and site names as arguments and contains no Flourish defaults.
-- [ ] The `deploy-gcp` skill exists in `.rulesync/skills/` and all generated mirrors are committed (`bun run rules:check` exits 0).
-- [ ] The skill's plan step prints project, region, and service names and stops for confirmation before any mutating command.
+- [x] `scripts/setup-gcs-hosting.sh` accepts project and site names as arguments and contains no Flourish defaults.
+- [x] The `deploy-gcp` skill exists in `.rulesync/skills/` and all generated mirrors are committed (`bun run rules:check` exits 0).
+- [x] The skill's plan step prints project, region, and service names and stops for confirmation before any mutating command.
 - [ ] A full deploy of `example-backend` + `example-frontend` to a scratch GCP project succeeds following only the public docs, and `curl <backend>/health` returns `"healthy":true`.
-- [ ] All Flourish-specific infrastructure lives under `infra/flourish/` and CI still passes.
+- [x] All Flourish-specific infrastructure lives under `infra/flourish/` and CI still passes.