@terreno/mcp 0.29.0 → 0.30.0

package/src/docs/versioned/0.29.0/tasks/public-roadmap-github.md

@@ -0,0 +1,112 @@
+# Task List: Public Roadmap on GitHub
+
+See: [`docs/implementationPlans/public-roadmap-github.md`](../implementationPlans/public-roadmap-github.md)
+
+**RTK deprecation flag:** None. Safe to implement before PR #869. One caveat: the `area:syncdb` label and the `syncdb` Area value assume PR #869 merges — create them anyway, they cost nothing.
+
+## Instructions for the implementing agent
+
+- Several tasks require GitHub UI or `gh` API calls that change repository state. The `gh` CLI available to cloud agents is **read-only**. For any task that mutates GitHub state (creating Discussion categories, Projects, labels, or repo settings), write the exact commands or UI steps into `docs/explanation/roadmap-process.md` under a "Maintainer setup" heading and mark the task as requiring a human. Do not attempt to fake completion.
+- Tasks that create files in the repo (`ROADMAP.md`, workflows, scripts, templates) are fully implementable — do those.
+- Run `bun run lint` before each commit. Run `bun run rules:check` if you touch `.rulesync/`.
+- Do not add new dependencies for YAML or GraphQL — use `fetch` and Bun's built-ins.
+
+## Phase 1: Discussions
+
+- [ ] **Task 1.1**: Document Discussion category setup
+  - Description: Create `docs/explanation/roadmap-process.md`. Start with a "Maintainer setup" section listing the seven Discussion categories from the IP with their exact names, formats (Announcement / Question-Answer / Open-ended), descriptions, and display order. For each, include the description text to paste into the GitHub UI (one to two sentences, written for outside users). Note that Discussions must first be enabled in Settings → General → Features.
+  - Files: `docs/explanation/roadmap-process.md` (new)
+  - Depends on: none
+  - Acceptance: all seven categories are listed with name, format, description, and order; the Announcements category is marked maintainers-only.
+
+- [ ] **Task 1.2**: Write the pinned intro posts
+  - Description: In `docs/explanation/roadmap-process.md`, add a "Pinned posts" section containing the full markdown body for one pinned post per category. Each should say what belongs there, what does not, and where to go instead. The Ideas post must explain that ideas are the intake funnel and that maintainers promote them to issues. The Agents & AI post must point at the MCP setup docs and the skills directory. The Q&A post must link `docs/how-to/` and note that recurring questions become how-to guides.
+  - Files: `docs/explanation/roadmap-process.md`
+  - Depends on: Task 1.1
+  - Acceptance: seven post bodies exist, each under 200 words, each naming an alternative destination for off-topic content.
+
+- [ ] **Task 1.3**: Add Discussion templates
+  - Description: Create `.github/DISCUSSION_TEMPLATE/rfc.yml` with fields: title guidance, Summary (required), Motivation (required), Detailed design (required), Alternatives considered (required), Drawbacks, Unresolved questions, and a checkbox acknowledging that accepted RFCs become IPs in `docs/implementationPlans/`. Create `.github/DISCUSSION_TEMPLATE/ideas.yml` with: Problem you are hitting (required), What you tried, Rough idea for a solution, and Would you be willing to help implement. Both must set the correct `labels:` and target the right category via the filename convention.
+  - Files: `.github/DISCUSSION_TEMPLATE/rfc.yml` (new), `.github/DISCUSSION_TEMPLATE/ideas.yml` (new)
+  - Depends on: Task 1.1
+  - Acceptance: both files parse as valid YAML and use GitHub's discussion form schema (`body` with `type: textarea` / `type: checkboxes`); the RFC template mentions the IP graduation path.
+
+## Phase 2: Project board
+
+- [ ] **Task 2.1**: Document Project board setup
+  - Description: Add a "Project board" section to `docs/explanation/roadmap-process.md` specifying: the Project name (`Terreno Roadmap`), whether it is repo- or org-level, the six fields with their exact types and option values from the IP, and the four views with their layout, grouping, and filters. Include the `gh project` commands a maintainer can run for the parts the CLI supports, and mark the rest as UI-only.
+  - Files: `docs/explanation/roadmap-process.md`
+  - Depends on: Task 1.1
+  - Acceptance: all six fields and four views are specified precisely enough to recreate without further decisions; option values match the IP tables exactly.
+
+- [ ] **Task 2.2**: Write the tracking-issue bodies for this program's IPs
+  - Description: Create `docs/explanation/roadmap-seed-issues.md` containing one ready-to-paste issue body per IP listed in `docs/implementationPlans/oss-launch-program.md`. Each body must include: a one-paragraph summary written for an outside reader (not internal shorthand), a link to the IP file, a link to the task file, the RTK deprecation flag, the dependencies, and the labels and Project field values to set (`Area`, `Target`, `Impact`, `IP`). Read each IP file to write its summary — do not paraphrase from the program index alone.
+  - Files: `docs/explanation/roadmap-seed-issues.md` (new)
+  - Depends on: Task 2.1
+  - Acceptance: one section per IP in the program index; every section names its `Area`, `Target`, `Impact`, and `IP` field values; every summary is comprehensible without reading the IP.
+
+## Phase 3: Labels and triage
+
+- [ ] **Task 3.1**: Define the label set as data
+  - Description: Create `.github/labels.yml` listing every label from the IP taxonomy with `name`, `color`, and `description`. Use a consistent color family per prefix (for example one hue for `area:`, another for `type:`, another for `status:`, and distinct colors for the bare labels). Add a "Labels" section to `docs/explanation/roadmap-process.md` explaining that `.github/labels.yml` is the source of truth and how to apply it (`gh label create` loop or a label-sync action), plus which GitHub default labels to delete.
+  - Files: `.github/labels.yml` (new), `docs/explanation/roadmap-process.md`
+  - Depends on: Task 1.1
+  - Acceptance: `.github/labels.yml` parses as valid YAML and contains every label in the IP taxonomy table with no duplicates; colors are valid six-digit hex without `#`.
+
+- [ ] **Task 3.2**: Add the triage workflow
+  - Description: Create `.github/workflows/triage.yml`. On `issues: [opened]`, add the `status:needs-triage` label. Then read the issue body for the package dropdown value rendered by the issue forms and map it to the matching `area:*` label (for example `@terreno/api` → `area:api`, `docs` → `area:docs`). Implement the mapping in an inline `actions/github-script` step with an explicit lookup object; if no match is found, add no area label and leave a comment asking the reporter to specify. Validate required inputs before use per the repo convention.
+  - Files: `.github/workflows/triage.yml` (new)
+  - Depends on: Task 3.1
+  - Acceptance: workflow parses as valid YAML; the mapping object covers every option in `bug_report.yml`'s package dropdown; the no-match path does not throw.
+
+- [ ] **Task 3.3**: Document the backfill triage pass
+  - Description: Add a "One-time backfill" section to `docs/explanation/roadmap-process.md` describing how to triage existing open issues and PRs onto the new taxonomy: run `gh issue list --state open --limit 200 --json number,title,labels`, assign one `area:` and one `type:` label each, add anything still relevant to the board with `Status = Inbox`, and close or label `status:wontfix` anything stale beyond six months. Include the read-only `gh` commands for producing the working list.
+  - Files: `docs/explanation/roadmap-process.md`
+  - Depends on: Task 3.1
+  - Acceptance: the section gives a repeatable procedure and the exact `gh` command for listing candidates; it does not claim the backfill has been done.
+
+## Phase 4: Roadmap generation
+
+- [ ] **Task 4.1**: Write the roadmap generator
+  - Description: Create `scripts/generate-roadmap.ts` (Bun, TypeScript, `const` arrow functions with explicit return types, no new dependencies). It queries the GitHub GraphQL API for the `Terreno Roadmap` ProjectV2 items and their field values, then writes `ROADMAP.md`: a header explaining that the board is the source of truth and that no dates are promised, then sections grouped by `Target` (current release first, then `Next`, then `Future`), and within each, subsections by `Area`. Each item renders as a bullet with its title, issue link, `Impact`, and an IP link when the `IP` field is set. Exclude items with `Status` of `Declined`. Read the token from `GITHUB_TOKEN` and the project number from `TERRENO_PROJECT_NUMBER`; fail with a clear message listing missing variables when either is absent. Use Luxon for the generated-at timestamp.
+  - Files: `scripts/generate-roadmap.ts` (new), `package.json` (add a `roadmap:generate` script)
+  - Depends on: Task 2.1
+  - Acceptance: running with both env vars unset prints an error naming both and exits non-zero; with a valid token it writes a `ROADMAP.md` matching the described structure; `bun run lint` passes.
+
+- [ ] **Task 4.2**: Add the roadmap workflow
+  - Description: Create `.github/workflows/roadmap-generate.yml` running on `schedule` (daily) and `workflow_dispatch`. Validate `GITHUB_TOKEN`/PAT and `TERRENO_PROJECT_NUMBER` at job start with the repo's fail-fast pattern. Run `bun run roadmap:generate`, then commit and push `ROADMAP.md` only if `git diff --quiet` reports changes. Use a bot identity for the commit.
+  - Files: `.github/workflows/roadmap-generate.yml` (new)
+  - Depends on: Task 4.1
+  - Acceptance: workflow parses as valid YAML; the secret-validation step lists every required variable; the commit step is conditional on a real diff.
+
+- [ ] **Task 4.3**: Seed `ROADMAP.md` and link it
+  - Description: Commit an initial hand-written `ROADMAP.md` (the generator will overwrite it later) built from the IPs in `docs/implementationPlans/oss-launch-program.md` plus the active plans in `PLAN_INDEX.md`. Add a note at the top that it is generated from the Project board. Link it from `README.md` and add it to the docs site sidebar in `website/docusaurus.config.ts` (or the sidebars file if navigation is defined there — check both).
+  - Files: `ROADMAP.md` (new), `README.md`, `website/docusaurus.config.ts` or `website/sidebars.ts`
+  - Depends on: Task 4.1
+  - Acceptance: `ROADMAP.md` lists every IP in the program with a `Target`; the docs site builds (`bun run website:build`) with the new nav entry; the README links it.
+
+- [ ] **Task 4.4**: Add the docs feedback footer link
+  - Description: In `website/docusaurus.config.ts`, add a footer link (or theme config item) pointing at the Docs feedback Discussions category. If Docusaurus's `editUrl` mechanism is the better fit for per-page feedback, add the discussion link alongside the existing `editUrl` rather than replacing it.
+  - Files: `website/docusaurus.config.ts`
+  - Depends on: Task 1.1
+  - Acceptance: `bun run website:build` succeeds and the built output contains the discussions URL; the existing `editUrl` still works.
+
+## Phase 5: Linear bridge
+
+- [ ] **Task 5.1**: Document the Linear bridge rules
+  - Description: Add a "Linear bridge" section to `docs/explanation/roadmap-process.md` covering: which artifacts live where (GitHub = public discussion, issues, roadmap state; Linear = sprint execution; `docs/implementationPlans/` = design), the one-way GitHub → Linear intake triggered by the `tracked` label, the rule that Linear status is not synced back and that GitHub state changes via `Fixes #NNN` on merge, how internally-originated public work gets a manual GitHub issue, and an explicit statement that internal-only Linear work is never mirrored. Explain *why* status is not two-way synced.
+  - Files: `docs/explanation/roadmap-process.md`
+  - Depends on: Task 3.1
+  - Acceptance: the section states the direction of every sync, names the trigger label, and gives the reason two-way status sync was rejected.
+
+- [ ] **Task 5.2**: Document the intake flow in `CONTRIBUTING.md`
+  - Description: Add a "How work gets planned" section to `CONTRIBUTING.md`, under 30 lines: file an Ideas discussion → maintainer promotes to an issue → issue is triaged onto the roadmap board → substantial work gets an IP → implementation. Add the RFC path for public API changes and new packages. Link `ROADMAP.md`, the Discussions categories, and `docs/implementationPlans/README.md`.
+  - Files: `CONTRIBUTING.md`
+  - Depends on: Task 5.1
+  - Acceptance: the section is under 30 lines, links all three destinations, and matches the flow diagram in the IP.
+
+- [ ] **Task 5.3**: Add the release announcement step
+  - Description: Edit `.rulesync/skills/release/SKILL.md` to add a step: after publishing a release that includes breaking changes or deprecations, post a discussion in the Announcements category summarizing the change, linking the changelog section and the relevant upgrade note in `mcp-server/src/docs/upgrades/`. Regenerate mirrors with `bun run rules`.
+  - Files: `.rulesync/skills/release/SKILL.md` plus generated mirrors
+  - Depends on: Task 1.1
+  - Acceptance: `bun run rules:check` exits 0; the release skill names the Announcements category and the upgrade-note path.

