@terreno/mcp 0.27.0 → 0.28.0

package/src/docs/versioned/next/implementationPlans/public-roadmap-github.md

@@ -0,0 +1,204 @@
+# Implementation Plan: Public Roadmap on GitHub
+
+**Status:** Approved — decisions recorded (2026-07-29)
+**Priority:** High
+**Effort:** Small batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`oss-governance-baseline`](oss-governance-baseline.md) (issue templates land there)
+**RTK deprecation flag:** None — process and metadata only. Safe to implement before PR #869.
+
+## Goal
+
+Run Terreno's roadmap in public on GitHub while keeping Linear as the internal execution tracker. Outside users need to see what is planned, argue about priorities, and file well-shaped requests; Flourish engineers need to keep sprinting in Linear without double-entry.
+
+The design principle: **one direction of truth per artifact.** Public discussion and roadmap state live on GitHub. Sprint execution, estimates, and assignees live in Linear. IPs in `docs/implementationPlans/` remain the design source of truth for both.
+
+## Non-Goals
+
+- Migrating Flourish's internal work off Linear.
+- Building a custom sync service between Linear and GitHub.
+- Publishing internal Flourish product roadmap items that happen to touch Terreno.
+- Public sprint planning or estimates.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Decision |
+|---|----------|
+| R1 | Target **release version** on the roadmap (`0.28`, `0.29`, `Future`) — no calendar dates |
+| R2 | GitHub Project board + **generated `ROADMAP.md`** |
+| R3 | Linear GitHub sync on issues labeled **`tracked`** (one-way GitHub → Linear) |
+| R4 | **Maintainers only** open board items; users file Ideas discussions |
+| R5 | **One tracking issue per IP**, opened manually when IP reaches Approved |
+| R6 | **Post-moderated** Discussions |
+| R7 | Lightweight **RFC** discussion category → graduates to IP |
+
+## Architecture
+
+### Three surfaces, one flow
+
+```mermaid
+flowchart LR
+  subgraph public ["Public (GitHub)"]
+    D["Discussions<br/>Ideas / Q&A / RFC"]
+    I["Issues<br/>triaged work"]
+    P["Project: Terreno Roadmap"]
+    RM["ROADMAP.md<br/>generated"]
+  end
+  subgraph design ["Design (repo)"]
+    IP["docs/implementationPlans/*.md"]
+  end
+  subgraph internal ["Internal"]
+    L["Linear"]
+  end
+  D -->|"maintainer promotes"| I
+  I -->|"triage: add to board"| P
+  P -->|"nightly generate"| RM
+  I -->|"label: tracked"| L
+  IP -->|"Approved → tracking issue"| I
+  D -->|"RFC accepted"| IP
+```
+
+### Discussion categories
+
+| Category | Format | Purpose | Who posts |
+|----------|--------|---------|-----------|
+| **Announcements** | Announcement | Releases, breaking changes, deprecations (including the RTK → syncdb deprecation), launch posts | Maintainers only |
+| **Q&A** | Question / Answer | "How do I…" support questions. Answers marked accepted; recurring ones graduate into `docs/how-to/` | Anyone |
+| **Ideas** | Open-ended | Feature requests before they are shaped. The intake funnel — nothing goes straight to an issue | Anyone |
+| **RFCs** | Open-ended | Proposals that change public API or add a package. Graduates into an IP when accepted | Anyone, template-guided |
+| **Show and tell** | Open-ended | Apps built with Terreno. Social proof, and a source of real-world friction reports | Anyone |
+| **Agents & AI** | Open-ended | MCP setup, skills, agent workflows, prompt patterns. Deliberately separate — it is the differentiator and deserves a visible home | Anyone |
+| **Docs feedback** | Open-ended | Per-page feedback; linked from every docs page footer | Anyone |
+
+Category ordering in the UI should be: Announcements, Q&A, Ideas, Agents & AI, RFCs, Show and tell, Docs feedback.
+
+### Project board
+
+One org- or repo-level Project named **Terreno Roadmap**, board layout, grouped by `Status`.
+
+**Fields**
+
+| Field | Type | Values | Notes |
+|-------|------|--------|-------|
+| `Status` | single select | `Inbox`, `Shaping`, `Planned`, `In progress`, `In review`, `Shipped`, `Declined` | `Inbox` = triaged but not committed |
+| `Area` | single select | `api`, `ui`, `syncdb`, `auth`, `admin`, `ai`, `mcp`, `docs`, `deploy`, `examples`, `dx` | Mirrors package boundaries plus cross-cutting areas |
+| `Target` | single select | `0.28`, `0.29`, `Next`, `Future` | Per R1; add versions as releases approach |
+| `IP` | text | e.g. `web-ssr-and-admin-spa` | Slug of the IP file, empty if no IP yet |
+| `Impact` | single select | `Breaking`, `Feature`, `Improvement`, `Fix` | Drives changelog grouping |
+| `Community interest` | number | 👍 count, refreshed on triage | Makes prioritization legible |
+
+**Views**
+
+1. **Roadmap** (board, grouped by `Status`, filtered to `Status != Declined`) — the default public view.
+2. **By area** (table, grouped by `Area`) — for contributors looking for something to pick up.
+3. **Next release** (table, filtered to `Target = <current+1>`) — what is actually landing.
+4. **Needs shaping** (table, filtered to `Status = Shaping`) — where community input changes outcomes.
+
+### Label taxonomy
+
+Keep it small enough to be used consistently.
+
+| Prefix | Labels | Purpose |
+|--------|--------|---------|
+| `area:` | `area:api`, `area:ui`, `area:syncdb`, `area:auth`, `area:admin`, `area:ai`, `area:mcp`, `area:docs`, `area:deploy`, `area:examples`, `area:dx` | Matches the `Area` project field |
+| `type:` | `type:bug`, `type:feature`, `type:docs`, `type:chore`, `type:rfc` | Set by issue forms where possible |
+| `status:` | `status:needs-triage`, `status:needs-info`, `status:blocked`, `status:wontfix` | Workflow state that is not board state |
+| (bare) | `good first issue`, `help wanted`, `breaking`, `tracked`, `deprecation` | `tracked` triggers the Linear sync; `deprecation` marks RTK-migration work |
+
+### Linear bridge
+
+- Linear's GitHub integration is configured to import GitHub issues labeled `tracked` into the Terreno Linear team.
+- Direction: GitHub → Linear for creation and title/description; status is **not** synced automatically. When a Linear issue closes, the engineer closes the GitHub issue in the same PR (`Fixes #NNN`), which moves the board to `Shipped`.
+- Linear issues created internally that will become public work get a GitHub issue opened manually and the Linear URL pasted into it. No automation in that direction.
+- Internal-only Linear work is never mirrored.
+
+Rationale: two-way status sync between trackers reliably produces confusing loops. One-way intake plus `Fixes #NNN` on merge gives correct public state with no maintenance.
+
+### Automation
+
+Three GitHub Actions workflows:
+
+1. **`roadmap-generate.yml`** — on a schedule and on Project item changes, query the Project via the GraphQL API and regenerate `ROADMAP.md` (grouped by `Target`, then `Area`, with links to issues and IPs). Commits only when the content changes.
+2. **`triage.yml`** — on issue open: apply `status:needs-triage`, and apply the `area:*` label derived from the issue form's package dropdown.
+3. **`discussion-to-issue.yml`** — optional; when a maintainer adds the `promote` label to a Discussion (or comments `/promote`), open a linked issue pre-filled from the discussion body. Skip in v1 if the GraphQL surface proves fiddly; manual promotion is acceptable.
+
+## Models
+
+None (GitHub metadata only).
+
+## APIs
+
+GitHub GraphQL API (`ProjectV2` queries) is used read-only by `roadmap-generate.yml`. Requires a token with `project: read` and `contents: write`; use the built-in `GITHUB_TOKEN` if org settings permit Projects access, otherwise a fine-grained PAT stored as a secret and validated at job start per the repo's required-secret-validation convention.
+
+## Notifications
+
+None beyond GitHub's own subscriptions. Announcements category posts should be the release channel; the `release` skill gains a step to post one for releases with breaking changes.
+
+## UI
+
+- `ROADMAP.md` at the repo root, linked from `README.md` and the docs site sidebar.
+- A "Discuss this page" footer link on docs pages pointing at the Docs feedback category (implemented in the Docusaurus theme config).
+
+## Phases
+
+1. **Discussions** — enable, create categories, seed each with a pinned intro post, add the RFC template.
+2. **Project board** — create the Project, fields, and views; backfill items from `PLAN_INDEX.md` and the IPs in this program.
+3. **Labels and triage** — create the label set, delete unused defaults, add `triage.yml`.
+4. **Roadmap generation** — `ROADMAP.md` + `roadmap-generate.yml`, link from README and docs site.
+5. **Linear bridge** — configure the integration, document the process in `CONTRIBUTING.md`, and record the rules in a maintainer doc.
+
+## Feature Flags & Migrations
+
+None. Existing open issues need a one-time triage pass to apply the new labels and land on the board (Task 3.3).
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- Public voting/prioritization beyond 👍 reactions.
+- Automated changelog generation from board state.
+- A status page or uptime dashboard for the hosted MCP server.
+- Contributor recognition automation (all-contributors bot).
+
+## Files to Create / Modify
+
+**Create**
+
+- `ROADMAP.md`
+- `.github/DISCUSSION_TEMPLATE/rfc.yml`
+- `.github/DISCUSSION_TEMPLATE/ideas.yml`
+- `.github/workflows/roadmap-generate.yml`
+- `.github/workflows/triage.yml`
+- `docs/explanation/roadmap-process.md`
+- `scripts/generate-roadmap.ts`
+
+**Modify**
+
+- `README.md` (link `ROADMAP.md` and Discussions)
+- `CONTRIBUTING.md` (intake flow: Discussions → issue → board; RFC path)
+- `website/docusaurus.config.ts` (docs feedback footer link, roadmap sidebar entry)
+- `.rulesync/skills/release/SKILL.md` (post an Announcements discussion for breaking releases)
+- `.github/ISSUE_TEMPLATE/*.yml` (add `type:` labels via the `labels:` key)
+
+## Task List
+
+See [`docs/tasks/public-roadmap-github.md`](../tasks/public-roadmap-github.md).
+
+## Acceptance Criteria
+
+- [ ] All seven Discussion categories exist with the specified formats and a pinned intro post each.
+- [ ] The **Terreno Roadmap** Project exists with the six fields and four views described above.
+- [ ] Every IP in `docs/implementationPlans/PLAN_INDEX.md` marked Approved or later has a tracking issue on the board with its `IP` field set to the IP slug.
+- [ ] The label set matches the taxonomy table; no unused GitHub default labels remain.
+- [ ] `bun run scripts/generate-roadmap.ts` produces `ROADMAP.md` grouped by `Target` then `Area`, and `roadmap-generate.yml` commits it only when changed.
+- [ ] Opening a new issue applies `status:needs-triage` and the correct `area:*` label automatically.
+- [ ] Adding `tracked` to a GitHub issue creates a corresponding Linear issue; closing the Linear issue does **not** silently change GitHub state.
+- [ ] `CONTRIBUTING.md` documents the intake flow and the RFC path in under 30 lines.
+- [ ] `docs/explanation/roadmap-process.md` explains the GitHub/Linear split, including why status is not two-way synced.
+- [ ] Every docs page shows a working "Discuss this page" link.

