@terreno/mcp 57.20.0 → 57.22.0

package/dist/docs/versioned/57.2.0/tasks/org-management-ui.md

@@ -1,107 +0,0 @@
-# Tasks: Organizations as a first-class primitive (admin UI + RBAC)
-
-IP: [org-management-ui](../implementationPlans/org-management-ui.md)
-
-Supporting skills (all tasks): `update-docs`. Models: `mongoose-schema-safety`. API tests: `backend-test-env`. Admin UI: `terreno-ui`, `building-terreno-apps`, `verify-ui-changes`. SDK: `generate-sdk`. Data: `terreno-data-fetching`.
-
-## Phase 1 — Models + context
-
-- [ ] **Task 1.1**: Organization + Membership models
-  - Delivers: persist orgs and per-org `roleName` (`org-admin` \| `member`)
-  - Files: `api/src/orgs/organizationModel.ts`, types, `api/src/orgs/*.test.ts`
-  - Blocked by: none
-  - Docs: field `description`s (OpenAPI); note in `docs/reference/api.md` stub section if the page is updated later in 6.1
-  - Acceptance: unit tests for compound unique index and duplicate membership rejection
-- [ ] **Task 1.2**: `orgScopedPlugin`
-  - Delivers: required indexed `organizationId` on consumer schemas
-  - Files: `api/src/orgs/orgPlugin.ts` + tests
-  - Blocked by: 1.1
-  - Docs: none until 6.1
-  - Acceptance: save without org fails; index present
-- [ ] **Task 1.3**: Org context middleware + `OrgQueryFilter`
-  - Delivers: Q13 header matrix; lists never cross orgs
-  - Files: `api/src/orgs/orgContext.ts`, `orgPermissions.ts`, `api/src/permissions.ts` (stop using `User.organizationIds`)
-  - Blocked by: 1.1, 1.2
-  - Docs: none until 6.1
-  - Acceptance: supertest — operator missing header on scoped list → 400; org-admin of one org omits header → scoped; org A member never reads org B including `$or` / query-param attacks; non-member header → 403
-
-## Phase 2 — RBAC
-
-- [ ] **Task 2.1**: `organization` statements + `operator` role + membership-scoped `org-admin`
-  - Delivers: platform vs org grants as in the IP tables
-  - Files: `api/src/rbac/statements.ts`, `roleModel.ts`, resolve/can path for Membership `roleName`, tests
-  - Blocked by: 1.3
-  - Docs: `docs/reference/api.md` RBAC/org note (or 6.1)
-  - Acceptance: `org-admin` on org A cannot `organization:list` all orgs; `operator` can; `user.roles` containing `org-admin` is not how grants work (test that membership wins)
-
-## Phase 3 — OrgsApp routes
-
-- [ ] **Task 3.1**: Operator org CRUD + `/orgs/mine`
-  - Delivers: create/list-all/mine/read/patch/soft-delete + `onOrgAudit`
-  - Files: `api/src/orgs/orgsApp.ts`, exports, OpenAPI, supertest
-  - Blocked by: 2.1
-  - Docs: none until 6.1
-  - Acceptance: org-admin 403 on `GET /orgs`; operator 200; create does not require membership; disable/soft-delete suspends memberships
-- [ ] **Task 3.2**: Members attach / patch / delete + last-admin guards
-  - Delivers: existing-user attach; no email; last `org-admin` protected
-  - Files: `api/src/orgs/orgsApp.ts` + tests
-  - Blocked by: 3.1
-  - Docs: none until 6.1
-  - Acceptance: attach by email of existing user; unknown email 404; demote last org-admin 400; no comms/send invoked
-
-## Phase 4 — Admin backend
-
-- [ ] **Task 4.1**: Admin org routes + AdminApp tenant context
-  - Delivers: admin UI can call org APIs; generic admin model lists use context filter
-  - Files: `admin-backend/src/*` (org registration or aliases), AdminApp queryFilter/preCreate, tests
-  - Blocked by: 3.2
-  - Docs: `docs/reference/admin-backend.md` org section (may land with 6.1)
-  - Acceptance: operator `/admin` list of an org-scoped model without header → 400; with header → only that org; org-admin cannot hit all-orgs admin list
-
-## Phase 5 — Admin frontend
-
-- [ ] **Task 5.1**: `OrgDirectoryScreen` (operator)
-  - Delivers: all-orgs table, create, disable, enter org
-  - Files: `admin-frontend/src/orgs/OrgDirectoryScreen.tsx` + tests
-  - Blocked by: 4.1
-  - Docs: `docs/reference/admin-frontend.md` component section
-  - Acceptance: loading/error/empty; org-admin nav hidden in unit test via role prop/fixture
-- [ ] **Task 5.2**: `OrgSwitcher` + `useOrgContext` (header + URL)
-  - Delivers: Q10/Q13 client behavior for org-admins and operators-in-org
-  - Files: `admin-frontend/src/orgs/OrgSwitcher.tsx`, `useOrgContext.tsx`, `AdminShellLayout` slot
-  - Blocked by: 5.1
-  - Docs: admin-frontend reference
-  - Acceptance: switching sets `X-Organization-Id` on subsequent admin queries (test with mocked api); single-org org-admin still renders org name
-- [ ] **Task 5.3**: Org settings + members table
-  - Delivers: settings PATCH; members DataTable; add existing user; last-admin error; disabled Invite; billing placeholder
-  - Files: `admin-frontend/src/orgs/OrgSettingsScreen.tsx`, `OrgMembersScreen.tsx` + tests
-  - Blocked by: 5.2, 3.2
-  - Docs: admin-frontend reference
-  - Acceptance: Invite control disabled; billing placeholder visible; last-admin error shown
-- [ ] **Task 5.4**: Host wiring — admin-spa + example-frontend `/admin`
-  - Delivers: routes on both hosts; SDK regen
-  - Files: `admin-spa/app/orgs/*`, `example-frontend/app/admin/orgs/*`, `example-frontend/store/openApiSdk.ts` (generated)
-  - Blocked by: 5.3
-  - Docs: `docs/reference/admin-spa.md` nav entry
-  - Acceptance: `cd example-frontend && bun run sdk` compiles; both apps have `/admin/orgs` routes
-- [ ] **Task 5.5**: Frontend verification
-  - Delivers: evidence org-admin vs operator flows
-  - Files: `/opt/cursor/artifacts/` (not in repo)
-  - Blocked by: 5.4, 6.2
-  - Docs: none
-  - Acceptance: login operator → directory → create/open org → members; login org-admin → no directory → switcher → members only that org; screenshots/video on the PR (`verify-ui-changes`)
-
-## Phase 6 — Example + docs
-
-- [ ] **Task 6.1**: Docs (same slice as behavior; can land incrementally but must be complete before Brew)
-  - Delivers: stranger can operate orgs from docs
-  - Files: `docs/how-to/add-organizations.md`, `docs/explanation/organizations.md`, `docs/reference/api.md`, `docs/reference/admin-backend.md`, `docs/reference/admin-frontend.md`, `docs/reference/admin-spa.md`, `.rulesync/**` if agent rules need org context
-  - Blocked by: 4.1 (content must match shipped routes)
-  - Docs: (this task)
-  - Acceptance: `bun run website:build` (or package docs check used in CI); how-to has one minimal OrgsApp + AdminApp example
-- [ ] **Task 6.2**: example-backend migration + seeds
-  - Delivers: Membership instead of `User.organizationIds`; operator + two org-admins
-  - Files: `example-backend/src/models/user.ts`, `types/models/userTypes.ts`, `api/projects.ts`, `scripts/seed-*`, `access.ts`, `rbacRoles.ts`, tests
-  - Blocked by: 3.2, 2.1
-  - Docs: seed users named in `docs/how-to/add-organizations.md`
-  - Acceptance: grep finds no `organizationIds` on User; isolation tests pass; seed creates operator@example.com