package/src/docs/versioned/0.29.0/tasks/rtk-to-syncdb-migration-docs.md

@@ -0,0 +1,163 @@
+# Task List: RTK Deprecation and SyncDB Migration Docs
+
+See: [`docs/implementationPlans/rtk-to-syncdb-migration-docs.md`](../implementationPlans/rtk-to-syncdb-migration-docs.md)
+
+**RTK deprecation flag:** **Blocked.** Do not start any task in this file until PR [#869](https://github.com/flourishhealth/terreno/pull/869) is merged into `master`. Verify with `git log --oneline master | rg -i syncdb` before beginning.
+
+## Instructions for the implementing agent
+
+- **Phase 1 is mandatory and gates everything else.** Do not write a single line of documentation before completing Task 1.1 and Task 1.2. The surface map in the IP was written before #869 merged and is a hypothesis, not a fact.
+- Never document an API you have not seen in `syncdb/src/index.ts` (or wherever the merged package exports from). If the IP describes something that does not exist, correct the IP in the same PR and note the correction.
+- Every code sample must be copied from working code (`example-frontend`, `syncdb/src/**/*.test.ts`, or a snippet you compiled) — never invented.
+- Do not change `@terreno/syncdb` or `@terreno/rtk` source behavior. Adding a deprecation notice to `rtk/README.md` is allowed; changing `rtk/src/` is not.
+- Run `bun run lint`, `bun run compile`, and `bun run website:build` before each commit. Run `bun run rules:check` after touching `.rulesync/`.
+
+## Phase 1: Reconcile with merged #869
+
+- [ ] **Task 1.1**: Inventory the merged syncdb public API
+  - Description: Read the merged `syncdb/src/index.ts` and every module it re-exports. Produce `docs/implementationPlans/syncdb-api-inventory.md` (a temporary working document, deleted in Task 6.6) listing every exported symbol with its signature, a one-line description, and the source file. Separately list: the client config options, every React hook, every client method, the conflict-resolution API, the sync-status API, and the codegen CLI surface. Also record whether local-first is the only mode or an opt-in (IP blocking question M7) and whether `bun run sdk` still works (M5).
+  - Files: `docs/implementationPlans/syncdb-api-inventory.md` (new, temporary)
+  - Depends on: PR #869 merged
+  - Acceptance: every symbol in the inventory is greppable in `syncdb/src/`; M5 and M7 are answered with a file-and-line citation.
+
+- [ ] **Task 1.2**: Correct the IP surface map against reality
+  - Description: Compare the inventory from Task 1.1 to the "Documentation surface map" and "Known RTK-shaped surfaces" tables in the IP and in `docs/implementationPlans/oss-launch-program.md`. Update both files where reality differs. Add rows for any surface #869 introduced that neither table anticipated (for example new socket events, new backend routes under `api/src/sync/`, `excludeArchivedPlugin`, tenant/organization permission helpers). Report the deltas in the PR body.
+  - Files: `docs/implementationPlans/rtk-to-syncdb-migration-docs.md`, `docs/implementationPlans/oss-launch-program.md`
+  - Depends on: Task 1.1
+  - Acceptance: both surface maps match the merged code; every added row cites a file path; the PR body lists what changed from the pre-merge hypothesis.
+
+- [ ] **Task 1.3**: Capture the reference migration from #869
+  - Description: `git log` the #869 merge and extract the diff for `example-frontend` — the actual RTK → syncdb migration of the todos flow. Save the before/after pairs (store setup, one read hook, one write hook, conflict UI, sync status UI) into the working inventory doc. These become the code samples for the migration guide. Note anything the reference migration did *not* cover (auth, feature flags, other screens).
+  - Files: `docs/implementationPlans/syncdb-api-inventory.md`
+  - Depends on: Task 1.1
+  - Acceptance: at least five before/after pairs captured with file paths and commit SHA; gaps in the reference migration are listed explicitly.
+
+## Phase 2: Reference documentation
+
+- [ ] **Task 2.1**: Write `docs/reference/syncdb.md`
+  - Description: New reference page following the structure of `docs/reference/rtk.md` (read it first for tone and section ordering). Sections: installation and peer dependencies; `createSyncDbClient` config table (every option, type, default, description); provider setup; read hooks; mutation hooks; conflict API; sync-status API; the Redux bridge if it shipped; codegen; environment variables. Every option in the config table must come from the inventory. Include a runnable example per hook.
+  - Files: `docs/reference/syncdb.md` (new)
+  - Depends on: Task 1.1
+  - Acceptance: every documented symbol exists in the inventory; every config option lists a type and default; no `TODO` or placeholder text remains.
+
+- [ ] **Task 2.2**: Remove `rtk.md` from the public reference index
+  - Description: Per IP decision M4 (P7 A), remove `docs/reference/rtk.md` from the public reference tree — do **not** maintain a parallel RTK reference page at launch. Add a Docusaurus redirect from the old URL to `docs/how-to/migrate-rtk-to-syncdb.md`. Archive the pre-launch `rtk.md` content only if inbound links require it (e.g. under `docs/reference/legacy/` with a deprecation banner), but do not list it in `docs/reference/README.md`.
+  - Files: `docs/reference/rtk.md` (removed or archived), `website/docusaurus.config.ts`, `docs/reference/README.md`
+  - Depends on: Task 2.1
+  - Acceptance: `docs/reference/README.md` has no RTK entry; the old URL redirects to the migration guide; no launch doc presents RTK as a supported reference path.
+
+- [ ] **Task 2.3**: Update the reference and docs indexes
+  - Description: Update `docs/reference/README.md` and `docs/README.md`: add `@terreno/syncdb` and `@terreno/ai` to the package table (`ai` is currently missing entirely), add `@terreno/admin-spa` and `@terreno/feature-flags` if absent. Do **not** list `rtk` in the public reference index per M4 — link the migration guide from a "Migrating from RTK" note instead. Confirm every shipped package in `publish-on-tag.yml` appears exactly once in the appropriate section.
+  - Files: `docs/reference/README.md`, `docs/README.md`
+  - Depends on: Task 2.2
+  - Acceptance: the package table contains one row per published package; `rtk` appears only under Legacy; every link resolves.
+
+## Phase 3: Migration guide
+
+- [ ] **Task 3.1**: Draft the migration guide skeleton with verified samples
+  - Description: Create `docs/how-to/migrate-rtk-to-syncdb.md` with the eleven sections from the IP. Populate sections 2–4 (install/configure, reads, writes) using the before/after pairs captured in Task 1.3. For section 4, explicitly list the RTK-era code that should be **deleted** after migrating (manual optimistic updates, `isLoading` spinners on writes, refetch-after-mutate patterns) — this is the part consumers get wrong.
+  - Files: `docs/how-to/migrate-rtk-to-syncdb.md` (new)
+  - Depends on: Task 1.3, Task 2.1
+  - Acceptance: sections 1–4 complete; every code block traceable to a real file; section 4 has a "delete this" list.
+
+- [ ] **Task 3.2**: Document conflicts and sync status
+  - Description: Complete sections 5 and 6. Explain what a conflict is in this system, exactly when one is produced (cite the server-side 409/nack path in `api/src/sync/`), the two v1 resolution strategies, and the minimum UI a consumer must build. For sync status, show how to replace request-level loading UX with sync-state UX. Use the `example-frontend` implementation as the reference; if it has no conflict UI, say so and link a follow-up issue rather than inventing one.
+  - Files: `docs/how-to/migrate-rtk-to-syncdb.md`
+  - Depends on: Task 3.1
+  - Acceptance: the conflict trigger is cited to a source file; both strategies documented; the minimum-UI requirement is concrete (named components or hooks).
+
+- [ ] **Task 3.3**: Document the auth migration
+  - Description: Complete section 7. Cover: `generateAuthSlice` → Better Auth session, token storage differences on native versus web, the socket auth handshake changes from #869 (pluggable socket auth, Better Auth bearer sessions, session revalidation, `sync:auth-expired`), required backend config (`BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `trustedOrigins`), and the cross-domain cookie requirements. State clearly that auth can be migrated *before* the data layer (IP question M3) and give the two-step order.
+  - Files: `docs/how-to/migrate-rtk-to-syncdb.md`
+  - Depends on: Task 3.2
+  - Acceptance: every env var named exists in `docs/reference/environment-variables.md` after this IP; the `sync:auth-expired` event is cited to source; the two-step order is stated in the first paragraph of the section.
+
+- [ ] **Task 3.4**: Document codegen, feature flags, rollback, and the checklist
+  - Description: Complete sections 8–11. Codegen: whether `bun run sdk` is unchanged (answer from Task 1.1), what the generated file looks like now, and the update to `openapi-config.ts`. Feature flags: how the OpenFeature provider is fed post-migration. Rollback: per-screen rollback via `USE_SYNCDB` and what state is left behind (IndexedDB contents, outbox entries) when rolling back. Checklist: a copy-pasteable ordered checklist covering everything in sections 1–10.
+  - Files: `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/how-to/README.md`
+  - Depends on: Task 3.3
+  - Acceptance: all eleven sections complete; the rollback section states what local data survives; the checklist has no step absent from the body; the guide is listed in `docs/how-to/README.md`.
+
+- [ ] **Task 3.5**: Validate the guide by performing the migration
+  - Description: On a scratch branch, take a screen in `example-frontend` that #869 did **not** migrate and migrate it following only the guide. Record every point where the guide was insufficient. Fix the guide. Then revert the scratch branch — the migration itself is not part of this IP's deliverable, only the guide corrections are.
+  - Files: `docs/how-to/migrate-rtk-to-syncdb.md`
+  - Depends on: Task 3.4
+  - Acceptance: the migrated screen compiles and works locally; every gap found is fixed in the guide; the scratch migration is not committed to this branch.
+
+## Phase 4: Explainers and auth repositioning
+
+- [ ] **Task 4.1**: Write `docs/explanation/local-first-data.md`
+  - Description: Conceptual explainer, no step-by-step. Cover: what local-first means here (local DB is the UI source of truth, server is the authority), the mental-model shift from request/response to apply-locally-then-reconcile, what the developer stops having to think about (loading states on writes, manual optimistic updates, refetch orchestration), what they must newly think about (conflicts, sync status, encryption at rest, key lifecycle on logout), and the tradeoffs versus server-first fetching. Link the migration guide and the syncdb reference.
+  - Files: `docs/explanation/local-first-data.md` (new)
+  - Depends on: Task 2.1
+  - Acceptance: no shell commands or step lists; names at least three things developers stop doing and three they start doing; linked from `docs/explanation/README.md` if one exists.
+
+- [ ] **Task 4.2**: Reposition authentication documentation
+  - Description: Rewrite `docs/explanation/authentication.md` so Better Auth is the primary path and JWT/Passport is described as legacy with its support status. Update `docs/how-to/configure-better-auth.md` to drop "optional"/"alternative" framing and present it as the default setup. Add a short decision section: when a consumer would still choose JWT (existing deployment, custom token requirements). Verify every claim against `api/src/betterAuth*.ts` and the #869 socket auth changes.
+  - Files: `docs/explanation/authentication.md`, `docs/how-to/configure-better-auth.md`
+  - Depends on: Task 3.3
+  - Acceptance: Better Auth appears before JWT in both documents; the JWT section states its support status; every config option cited exists in `api/src/betterAuth.ts`.
+
+## Phase 5: Agent surfaces
+
+- [ ] **Task 5.1**: Add syncdb agent rules and mark RTK rules legacy
+  - Description: Create `.rulesync/rules/syncdb/00-syncdb.md` following the structure of `.rulesync/rules/rtk/00-rtk.md` (commands, architecture, key exports, usage patterns, conventions, testing). Add a legacy banner to the top of the RTK rule file stating that new code must use syncdb and that the RTK rules exist only for maintaining existing consumers. Run `bun run rules` and commit all mirrors.
+  - Files: `.rulesync/rules/syncdb/00-syncdb.md` (new), `.rulesync/rules/rtk/00-rtk.md`, generated mirrors
+  - Depends on: Task 2.1
+  - Acceptance: `bun run rules:check` exits 0; the syncdb rule documents only APIs from the inventory; the RTK rule's first line marks it legacy.
+
+- [ ] **Task 5.2**: Update the SDK codegen skill
+  - Description: Rewrite `.rulesync/skills/generate-sdk/SKILL.md` for the syncdb codegen path. Keep an explicitly-labeled legacy branch for consumers still on RTK during the support window. Update the trigger description, the prerequisite list, the command, the output file path, and the "never edit the generated file" warning to name the correct file. Regenerate mirrors.
+  - Files: `.rulesync/skills/generate-sdk/SKILL.md`, generated mirrors
+  - Depends on: Task 3.4
+  - Acceptance: the skill's primary path produces a working generated file when run against `example-backend`; the legacy branch is clearly labeled; `bun run rules:check` exits 0.
+
+- [ ] **Task 5.3**: Update root agent context files
+  - Description: Update `AGENTS.md`, `CLAUDE.md`, and `CLAUDE-consumer.md`: replace the `@terreno/rtk` package description and the "always use generated SDK hooks" guidance with the syncdb equivalent, update the architecture diagram, and add a short legacy note pointing at the migration guide. Do not change unrelated sections. Note that `CLAUDE.local.md` also contains a stale copy — either update or delete it (it appears to be an outdated duplicate; confirm before deleting).
+  - Files: `AGENTS.md`, `CLAUDE.md`, `CLAUDE-consumer.md`, possibly `CLAUDE.local.md`
+  - Depends on: Task 5.1
+  - Acceptance: no root agent file instructs writing RTK Query code for new work; the architecture diagram names syncdb; `bun run rules:check` exits 0.
+
+- [ ] **Task 5.4**: Update MCP resources and bootstrap templates
+  - Description: Update `mcp-server/src/docs/resources/*.md` (the `terreno://docs/rtk` resource and the patterns/overview bundles) and every file under `mcp-server/src/docs/templates/bootstrap/` that wires the Redux store, auth slice, or RTK hooks. A bootstrapped app must run on syncdb + Better Auth. Also check `mcp-server/src/prompts.ts` for RTK-specific prompt text.
+  - Files: `mcp-server/src/docs/resources/*.md`, `mcp-server/src/docs/templates/bootstrap/**`, `mcp-server/src/prompts.ts`
+  - Depends on: Task 5.1
+  - Acceptance: `terreno_bootstrap_app` output contains no RTK Query wiring; a bootstrapped app installs, compiles, and boots; `bun run mcp:build` succeeds.
+
+## Phase 6: Deprecation signalling
+
+- [ ] **Task 6.1**: Add the deprecation notice to `rtk/README.md`
+  - Description: Add a notice block at the very top of `rtk/README.md`: deprecated as of version X, supported through version Y, superseded by `@terreno/syncdb`, link the migration guide. Do not remove existing content.
+  - Files: `rtk/README.md`
+  - Depends on: Task 2.2
+  - Acceptance: the notice is the first content after the title; versions are concrete, not placeholders.
+
+- [ ] **Task 6.2**: Add the changelog entry
+  - Description: Add a `Deprecated` entry to the root `CHANGELOG.md` under the release that includes #869, naming `@terreno/rtk`, the support window, and the migration guide link. Add the corresponding `Added` entry for `@terreno/syncdb`.
+  - Files: `CHANGELOG.md`
+  - Depends on: Task 6.1
+  - Acceptance: both entries exist under the correct version heading; the migration guide link resolves.
+
+- [ ] **Task 6.3**: Write the upgrade note
+  - Description: Create `mcp-server/src/docs/upgrades/<version>.md` for the release containing #869, following the format of the existing `0.20.0.md` and `0.21.0.md` notes. Include: what changed, whether action is required, the auth-then-data migration order, links to the migration guide, and before/after snippets for the two most common changes (a read hook and a write hook).
+  - Files: `mcp-server/src/docs/upgrades/<version>.md` (new)
+  - Depends on: Task 3.4
+  - Acceptance: `terreno_get_upgrade_guide` with a range spanning this version returns the note; the format matches the existing notes.
+
+- [ ] **Task 6.4**: Draft the announcement post
+  - Description: Add the announcement body to `docs/explanation/roadmap-process.md` under a "Drafted announcements" heading (or to a new `docs/explanation/announcements/rtk-deprecation.md` if that file does not exist yet). It should explain to outside users what changed, why local-first, what they must do and by when, and where to ask questions. Under 400 words. Do not post it — posting is a maintainer action.
+  - Files: `docs/explanation/roadmap-process.md` or `docs/explanation/announcements/rtk-deprecation.md`
+  - Depends on: Task 6.2
+  - Acceptance: under 400 words; names the support window; links the migration guide and the Q&A discussion category.
+
+- [ ] **Task 6.5**: Update the README architecture and package list
+  - Description: Update `README.md`: replace `@terreno/rtk` with `@terreno/syncdb` in the architecture diagram and the published-packages list, keeping `rtk` listed with a `(deprecated)` marker. Update the "Integration Flow" numbered list to describe the syncdb loop. Do not make positioning changes here — those belong to [`positioning-django-rails-universal`](../implementationPlans/positioning-django-rails-universal.md).
+  - Files: `README.md`
+  - Depends on: Task 6.1
+  - Acceptance: the diagram names syncdb; `rtk` is marked deprecated; the integration flow describes local-first reads and writes; no positioning prose changed.
+
+- [ ] **Task 6.6**: Delete the working inventory document
+  - Description: Confirm every fact from `docs/implementationPlans/syncdb-api-inventory.md` has landed in `docs/reference/syncdb.md` or the migration guide, then delete the working file. It is scaffolding, not a deliverable.
+  - Files: `docs/implementationPlans/syncdb-api-inventory.md` (deleted)
+  - Depends on: all Phase 2–5 tasks
+  - Acceptance: the file no longer exists; no other document links to it.

package/src/docs/versioned/0.29.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
+
+- [ ] **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/src/docs/versioned/0.29.0/tasks/web-ssr-and-admin-spa.md

@@ -0,0 +1,155 @@
+# Task List: Server-Side Rendering for Universal Web (and Admin SPA)
+
+See: [`docs/implementationPlans/web-ssr-and-admin-spa.md`](../implementationPlans/web-ssr-and-admin-spa.md)
+
+**RTK deprecation flag:** **Partial.** Phase 0 must run after PR #869 merges, because whether the local-first client can be kept out of the server render path is the main feasibility question. Tasks marked `[RTK]` touch the data layer directly.
+
+**Prerequisite:** Expo SDK ≥ 55. The repo catalog is on `~54.0.29`; PR [#779](https://github.com/flourishhealth/terreno/pull/779) upgrades to SDK 56. Verify the merged Expo version before starting and stop if it is below 55.
+
+## Instructions for the implementing agent
+
+- **Phase 0 is a gate, not a formality.** If the spike shows that `static` output cannot work without unreasonable changes, write the report, update the IP with the finding, and stop. A well-documented no-go is a successful outcome for Phase 0.
+- Do not modify `@terreno/ui` component behavior to make SSR work. If a component needs a browser API, guard the access; do not change what it renders in the browser.
+- Every SSR-safety fix needs a test that fails before the fix.
+- Server rendering is **alpha** in Expo SDK 55+. Treat upstream bugs as expected; record them with links rather than working around them silently.
+- Run `bun run compile`, `bun run lint`, and `bun run ui:test` before each commit.
+
+## Phase 0: Feasibility spike
+
+- [ ] **Task 0.1**: Verify prerequisites
+  - Description: Confirm the Expo version in the root `package.json` catalog is ≥ 55 and that PR #869 is merged. Record both. If Expo is below 55, stop and report that this IP is blocked on PR #779. Read the current Expo documentation for `web.output` modes and server rendering and record the alpha status and any stated limitations.
+  - Files: none (findings in the PR body)
+  - Depends on: PR #779 and PR #869 merged
+  - Acceptance: both versions recorded with citations; the upstream alpha status and its documented limitations are captured; a stop decision is made explicitly if prerequisites are unmet.
+
+- [ ] **Task 0.2**: Attempt `static` output on `example-frontend`
+  - Description: On a scratch branch, set `web.output` to `static` in `example-frontend`'s app config and run the web export. Record every error and warning in full. For each failure, identify the root cause: a `@terreno/ui` component touching a browser global, a native-only import, a font-loading issue, a provider issue, or the syncdb client initializing at module scope. Do not fix anything yet — the goal is a complete inventory of the work.
+  - Files: none (scratch branch, not committed)
+  - Depends on: Task 0.1
+  - Acceptance: the export was attempted and every failure captured verbatim with its root cause classified; the scratch branch is not merged.
+
+- [ ] **Task 0.3**: `[RTK]` Determine whether the syncdb client can be excluded from server render
+  - Description: The syncdb client depends on IndexedDB and Web Crypto, neither of which exists on the server. Read the merged syncdb client initialization code and determine: whether it initializes at module scope or on provider mount, whether it already guards for a non-browser environment, and what would be required to make it a no-op during server render while hydrating correctly on the client. This is the highest-risk unknown in the IP. Write the finding with file citations.
+  - Files: none (findings in the PR body)
+  - Depends on: Task 0.2
+  - Acceptance: the initialization path is traced with file and line citations; a concrete answer is given on whether exclusion is possible and what it costs; if it is not possible without syncdb changes, that requirement is written up as a dependency.
+
+- [ ] **Task 0.4**: Write the feasibility report and go/no-go
+  - Description: Create `docs/implementationPlans/web-ssr-feasibility.md` containing: the prerequisite state, the full failure inventory from Task 0.2 classified by root cause with an effort assessment per class, the syncdb finding from Task 0.3, the risks that turned out to be real versus imagined against the IP's risk table, and an explicit recommendation — proceed with `static`, proceed with `static` and `server`, defer, or abandon with reasons. Update the IP's risk table and phases to match reality.
+  - Files: `docs/implementationPlans/web-ssr-feasibility.md` (new), `docs/implementationPlans/web-ssr-and-admin-spa.md`
+  - Depends on: Task 0.3
+  - Acceptance: the report contains an unambiguous recommendation; the IP's risk table is corrected against what was actually observed; every subsequent phase is either confirmed, rescoped, or cancelled in the IP.
+
+## Phase 1: SSR-safety audit and fixes
+
+- [ ] **Task 1.1**: Build a server-render test harness
+  - Description: Create `ui/src/__tests__/serverRender.test.tsx` that renders components with `react-dom/server`'s `renderToString` (or the equivalent supported path for `react-native-web`) in an environment where `window`, `document`, and `localStorage` are undefined. The harness should iterate every component exported from `ui/src/index.tsx` and assert each renders without throwing. Components that legitimately cannot render without a browser get an explicit allowlist entry with a comment explaining why — the allowlist is the audit output.
+  - Files: `ui/src/__tests__/serverRender.test.tsx` (new)
+  - Depends on: Task 0.4 (go decision)
+  - Acceptance: the harness covers every export from `ui/src/index.tsx`; failures are listed rather than skipped; the allowlist has a justification per entry; `bun run ui:test` runs it.
+
+- [ ] **Task 1.2**: Fix SSR-unsafe components
+  - Description: For each failure the harness finds, guard the browser-API access rather than changing render output. Follow the existing precedent in the repo (the client storage layer's `typeof window` checks). Do not change any component's browser behavior. Each fix must make a previously-failing harness case pass, and no existing `@terreno/ui` test may change behavior.
+  - Files: `ui/src/**`
+  - Depends on: Task 1.1
+  - Acceptance: the harness passes with an allowlist containing only genuinely browser-dependent components; `bun run ui:test` passes with no changed assertions in existing tests; browser behavior is unchanged (verified by the existing test suite).
+
+- [ ] **Task 1.3**: Verify theme and font determinism
+  - Description: Render a component tree wrapped in `TerrenoProvider` twice in the server harness and assert identical output, proving theme resolution is deterministic. Check the font-loading path for anything that would differ between server and client render. Fix any non-determinism (for example a value derived from the current time or a random id) and add the test.
+  - Files: `ui/src/__tests__/serverRender.test.tsx`, `ui/src/Theme.tsx` or `ui/src/TerrenoProvider.tsx` if a fix is needed
+  - Depends on: Task 1.2
+  - Acceptance: two server renders of the same tree produce byte-identical output; any non-determinism found is fixed and covered by the test.
+
+- [ ] **Task 1.4**: `[RTK]` Guard the data-layer client against server render
+  - Description: Implement the exclusion determined in Task 0.3 so the syncdb client does not initialize during server render, and hydrates normally on the client. Add a test asserting that importing and rendering the provider in the server harness does not attempt IndexedDB or Web Crypto access. If Task 0.3 concluded this requires changes inside `@terreno/syncdb`, make the minimal change there with its own test.
+  - Files: `syncdb/src/**` and/or the provider wiring, plus tests
+  - Depends on: Task 1.3, Task 0.3
+  - Acceptance: the server harness renders the provider without touching IndexedDB or Web Crypto; the client still initializes correctly in the browser (verified by an existing or new client-side test); `bun run compile` passes.
+
+## Phase 2: `static` output for `admin-spa`
+
+- [ ] **Task 2.1**: Add output-mode support to the admin serve plugin
+  - Description: Locate `AdminSpaServeApp` (confirm the file path — it is registered in `example-backend/src/server.ts`) and add support for serving a `static`-output build: per-route HTML files rather than a single `index.html` fallback. The existing `single`-output behavior must remain the default and continue working unchanged so consumers upgrading Terreno without rebuilding their admin are unaffected. Add tests for both modes, including the fallback behavior for unknown routes.
+  - Files: the `AdminSpaServeApp` source file, tests
+  - Depends on: Task 1.2
+  - Acceptance: both output modes serve correctly; `single` remains the default; a request for an unknown route behaves correctly in each mode; tests cover both.
+
+- [ ] **Task 2.2**: Build `admin-spa` with `static` output
+  - Description: Change `admin-spa`'s app config to `static` output and build it. Fix whatever breaks in `admin-spa/src/**` following the same guard-rather-than-change discipline from Phase 1. Verify every admin route produces an HTML file and that the app still functions after hydration — list models, open a form, save a record.
+  - Files: `admin-spa/app.json` or `admin-spa/app.config.ts`, `admin-spa/src/**`
+  - Depends on: Task 2.1
+  - Acceptance: the build produces per-route HTML; every admin route loads; list, form, and save all work after hydration; no hydration mismatch warnings in the console.
+
+- [ ] **Task 2.3**: Update the admin integration workflow
+  - Description: Update `.github/workflows/admin-spa-integration.yml` to build and exercise the `static` output. If the workflow currently asserts single-`index.html` behavior, extend it to cover both modes rather than replacing the existing coverage.
+  - Files: `.github/workflows/admin-spa-integration.yml`
+  - Depends on: Task 2.2
+  - Acceptance: the workflow passes; both output modes are exercised; existing coverage is retained.
+
+## Phase 3: `static` output for `example-frontend`
+
+- [ ] **Task 3.1**: Switch `example-frontend` to `static` output
+  - Description: Set `web.output` to `static`, build, and fix remaining failures. Verify every route produces HTML with meaningful content by fetching each route with JavaScript disabled and confirming visible text is present in the response body — not just an empty shell. Confirm no hydration mismatch warnings appear on any route.
+  - Files: `example-frontend/app.json`, `example-frontend/**` as needed
+  - Depends on: Task 1.4, Task 2.2
+  - Acceptance: every route returns HTML containing meaningful content with JavaScript disabled; no hydration warnings on any route; the app functions normally with JavaScript enabled.
+
+- [ ] **Task 3.2**: Update the frontend deploy workflow and hosting config
+  - Description: Update `.github/workflows/frontend-example-deploy.yml` and the hosting configuration for the new output shape. `static` output produces per-route HTML, so the SPA-fallback rewrite that `single` required may now be wrong for some paths — verify the host's routing behavior and adjust. Update `example-frontend/vercel.json` from [`deploy-to-vercel`](../implementationPlans/deploy-to-vercel.md) if its rewrites conflict with per-route HTML.
+  - Files: `.github/workflows/frontend-example-deploy.yml`, `example-frontend/vercel.json`, hosting config
+  - Depends on: Task 3.1
+  - Acceptance: the deployed example serves per-route HTML; deep links resolve; the SPA-fallback rewrite no longer shadows real route files; the deploy workflow passes.
+
+## Phase 4: `server` output with the Express adapter
+
+- [ ] **Task 4.1**: Prototype the Express adapter inside `@terreno/api`
+  - Description: Only if Task 0.4 recommended proceeding to `server` output. Build a prototype mounting `expo-server/adapter/express` in the Terreno Express app: serve `dist/client` statically and delegate remaining requests to the server bundle. Verify the exact adapter import path and `createRequestHandler` parameters against current Expo documentation. Establish route precedence: API routes, auth routes, and the admin mount must all match before the SSR catch-all. Add tests asserting precedence — a request to an API path must never reach the SSR handler.
+  - Files: `api/src/` (new plugin or serve module), tests
+  - Depends on: Task 3.1, Task 0.4
+  - Acceptance: SSR renders through the Express app; precedence tests prove API, auth, and admin routes are never shadowed; the adapter import path is verified against current Expo docs and cited.
+
+- [ ] **Task 4.2**: `[RTK]` Handle the unauthenticated-shell render
+  - Description: Per IP question S3, v1 renders the unauthenticated shell on the server and hydrates to the real state on the client. Implement that explicitly rather than by accident: ensure no server render depends on session state, and verify there is no visible flicker of authenticated content. Document the tradeoff in the how-to guide. If the flicker is unacceptable in practice, record that finding and scope a follow-up rather than expanding this IP.
+  - Files: `api/src/` SSR module, `example-frontend/app/_layout.tsx`, docs
+  - Depends on: Task 4.1
+  - Acceptance: server-rendered HTML never contains authenticated content; the hydration transition is observed and characterized (acceptable or not) with a screenshot or recording; the tradeoff is documented.
+
+- [ ] **Task 4.3**: Document Expo Router API routes narrowly
+  - Description: Per IP question S6, document that `server` output enables Expo Router API routes and that they should be used only for web-specific concerns — OG image generation, web-only redirects — with an explicit statement that business logic, data access, and auth belong in `@terreno/api`. Include one worked example (an OG image route) and a "do not put this here" list.
+  - Files: `docs/how-to/enable-web-ssr.md`
+  - Depends on: Task 4.1
+  - Acceptance: the boundary is stated unambiguously; one worked example present; the "do not" list names data access, auth, and business logic.
+
+## Phase 5: Data loading design
+
+- [ ] **Task 5.1**: `[RTK]` Design pass on server-render data loading
+  - Description: Research and write a design note on how server-rendered routes should obtain data given a local-first client: how Expo Router data loaders (`useLoaderData`) interact with a client whose source of truth is a local encrypted store, whether server-fetched data should seed the local store or bypass it, what happens on hydration when local data differs from server-rendered data, and how permissions are enforced when the renderer is inside the API process. Output a recommendation and, if the work is substantial, a new IP rather than expanding this one.
+  - Files: `docs/implementationPlans/ssr-data-loading.md` (new) or a section in the feasibility report
+  - Depends on: Task 4.2
+  - Acceptance: all four questions are answered with a recommendation; if the recommendation implies substantial work, a separate IP is created and this IP's scope is closed at Phase 4.
+
+## Phase 6: Documentation and defaults
+
+- [ ] **Task 6.1**: Write `docs/explanation/web-rendering-modes.md`
+  - Description: Explainer covering all rendering modes (`single`, `static`, `server`) with honest tradeoffs: SEO, first paint, hosting requirements, operational complexity, and what each costs. State which modes Terreno supports as of this work and which are recommended for which situation. Include the "why does a React Native framework care about SSR" framing, since the answer is not obvious to readers who think of Terreno as mobile-first.
+  - Files: `docs/explanation/web-rendering-modes.md` (new), `docs/explanation/README.md`
+  - Depends on: Task 3.1
+  - Acceptance: all three modes covered with at least four tradeoff dimensions each; supported modes stated accurately; the framing section present.
+
+- [ ] **Task 6.2**: Write `docs/how-to/enable-web-ssr.md`
+  - Description: How-to taking a reader from `single` to `static`, and to `server` if it shipped. Cover: the app-config change, what changes in the build output, the hosting change required for each mode, how to verify (fetch a route with JavaScript disabled), common failures (hydration mismatches, browser globals in custom components, the SPA-fallback rewrite shadowing route files), and how to roll back.
+  - Files: `docs/how-to/enable-web-ssr.md` (new), `docs/how-to/README.md`
+  - Depends on: Task 6.1, Task 4.3
+  - Acceptance: a reader can follow it to switch modes; the verification step is concrete; at least three common failures documented with symptoms; rollback included.
+
+- [ ] **Task 6.3**: Update deployment documentation and the output-mode table
+  - Description: Update `docs/explanation/deployment-baseline.md`'s output-mode table for the modes that now ship, and update both provider guides ([`deploy-to-vercel`](../implementationPlans/deploy-to-vercel.md), [`deploy-to-gcp`](../implementationPlans/deploy-to-gcp.md)) for the hosting implications. GCP is affected most: `server` output cannot be served from a GCS bucket, so the GCP guide needs a Cloud Run web-serving option.
+  - Files: `docs/explanation/deployment-baseline.md`, `docs/how-to/deploy-web-to-vercel.md`, `docs/how-to/deploy-web-to-gcs-cdn.md`, possibly a new `docs/how-to/deploy-web-to-cloud-run.md`
+  - Depends on: Task 6.2
+  - Acceptance: the output-mode table matches shipped reality; the GCS guide states that `server` output cannot be hosted there and links the alternative; both provider guides are consistent with the modes that shipped.
+
+- [ ] **Task 6.4**: Decide and implement the default output mode
+  - Description: Per IP question S5, decide whether `static` becomes the default for new apps. If yes: update the bootstrap templates in `mcp-server/src/docs/templates/bootstrap/`, write an upgrade note explaining the change and how to keep `single`, and update the deployment guides. If no: record the decision and its reason in the explainer. Do not change the default without an upgrade note.
+  - Files: `mcp-server/src/docs/templates/bootstrap/**`, `mcp-server/src/docs/upgrades/<version>.md`, `docs/explanation/web-rendering-modes.md`
+  - Depends on: Task 6.3
+  - Acceptance: the decision is recorded with reasoning; if the default changed, a bootstrapped app builds and deploys with the new default and an upgrade note exists; `bun run mcp:build` succeeds.

package/dist/docs/versioned/0.25.0/implementationPlans/PLAN_INDEX.md

@@ -1,21 +0,0 @@
-# Implementation plan index
-
-Tracks active and completed implementation plans (IP) for Terreno. File paths are relative to `docs/implementationPlans/`.
-
-## Active
-
-| Plan | Status | Created | Tasks |
-|------|--------|---------|-------|
-| [Admin UI v2 — Django-parity admin](admin-ui-v2-django-parity.md) | Approved | 2026-06-15 | [tasks](../tasks/admin-ui-v2-django-parity.md) |
-
-## Completed
-
-*(Move rows here from Active when the IP status becomes Complete.)*
-
-## Deferred / Closed
-
-*(Plans parked or superseded.)*
-
-## Backlog
-
-*(Links to ideas not yet promoted to a full IP.)*