package/src/docs/versioned/next/implementationPlans/rtk-to-syncdb-migration-docs.md

@@ -0,0 +1,169 @@
+# Implementation Plan: RTK Deprecation and SyncDB Migration Docs
+
+**Status:** Draft — blocked on PR #869
+**Priority:** Critical (gates most of Wave 1)
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** PR [#869](https://github.com/flourishhealth/terreno/pull/869) merging
+**RTK deprecation flag:** **Blocked** — this IP *is* the RTK deprecation. Nothing here can be written until #869 lands, because the public surface of `@terreno/syncdb` is not final until then.
+
+## Goal
+
+Make **Better Auth + `@terreno/syncdb`** the documented, blessed frontend platform, and give every existing `@terreno/rtk` consumer a correct, tested migration path. This is the gating IP for the launch documentation: publishing tutorials, reference docs, or a positioning rewrite against RTK Query would guarantee an immediate rewrite.
+
+Scope is documentation, deprecation signalling, and migration tooling — not syncdb feature work (that is PR #869's own scope).
+
+## Non-Goals
+
+- Implementing or changing `@terreno/syncdb` behavior.
+- Migrating internal Flourish applications (tracked separately).
+- Removing `@terreno/rtk` from the repo or unpublishing it.
+- Rewriting the tutorials themselves — that is [`docs-tutorials-ai-first`](docs-tutorials-ai-first.md), which depends on this IP.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (see program [P6–P7](oss-launch-program.md#blocking-questions-program-level)).
+
+| # | Question | Decision |
+|---|----------|----------|
+| M1 | RTK support window (→ P6) | **Keep publishing with deprecation notice through the current major line; stop publishing `@terreno/rtk` in the next major** |
+| M2 | `npm deprecate` marker | **B** — mark at end of support window |
+| M3 | Auth vs data migration | **C** — Better Auth first, then syncdb |
+| M4 | `docs/reference/rtk.md` (→ P7 **A**) | **Remove from the public reference index** — no legacy reference page. Existing RTK consumers use **`docs/how-to/migrate-rtk-to-syncdb.md`** only; do not maintain a parallel RTK reference path in launch docs |
+| M5 | SDK codegen command | **A** — `bun run sdk` keeps working |
+| M6 | Codemod | **B** — agent-assisted via `upgrading-terreno` skill |
+| M7 | Local-first default | **A** if #869 ships local-first only (verify against merged code) |
+
+## Architecture
+
+### Documentation surface map
+
+Every document below currently describes an RTK-shaped world and must be reconciled.
+
+| Document | Current state | Target state |
+|----------|---------------|--------------|
+| `docs/reference/rtk.md` | Primary frontend reference | **Removed from launch reference** (P7 A). Redirect to migration guide; archive pre-launch content if needed for inbound links |
+| `docs/reference/syncdb.md` | does not exist | New primary frontend data reference |
+| `docs/how-to/migrate-rtk-to-syncdb.md` | does not exist | New step-by-step migration guide |
+| `docs/explanation/local-first-data.md` | does not exist | New conceptual explainer: why local-first, what changes for the developer |
+| `docs/explanation/authentication.md` | JWT-primary | Better Auth primary, JWT documented as legacy |
+| `docs/how-to/configure-better-auth.md` | Exists, positioned as optional | Repositioned as the default auth path |
+| `docs/README.md` | Package table omits `ai`, `syncdb` | Complete package table with syncdb as the frontend data package |
+| `.rulesync/skills/generate-sdk/SKILL.md` | RTK Query codegen | syncdb descriptor codegen; RTK path kept as a legacy branch during the support window |
+| `.rulesync/rules/rtk/*` | RTK conventions for agents | New `syncdb` rules; RTK rules marked legacy |
+| `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md` | "Always use generated SDK hooks" (RTK) | syncdb hooks; RTK guidance moved to a legacy note |
+| `README.md` architecture diagram | `@terreno/rtk` box | `@terreno/syncdb` box |
+| `mcp-server` resources + bootstrap templates | RTK store wiring | syncdb client wiring |
+
+### The migration guide's shape
+
+The migration guide is the highest-value artifact. It must be organized by *what the developer has to change*, not by package internals:
+
+1. **Before you start** — decision table: adopt Better Auth first (M3), confirm backend version, confirm Mongo is a replica set.
+2. **Install and configure** — add `@terreno/syncdb`, create the client, wrap the app, remove the Redux store or keep it side-by-side.
+3. **Reads** — `useGetTodosQuery` → syncdb query hook. Show the same screen before and after, side by side.
+4. **Writes** — `usePostTodosMutation` → syncdb mutation. This is where behavior genuinely changes: writes land locally first, so loading states, error handling, and optimistic-update code all get simpler or get deleted. Show what to delete.
+5. **Conflicts** — new concept with no RTK equivalent. What a conflict is, when it happens, the two v1 strategies, and the minimum UI a consumer must add.
+6. **Sync status** — replacing spinner-driven UX with sync-state UX.
+7. **Auth** — JWT auth slice → Better Auth session, including token storage differences and the socket auth handshake.
+8. **Codegen** — regenerating typed operations, and what changes in the generated file.
+9. **Feature flags** — the OpenFeature provider's new data source.
+10. **Rollback** — how to go back if it goes wrong, per-screen via the `USE_SYNCDB` flag.
+11. **Checklist** — a copy-pasteable checklist for a real migration.
+
+Each step needs a working before/after code pair taken from the actual `example-frontend` migration in #869, not invented.
+
+### Deprecation signalling
+
+| Channel | Action |
+|---------|--------|
+| `docs/reference/legacy/rtk.md` | Legacy banner with the support window and end date/version |
+| `rtk/README.md` | Deprecation notice at the top linking the migration guide |
+| Root `CHANGELOG.md` | `Deprecated` entry in the release that lands #869 |
+| GitHub Discussions | Announcement post (see [`public-roadmap-github`](public-roadmap-github.md)) |
+| `mcp-server/src/docs/upgrades/<version>.md` | Upgrade note so `terreno_get_upgrade_guide` returns it |
+| `ROADMAP.md` | An item with `Impact = Breaking` and the removal target |
+| Agent rules | `.rulesync/rules/rtk/` marked legacy so agents stop generating RTK code |
+
+Agent rules matter most in practice: if the MCP server and bootstrap templates keep emitting RTK code, every AI-generated Terreno app starts on the deprecated path.
+
+## Models
+
+None.
+
+## APIs
+
+None new. This IP documents the surface #869 introduces; it must not add to it.
+
+## Notifications
+
+One Announcements discussion post at the start of the deprecation window. No in-app notifications.
+
+## UI
+
+None directly. The migration guide specifies the minimum conflict-resolution and sync-status UI a consumer must build; if `example-frontend` lacks a good reference implementation after #869, file a follow-up rather than inventing one here.
+
+## Phases
+
+1. **Reconcile with merged #869** — read the merged code, produce a verified inventory of the actual public API, and correct the surface map above. Nothing else starts until this is done.
+2. **Reference docs** — `docs/reference/syncdb.md`, move and banner `rtk.md`, update `docs/README.md`.
+3. **Migration guide** — the eleven-step guide with verified before/after pairs.
+4. **Explainers and auth repositioning** — `local-first-data.md`, rewrite `authentication.md`, reposition Better Auth.
+5. **Agent surfaces** — rules, skills, `AGENTS.md`/`CLAUDE*.md`, MCP resources and bootstrap templates.
+6. **Deprecation signalling** — READMEs, changelog, upgrade note, announcement draft, roadmap item.
+
+## Feature Flags & Migrations
+
+- `USE_SYNCDB` (introduced by #869) is the consumer-side rollout flag; the migration guide is organized around enabling it per screen.
+- No repo-side flag needed for documentation.
+- Docusaurus redirects required for every moved page (`docs/reference/rtk.md` → `docs/reference/legacy/rtk.md`).
+
+## Not Included / Future Work
+
+- Removing `@terreno/rtk` from the monorepo (end of support window, separate IP).
+- Native (iOS/Android) local storage encryption, which #869 explicitly defers.
+- Migrating Flourish's internal apps.
+- A `syncdb` performance/tuning guide.
+
+## Files to Create / Modify
+
+**Create**
+
+- `docs/reference/syncdb.md`
+- `docs/reference/legacy/rtk.md` (moved)
+- `docs/how-to/migrate-rtk-to-syncdb.md`
+- `docs/explanation/local-first-data.md`
+- `mcp-server/src/docs/upgrades/<syncdb-release-version>.md`
+- `.rulesync/rules/syncdb/00-syncdb.md`
+
+**Modify**
+
+- `docs/reference/README.md`, `docs/README.md`, `docs/how-to/README.md`
+- `docs/explanation/authentication.md`, `docs/how-to/configure-better-auth.md`
+- `README.md` (architecture diagram and package list)
+- `rtk/README.md`, `syncdb/README.md`
+- `.rulesync/rules/rtk/00-rtk.md` (legacy banner), `.rulesync/skills/generate-sdk/SKILL.md`
+- `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md`
+- `mcp-server/src/docs/resources/*.md`, `mcp-server/src/docs/templates/bootstrap/**`
+- `CHANGELOG.md`
+- `website/docusaurus.config.ts` (redirects)
+
+## Task List
+
+See [`docs/tasks/rtk-to-syncdb-migration-docs.md`](../tasks/rtk-to-syncdb-migration-docs.md).
+
+## Acceptance Criteria
+
+- [ ] A verified inventory of `@terreno/syncdb`'s public exports exists and every documented API appears in the merged package's `src/index.ts`.
+- [ ] `docs/reference/syncdb.md` documents every exported hook, client method, and config option, with a runnable example for each.
+- [ ] `docs/how-to/migrate-rtk-to-syncdb.md` covers all eleven steps, and every before/after pair compiles against the merged code.
+- [ ] Following the guide, a fresh clone of `example-frontend` can be moved from the RTK path to the syncdb path with no undocumented steps.
+- [ ] `docs/reference/rtk.md` no longer exists at its old path; the Legacy page states the support window; a Docusaurus redirect resolves the old URL.
+- [ ] `docs/explanation/authentication.md` presents Better Auth first and JWT as legacy.
+- [ ] No agent-facing surface (`AGENTS.md`, `CLAUDE*.md`, `.rulesync/rules/`, MCP resources, bootstrap templates) instructs an agent to write RTK Query code for a new app.
+- [ ] `terreno_bootstrap_app` output uses syncdb, and a bootstrapped app runs.
+- [ ] `terreno_get_upgrade_guide` returns the syncdb upgrade note for the release range that includes #869.
+- [ ] `CHANGELOG.md` has a `Deprecated` entry naming `@terreno/rtk`, the support window, and the migration guide link.
+- [ ] `bun run lint`, `bun run compile`, `bun run rules:check`, and `bun run website:build` all pass.

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

@@ -0,0 +1,166 @@
+# Implementation Plan: Upgrade Guides and the `upgrading-terreno` Skill
+
+**Status:** Draft — blocked on PR #869
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md), [`oss-governance-baseline`](oss-governance-baseline.md) (changelog)
+**RTK deprecation flag:** **Blocked** — the largest upgrade Terreno will ever ask consumers to perform is RTK → syncdb. The skill and the notes must be built around it.
+
+## Goal
+
+Make upgrading Terreno a solved problem before we ask the public to depend on it. The machinery is half-built: `terreno_get_upgrade_guide` exists and concatenates per-release notes, and a `terreno_upgrade` prompt exists — but only two upgrade notes have ever been written (`0.20.0.md`, `0.21.0.md`) against a current version of 0.26.0. Five releases have no notes, so the tool returns nothing useful for any recent range. There is no `upgrading-terreno` skill; the only upgrade skill in the repo is `upgrading-expo`, which handles the Expo SDK portion and nothing Terreno-specific.
+
+An open-source framework that ships breaking changes in lockstep across eleven packages and cannot tell you what changed is not adoptable.
+
+## Non-Goals
+
+- Upgrading the Expo SDK (delegate to the existing `upgrading-expo` skill — do not duplicate its content).
+- Automated codemods (see [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) question M6 — agent-assisted, not codemod).
+- Changing the lockstep versioning scheme.
+- Retroactively rewriting git history or release notes.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (defaults accepted).
+
+| # | Decision |
+|---|----------|
+| U1 | One consolidated **0.21 → 0.26** upgrade note; per-release notes from next version onward |
+| U2 | Upgrade note required when changelog has **Deprecated / Removed / Changed** (CI-enforced) |
+| U3 | Skill **performs** upgrade with confirmation gate + clean git tree |
+| U4 | **Direct multi-version jump** with sequential fallback on failure |
+| U5 | **Wrap `upgrading-expo`** at the correct point in the sequence |
+| U6 | Publish **deprecation window policy** (≥3 minors until 1.0; align RTK sunset with program P6) |
+
+## Architecture
+
+### Three artifacts
+
+1. **Upgrade notes** (`mcp-server/src/docs/upgrades/<version>.md`) — the data. Consumed by `terreno_get_upgrade_guide`, readable directly, and referenced from the changelog.
+2. **The `upgrading-terreno` skill** — the executor. Wraps note application, dependency bumps, Expo delegation, codegen, and verification.
+3. **A versioning and deprecation policy** (`docs/explanation/versioning-policy.md`) — the promise. What lockstep means, what a minor can break before 1.0, how long deprecations last.
+
+### Upgrade note format
+
+Standardize on the shape the existing notes already use, with required sections so the concatenated output from `terreno_get_upgrade_guide` reads coherently across several versions:
+
+```markdown
+# Upgrading to <version>
+
+**Action required:** Yes | No
+**Affected packages:** @terreno/api, @terreno/ui, ...
+
+## Summary
+## Breaking changes
+### <change title>
+**What changed** / **Why** / **Migration** (before/after code)
+## Deprecations
+## New capabilities
+## Verification
+```
+
+The `Verification` section matters most for automation: it gives the skill a concrete way to confirm each version's upgrade succeeded before moving to the next.
+
+### The upgrade ordering problem
+
+Order is the thing consumers get wrong, and it is not obvious:
+
+```mermaid
+flowchart TD
+  A["1. Clean git tree + branch"]
+  B["2. application_info:<br/>current @terreno/* versions"]
+  C["3. terreno_get_upgrade_guide<br/>current → target"]
+  D["4. Backend packages<br/>api, ai, admin-backend, feature-flags, api-health"]
+  E["5. Backend tests + compile"]
+  F["6. Expo SDK<br/>delegate to upgrading-expo"]
+  G["7. Frontend packages<br/>ui, syncdb, admin-frontend, admin-spa"]
+  H["8. Regenerate typed client"]
+  I["9. Compile + lint + tests"]
+  J["10. Run the app, verify UI"]
+  A --> B --> C --> D --> E --> F --> G --> H --> I --> J
+```
+
+Backend first because the OpenAPI spec is the contract the frontend generates from; regenerating the client against an un-upgraded backend produces a client for the wrong API. Expo before the Terreno frontend packages because `@terreno/ui` pins peer dependencies against Expo's versions.
+
+### Release-process enforcement
+
+The `release` skill currently does not require an upgrade note. Add:
+
+1. A required step: if the release's changelog section contains `Breaking`, `Deprecated`, `Removed`, or `Changed`, write `mcp-server/src/docs/upgrades/<version>.md` before tagging.
+2. A CI check in `repo-policies.yml` that fails a release tag when the note is missing.
+
+Without mechanical enforcement this decays again — that is exactly what happened between 0.21.0 and 0.26.0.
+
+## Models / APIs
+
+No new models. `terreno_get_upgrade_guide`'s behavior with a range containing no notes needs improving: it should say "no notes recorded for 0.22–0.24" rather than returning empty, so an agent does not conclude nothing changed.
+
+## Notifications
+
+An Announcements discussion post per breaking release, per [`public-roadmap-github`](public-roadmap-github.md) Task 5.3.
+
+## UI
+
+None.
+
+## Phases
+
+1. **Backfill** — the consolidated 0.21 → 0.26 note plus the note format and template.
+2. **Policy** — `docs/explanation/versioning-policy.md`.
+3. **Skill** — `upgrading-terreno` with the correct ordering and Expo delegation.
+4. **Enforcement** — release skill step and CI check; improve the tool's empty-range response.
+5. **Validation** — perform a real upgrade of a consumer app using only the skill.
+
+## Feature Flags & Migrations
+
+None.
+
+## Not Included / Future Work
+
+- Codemods.
+- Automatic dependency-bump PRs (Dependabot covers third-party deps, not intra-Terreno lockstep bumps).
+- A compatibility matrix across Expo SDK versions (worth doing once there is more than one supported SDK).
+- Downgrade guidance.
+
+## Files to Create / Modify
+
+**Create**
+
+- `mcp-server/src/docs/upgrades/README.md` (format + template)
+- `mcp-server/src/docs/upgrades/0.26.0.md` (consolidated 0.21 → 0.26)
+- `mcp-server/src/docs/upgrades/<syncdb-version>.md` (owned by the migration IP; referenced here)
+- `docs/explanation/versioning-policy.md`
+- `docs/how-to/upgrade-terreno.md`
+- `.rulesync/skills/upgrading-terreno/SKILL.md`
+- `.rulesync/skills/upgrading-terreno/references/ordering.md`
+
+**Modify**
+
+- `mcp-server/src/tools.ts` (`terreno_get_upgrade_guide` empty-range response)
+- `mcp-server/src/prompts.ts` (`terreno_upgrade` prompt points at the skill)
+- `.rulesync/skills/release/SKILL.md`
+- `.github/workflows/repo-policies.yml`
+- `CHANGELOG.md` (link notes per version)
+- `docs/how-to/README.md`, `docs/explanation/README.md`
+
+## Task List
+
+See [`docs/tasks/upgrade-guides-and-skill.md`](../tasks/upgrade-guides-and-skill.md).
+
+## Acceptance Criteria
+
+- [ ] `mcp-server/src/docs/upgrades/README.md` defines the required note format with a template.
+- [ ] A consolidated note covers everything a consumer must know to move from 0.21.0 to 0.26.0, derived from real release notes and diffs.
+- [ ] `terreno_get_upgrade_guide` for the range 0.21.0 → current returns useful content, and for a range with no recorded notes returns an explicit "no notes recorded" message rather than empty output.
+- [ ] `docs/explanation/versioning-policy.md` states what lockstep versioning means, the pre-1.0 breaking-change policy, and the minimum deprecation window.
+- [ ] The `upgrading-terreno` skill exists with all mirrors committed and enforces a clean git tree before starting.
+- [ ] The skill follows the documented ordering, delegates the Expo SDK portion to `upgrading-expo`, and regenerates the typed client only after the backend is upgraded.
+- [ ] The skill runs compile, lint, and tests between phases and stops on first failure with the failing step named.
+- [ ] On a multi-version jump failure, the skill retries version by version to isolate the breaking version.
+- [ ] The release skill requires an upgrade note when the changelog section contains a breaking, deprecated, removed, or changed entry.
+- [ ] A CI check fails a release tag whose upgrade note is missing when required.
+- [ ] An upgrade of a real consumer app across at least two minor versions succeeds using only the skill, and the transcript is captured.
+- [ ] `bun run mcp:build`, `bun run lint`, and `bun run rules:check` pass.