package/dist/docs/versioned/57.2.0/tasks/password-reset-and-email-verification.md

@@ -1,60 +0,0 @@
-# Tasks: Password reset and email verification
-
-IP: [password-reset-and-email-verification](../implementationPlans/password-reset-and-email-verification.md)
-
-## Phase 1 — Token infrastructure
-
-- [ ] **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`
-  - Description: `emailVerified` field plugin for user schemas
-  - Files: `api/src/plugins.ts`
-  - Depends on: none
-  - Acceptance: plugin test; example User adopts it
-
-## Phase 2 — JWT routes + mail
-
-- [ ] **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
-  - 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
-  - Description: `resetPassword` + `verifyEmail` templates with app-override hook and `publicAppUrl` links
-  - Files: `comms/src/templates.ts`
-  - Depends on: comms-abstraction Phase 1
-  - Acceptance: rendered output snapshot tests
-
-## Phase 3 — Better Auth parity
-
-- [ ] **Task 3.1**: Better Auth hooks
-  - Description: `sendResetPassword`/`sendVerificationEmail` wired to the same templates
-  - Files: `api/src/betterAuthSetup.ts`
-  - Depends on: 2.3
-  - Acceptance: parity test asserting identical template usage
-
-## Phase 4 — Client + docs
-
-- [ ] **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
-  - 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
-  - Description: how-to + env reference + rulesync
-  - Files: `docs/how-to/password-reset.md`, `docs/reference/environment-variables.md`, `.rulesync/**`
-  - Depends on: Phase 2
-  - Acceptance: `bun run rules:check` passes

package/dist/docs/versioned/57.2.0/tasks/positioning-django-rails-universal.md

@@ -1,100 +0,0 @@
-# Task List: Positioning — "Django/Rails for TypeScript, with Universal Apps"
-
-See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../implementationPlans/positioning-django-rails-universal.md)
-
-**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` touch the architecture diagram, package list, or integration flow and must run after PR #869 merges and after [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) Phase 6. Unmarked tasks are safe earlier.
-
-## Instructions for the implementing agent
-
-- Write the copy blocks **once** in `docs/explanation/positioning.md` (Task 1.1), then copy them verbatim everywhere else. Do not paraphrase per surface — drift is the problem this IP exists to fix.
-- Do not claim any feature listed under "Where Terreno is headed" as shipped. If you are unsure whether something ships today, grep for it in the package source before writing about it.
-- When moving content out of the README, use `git mv`-style discipline: cut from one file, paste into the other in the same commit, and grep for inbound links.
-- Run `bun run website:build` and `bun run rules:check` before each commit that touches `website/` or `.rulesync/`.
-
-## Phase 1: Canonical copy
-
-- [x] **Task 1.1**: Write `docs/explanation/positioning.md`
-  - Description: New explainer containing five clearly-labeled copy blocks in fenced code blocks (so they can be copied verbatim without markdown rendering surprises): `tagline` (one line), `elevator` (2–3 sentences), `pillars` (three bullets, in the order batteries-included / universal-by-default / AI-native), `aiPillar` (2–3 sentences naming both AI layers per IP question PO7 — the MCP tool layer and the `/terreno-*` SDLC pipeline process layer), and `pitch` (~150 words). Then a "Why the Django/Rails analogy" section, then the honest comparison table from the IP. Then a "Language rules" section restating the four rules from the program doc (lead with the analogy, say "universal app", never claim unshipped features, keep superlatives off reference pages) plus a fifth: never describe one AI layer without the other.
-  - Files: `docs/explanation/positioning.md` (new)
-  - Depends on: none
-  - Acceptance: five fenced copy blocks present and labeled; the `aiPillar` block names both the MCP tools and the `/terreno-*` pipeline; comparison table has at least eight rows including at least three honest gaps with IP links; language rules section has all five rules.
-
-- [x] **Task 1.2**: Verify every claim in the comparison table
-  - Description: For each row of the comparison table, confirm the Terreno side exists by finding it in source: `modelRouter` in `api/src/api.ts`, admin packages, `Permissions` in `api/src/permissions.ts`, Better Auth in `api/src/betterAuth*.ts`, MCP tools in `mcp-server/src/tools.ts`, and the SDLC pipeline in `plugins/terreno-planning/skills/`. For each "not shipped" row (background jobs, SSR, RBAC), confirm it is genuinely absent and link the IP or roadmap item tracking it. Correct any row that turns out to be wrong.
-  - Files: `docs/explanation/positioning.md`
-  - Depends on: Task 1.1
-  - Acceptance: every "shipped" row cites a source path; the generator row cites both `mcp-server/src/tools.ts` and `plugins/terreno-planning/`; every "not shipped" row links an IP file that exists in `docs/implementationPlans/`.
-
-- [x] **Task 1.3**: Gate the pipeline claim on its portability work
-  - Description: The `/terreno-*` pipeline currently only runs inside this monorepo (see [`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md), "It only works here"). Do not publish positioning copy that implies consumers can use it until that IP's Phase 2 is complete. Check the state of `agentic-sdlc-plugin` Task 2.5 before writing the `aiPillar` block; if portability is not done, write the block describing the tool layer only and add a `TODO` in the IP to revisit, rather than making a claim that fails on first use.
-  - Files: `docs/explanation/positioning.md`
-  - Depends on: Task 1.1
-  - Acceptance: the `aiPillar` block claims the pipeline only if `agentic-sdlc-plugin` Task 2.5 has passed; otherwise the omission is recorded with a pointer to the blocking task.
-
-## Phase 2: README restructure
-
-- [ ] **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
-  - 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
-  - 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
-  - Acceptance: package list matches `publish-on-tag.yml` one-to-one; each description matches the package's `package.json`; diagram names syncdb not rtk.
-
-## Phase 3: Docs site
-
-- [ ] **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
-  - 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
-  - Acceptance: `bun run website:build` succeeds; the built HTML contains the canonical tagline in the meta description; the hero (if present) shows the three pillars.
-
-## Phase 4: Agent surfaces
-
-- [ ] **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
-  - 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
-  - Acceptance: `bun run mcp:build` succeeds; the overview resource opens with the tagline; no resource intro describes Terreno as "a monorepo of shared packages".
-
-## Phase 5: Metadata
-
-- [ ] **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
-  - Acceptance: every published package has a `description` matching the pattern, plus `repository`, `homepage`, and `bugs` fields; `bun install` still resolves cleanly.
-
-- [x] **Task 5.2**: Document the GitHub repository metadata
-  - Description: The repo description and topics cannot be set from a commit. Add a "Repository metadata" subsection to `docs/explanation/positioning.md` giving the exact description string (the short tagline variant from PO1 option C) and the exact topic list to set: `typescript`, `react-native`, `expo`, `express`, `mongoose`, `framework`, `mcp`, `ai`, `universal-apps`, `full-stack`. Mark it as a maintainer action.
-  - Files: `docs/explanation/positioning.md`
-  - 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
-  - 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
-  - Acceptance: no prose surface says "monorepo containing shared packages"; component counts are either verified against the export list or removed; `bun run rules:check` exits 0.

package/dist/docs/versioned/57.2.0/tasks/upgrade-guides-and-skill.md

@@ -1,118 +0,0 @@
-# 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
-
-- [ ] **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.
-
-- [ ] **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.
-
-- [ ] **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.
-
-- [ ] **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
-
-- [ ] **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.
-
-- [ ] **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
-
-- [ ] **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.
-
-- [ ] **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.
-
-- [ ] **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.
-
-- [ ] **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.
-
-- [ ] **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
-
-- [ ] **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.
-
-- [ ] **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.
-
-- [ ] **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
-
-- [ ] **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.
-
-- [ ] **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/dist/docs/versioned/57.2.0/tutorials/README.md

@@ -1,7 +0,0 @@
-# Tutorials
-
-Learning-oriented, hands-on lessons. Start here if you are new to Terreno.
-
-## Contents
-
-- [Getting started](getting-started.md) — Install, run the examples, and see the stack in action

package/dist/docs/versioned/57.2.0/tutorials/getting-started.md

@@ -1,44 +0,0 @@
-# Getting Started
-
-Run the example full stack to see Terreno in action.
-
-## Prerequisites
-
-- [Bun](https://bun.sh/) installed
-- MongoDB running (for the backend example)
-
-## Steps
-
-1. **Clone and install**
-
-   ```bash
-   bun install
-   ```
-
-2. **Start the backend** (terminal 1)
-
-   ```bash
-   bun run backend:dev
-   ```
-
-   Backend runs at `http://localhost:4000`. OpenAPI spec at `/openapi.json`.
-
-3. **Start the frontend** (terminal 2)
-
-   ```bash
-   bun run frontend:web
-   ```
-
-   Frontend runs in the browser and talks to the backend.
-
-4. **Optional: regenerate SDK** after backend route changes
-
-   ```bash
-   cd example-frontend && bun run sdk
-   ```
-
-## Next steps
-
-- [How to create a model](../how-to/create-a-model.md) — Learn model conventions including required field descriptions
-- [How-to guides](../how-to/) — Task-focused guides
-- [Reference](../reference/) — Package and API details

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

@@ -1,41 +0,0 @@
-# Explanation
-
-Understanding-oriented documentation: concepts, architecture, and context.
-
-## Deployment
-
-- [Deployment baseline](deployment-baseline.md) — seven requirements for production Terreno apps
-- [GCP deployment architecture](deployment-architecture-gcp.md) — Cloud Run + GCS/CDN topology and tradeoffs
-- [GCP hosting architecture](gcp-hosting-architecture.md) — static site hosting with GCS and Cloud CDN (legacy detail)
-
-## Contents
-
-- [Local-first data](local-first-data.md) — Why the local store is the UI source of truth
-- [Planning plugins](planning-plugins.md) — How the lifecycle and scan plugins divide discovery from delivery
-- [Loop engineering](loop-engineering.md) — Fresh-invocation lifecycle, state, evidence, and orchestration boundaries
-- [GitHub issue lifecycle](../how-to/github-issue-lifecycle.md) — Pick-ready issues and plan comments for Pick/Roast
-- [Install agent skills](../how-to/install-agent-skills.md) — `npx skills add TerrenoLabs/terreno`
-- [AI observability](ai-observability.md) — Two planes (telemetry vs control), plugins vs LangfuseApp, SOP loop
-- [Durable agent harness](durable-agent-harness.md) — Phases, checkpoints, and why the audit span shares the checkpoint transaction
-- [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
-- [Agent UI Asks](agent-ui-asks.md) — Why agent questions are client-side tool calls, the pause and resume round trip, why cards carry exact answers, the watch paths, asks vs blocks
-- [Agent UI blocks](agent-ui-blocks.md) — Why chat replies use a closed YAML catalog instead of free-form UI, why steppers and checklists call the server, and the rich-blocks rollout
-- [Authentication architecture](authentication.md) — Better Auth, JWT, and optional MCP service tokens
-- [Organization tenancy](organizations.md) — Optional Membership-backed tenancy, context, and isolation boundaries
-- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
-- [Dependency management](dependency-management.md) — Catalog pins, exercise tests, fingerprint freeze
-- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
-- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
-- [Explicit `any` policy](explicit-any-policy.md) — Require rationale markers and ratchet usage per file
-- [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels
-- [TypeScript configuration](typescript-configuration.md) — tsconfig profiles for Node, frontend, Expo, and Bun workspaces on TypeScript 6
-- [Production source rules](source-rules.md) — Arrow functions, Luxon, APIError, logging, findOne, `as any`
-- [Positioning](positioning.md) — Canonical copy blocks and the honest Django/Rails comparison
-- [Versioning policy](versioning-policy.md) — Lockstep `@terreno/*` versions, pre-1.0 breaks, deprecation window
-- [How admin interfaces are shaped](admin-interface.md) — Screens, sidebar, `apiBase` vs `routeBase`
-- [Admin plugin frontend widgets](admin-plugin-frontend.md) — Widget IDs from backend plugins
-- [Consent admin migration](admin-consent-migration.md) — Which consent screens stay hand-written
-- [Public roadmap process](roadmap-process.md) — GitHub roadmap vs Linear execution
-- [Example app coverage](example-coverage.md) — Which framework capabilities the example apps exercise
-- [Repository settings](repository-settings.md) — Maintainer GitHub settings that cannot be committed
-- [Why Terreno owns chart SVG](charts.md) — Owned `react-native-svg` vs victory-native

package/src/docs/versioned/57.15.0/explanation/admin-interface.md

@@ -1,84 +0,0 @@
-# How admin interfaces are shaped
-
-Prefer existing admin packages over a new dashboard. `@terreno/admin-backend`
-exposes `/admin/config` plus per-model CRUD. `@terreno/admin-frontend` renders that
-config as a sidebar, home dashboard, tables, and forms. `@terreno/admin-spa` is the
-same UI served from the API origin.
-
-Consumer screens are thin routes. They wrap `AdminProvider` + `AdminShellLayout` and
-let `AdminHome`, `AdminScreenRouter`, `AdminModelTable`, and `AdminModelForm` do the
-work. Hand-write a route only when the generic table/form cannot express the
-workflow (consent publish, comms message detail, password-on-create).
-
-## Two hosts
-
-| Host | When to use | Route prefix (`routeBase`) | API prefix (`apiBase`) | Fetch auth |
-| --- | --- | --- | --- | --- |
-| Embedded (`example-frontend/app/admin`) | Admin lives inside the product Expo app | `"/admin"` | `"/admin"` | `getAuthHeaders` → Bearer, plus `apiOrigin` = RTK `baseUrl` so RPC does not hit the Expo origin |
-| Standalone (`@terreno/admin-spa`) | Same-origin console served by `AdminSpaServeApp` | `""` (SPA root; mount is `/console`) | `"/admin"` | `credentials="same-origin"`; empty `getAuthHeaders`; omit `apiOrigin` |
-
-`apiBase` is the HTTP path for `/config` and CRUD. `routeBase` is the Expo Router
-prefix the sidebar concatenates onto `/{model.name}` and `/{screen.name}`. Mixing
-them puts nav on the wrong URL. Embedded hosts must also set `apiOrigin` (the
-backend origin, e.g. `http://localhost:4000`) on `AdminProvider`. Native `fetch`
-RPC uses that origin to prefix `/admin/config` and `/rbac/roles`. Do not put the
-origin in `apiBase` — that would rewrite in-app navigation.
-
-## Screen kinds
-
-| Kind | Source of truth | Frontend |
-| --- | --- | --- |
-| Model changelist / form | `modelRouter({admin: ...})` or plugin `adminContribution()` | `AdminScreenRouter` → `AdminModelTable` / `AdminModelForm` (list filters live on `DataTable`, not a side drawer) |
-| Custom screen | `AdminApp.customScreens` or plugin `customScreens` (`name` + `displayName`) | Matching `AdminProvider.widgets.screens[name]`, or a dedicated Expo route |
-| Platform tool | Built-in (`scripts`, `roles`, `version`, `configuration`, audit log, feature flags, jobs) | Sidebar **Platform** section; visibility from `/admin/config.platformTools` (jobs is lifted from `customScreens`) |
-| Home widget | `AdminApp.home.slots` IDs | `AdminProvider.widgets.home` (built-ins already registered) |
-
-`GET /admin/config` is caller-specific. Models and custom screens without read
-access are omitted. The sidebar must not invent links the config did not return.
-
-## Navigation chrome
-
-`AdminShell` (via `AdminShellLayout`) always owns the sidebar. Do not add a second
-app-level nav inside admin.
-
-Order in the rail:
-
-1. **Home** → `{routeBase}/`
-2. **Models** grouped by `admin.group` (ungrouped models land in **General**). Custom screens with `group` render inside the matching group **before** model links for that group. A grouped screen with no models still gets its own group heading.
-3. **Screens** — only `customScreens` **without** `group` (plus optional host extras)
-4. **Platform** — Scripts (`/__scripts`), Migrations (`/__migrations` when
-   `migrations.enabled`), Roles, Version, Audit Log, Feature Flags, Jobs, Configuration
-
-Audit log and Feature Flags are models, but the shell lifts them into Platform so
-operators do not hunt for them among business collections. The Platform Audit Log
-row is `AuditEvent` when `AuditApp` is registered. `isAuditLogModel` also matches
-legacy `AdminAuditLog`, `audit-log`, and `audit-events` names. Jobs is a custom
-screen (`name: "jobs"`); the shell lifts it the same way.
-
-Below 768px the rail becomes a hamburger drawer. The main column is a body-style
-canvas (`neutral-050`). Nested `Page` screens use `color="transparent"` and
-`padding={0}` so cards sit on that canvas. Custom screens wrap content in
-`AdminScreenPage`; the back arrow uses `router.push(routeBase)` rather than
-`router.back()` because sidebar clicks do not always leave history on web.
-
-## Where code goes
-
-| Concern | Location |
-| --- | --- |
-| Which models appear | `modelRouter` `admin` block, or plugin `adminContribution()` |
-| Extra non-CRUD pages | `AdminApp.customScreens` + `widgets.screens` with the **same** `name`. Optional `group` places the screen in that sidebar group (see **Models** above). |
-| Home dashboard composition | `AdminApp.home.slots` |
-| Field widgets | `admin.fieldOverrides.widget` + `widgets.fields` |
-| Expo files | `app/admin/_layout.tsx` (shell once) or per-route shell in admin-spa |
-| Dedicated extra segments (`/comms/:id`) | Explicit Expo files so `[model]/[id]` does not treat them as generic forms |
-| Data fetching | REST remains membership/search/sort/pagination. String `_id` models with `adminBroadcast` overlay TinyBase and write through syncdb when the host passes a window client + fetch auth. Framework RPC uses host-bound fetch; ObjectId/API-only CRUD keeps RTK compatibility in Terreno 57. |
-
-## Related
-
-- [Build admin screens](../how-to/build-admin-screens.md)
-- [Add a model to the admin](../how-to/admin-add-model.md)
-- [Customize the admin home](../how-to/admin-custom-home.md)
-- [Add a custom admin field widget](../how-to/admin-custom-widget.md)
-- [Admin plugin frontend widgets](admin-plugin-frontend.md)
-- [admin-frontend reference](../reference/admin-frontend.md)
-- [admin-config reference](../reference/admin-config.md)