@terreno/mcp 57.15.0 → 57.16.1

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

@@ -1,100 +0,0 @@
-# Task List: Positioning — "Django/Rails for TypeScript, with Universal Apps"
-
-See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../implementationPlans/positioning-django-rails-universal.md)
-
-**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` touch the architecture diagram, package list, or integration flow and must run after PR #869 merges and after [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) Phase 6. Unmarked tasks are safe earlier.
-
-## Instructions for the implementing agent
-
-- Write the copy blocks **once** in `docs/explanation/positioning.md` (Task 1.1), then copy them verbatim everywhere else. Do not paraphrase per surface — drift is the problem this IP exists to fix.
-- Do not claim any feature listed under "Where Terreno is headed" as shipped. If you are unsure whether something ships today, grep for it in the package source before writing about it.
-- When moving content out of the README, use `git mv`-style discipline: cut from one file, paste into the other in the same commit, and grep for inbound links.
-- Run `bun run website:build` and `bun run rules:check` before each commit that touches `website/` or `.rulesync/`.
-
-## Phase 1: Canonical copy
-
-- [ ] **Task 1.1**: Write `docs/explanation/positioning.md`
-  - Description: New explainer containing five clearly-labeled copy blocks in fenced code blocks (so they can be copied verbatim without markdown rendering surprises): `tagline` (one line), `elevator` (2–3 sentences), `pillars` (three bullets, in the order batteries-included / universal-by-default / AI-native), `aiPillar` (2–3 sentences naming both AI layers per IP question PO7 — the MCP tool layer and the `/terreno-*` SDLC pipeline process layer), and `pitch` (~150 words). Then a "Why the Django/Rails analogy" section, then the honest comparison table from the IP. Then a "Language rules" section restating the four rules from the program doc (lead with the analogy, say "universal app", never claim unshipped features, keep superlatives off reference pages) plus a fifth: never describe one AI layer without the other.
-  - Files: `docs/explanation/positioning.md` (new)
-  - Depends on: none
-  - Acceptance: five fenced copy blocks present and labeled; the `aiPillar` block names both the MCP tools and the `/terreno-*` pipeline; comparison table has at least eight rows including at least three honest gaps with IP links; language rules section has all five rules.
-
-- [ ] **Task 1.2**: Verify every claim in the comparison table
-  - Description: For each row of the comparison table, confirm the Terreno side exists by finding it in source: `modelRouter` in `api/src/api.ts`, admin packages, `Permissions` in `api/src/permissions.ts`, Better Auth in `api/src/betterAuth*.ts`, MCP tools in `mcp-server/src/tools.ts`, and the SDLC pipeline in `plugins/terreno-planning/skills/`. For each "not shipped" row (background jobs, SSR, RBAC), confirm it is genuinely absent and link the IP or roadmap item tracking it. Correct any row that turns out to be wrong.
-  - Files: `docs/explanation/positioning.md`
-  - Depends on: Task 1.1
-  - Acceptance: every "shipped" row cites a source path; the generator row cites both `mcp-server/src/tools.ts` and `plugins/terreno-planning/`; every "not shipped" row links an IP file that exists in `docs/implementationPlans/`.
-
-- [ ] **Task 1.3**: Gate the pipeline claim on its portability work
-  - Description: The `/terreno-*` pipeline currently only runs inside this monorepo (see [`agentic-sdlc-plugin`](../implementationPlans/agentic-sdlc-plugin.md), "It only works here"). Do not publish positioning copy that implies consumers can use it until that IP's Phase 2 is complete. Check the state of `agentic-sdlc-plugin` Task 2.5 before writing the `aiPillar` block; if portability is not done, write the block describing the tool layer only and add a `TODO` in the IP to revisit, rather than making a claim that fails on first use.
-  - Files: `docs/explanation/positioning.md`
-  - Depends on: Task 1.1
-  - Acceptance: the `aiPillar` block claims the pipeline only if `agentic-sdlc-plugin` Task 2.5 has passed; otherwise the omission is recorded with a pointer to the blocking task.
-
-## Phase 2: README restructure
-
-- [ ] **Task 2.1**: Restructure the README's opening
-  - Description: Rewrite `README.md` above the packages list to this order: title with badges (preserve existing npm badges and the license badge from the governance IP), the `tagline` block as the subtitle, the `elevator` block, the three `pillars`, then a "Quickstart" section, then "Packages". Preserve the existing Vision and Philosophy content but fold it into the pillars rather than repeating it. Per IP question PO5, replace the "Where Terreno is headed" list with a two-line summary linking `ROADMAP.md`.
-  - Files: `README.md`
-  - Depends on: Task 1.1
-  - Acceptance: "Django/Rails for TypeScript" appears within the first two sentences; the pillars appear in the IP's order; the roadmap section is two lines plus a link; no feature claimed that is not shipped.
-
-- [ ] **Task 2.2**: Move maintainer content out of the README
-  - Description: Move these README sections to their correct homes: local development / bootstrap / linking instructions → `CONTRIBUTING.md`; the "Feature flags: OpenFeature migration" walkthrough → a new or existing page under `docs/how-to/` (check `docs/how-to/add-feature-flags.md` first — it may already cover this, in which case delete the README copy and link it); GCP project names, Cloud Run URLs, and Netlify hosts → `infra/flourish/README.md` (created by [`deploy-to-gcp`](../implementationPlans/deploy-to-gcp.md)) or a short "Live examples" list with URLs only and no infra detail; release instructions → `CONTRIBUTING.md`. After moving, grep the repo and `website/` for links to the removed anchors and fix them.
-  - Files: `README.md`, `CONTRIBUTING.md`, `docs/how-to/add-feature-flags.md`, `infra/flourish/README.md`
-  - Depends on: Task 2.1
-  - Acceptance: `rg -i "flourish-terreno|a\.run\.app|Slack" README.md` returns nothing; no content was deleted without a new home; `bun run website:build` reports no new broken links.
-
-- [ ] **Task 2.3**: `[RTK]` Update the README architecture and package list
-  - Description: Confirm the architecture diagram and published-package list reflect syncdb (this may already be done by `rtk-to-syncdb-migration-docs` Task 6.5 — check first and skip if so). Ensure every package in `publish-on-tag.yml` appears in the list exactly once with a one-line description matching its `package.json` description.
-  - Files: `README.md`
-  - Depends on: Task 2.2, `rtk-to-syncdb-migration-docs` Task 6.5
-  - Acceptance: package list matches `publish-on-tag.yml` one-to-one; each description matches the package's `package.json`; diagram names syncdb not rtk.
-
-## Phase 3: Docs site
-
-- [ ] **Task 3.1**: `[RTK]` Rewrite `docs/README.md`
-  - Description: Replace the opening line ("shared packages for full-stack applications with React Native and Express/Mongoose") with the `tagline` + `elevator` + `pillars` blocks. Keep the Diátaxis structure section. Rebuild the package table so it contains every published package including `@terreno/ai`, `@terreno/syncdb`, `@terreno/admin-spa`, and `@terreno/feature-flags`, with `rtk` under a Legacy heading. Update the Quick links section: remove the `.cursorrules` link if that file no longer exists, add `positioning.md`, `ROADMAP.md`, and `CONTRIBUTING.md`.
-  - Files: `docs/README.md`
-  - Depends on: Task 1.1, `rtk-to-syncdb-migration-docs` Task 2.3
-  - Acceptance: tagline appears in the first two sentences; package table complete and matching `publish-on-tag.yml`; every Quick link resolves to an existing file.
-
-- [ ] **Task 3.2**: Update the docs site configuration
-  - Description: In `website/docusaurus.config.ts`, set `tagline` to the canonical tagline and confirm `title`, `themeConfig.metadata` (og description), and navbar title read consistently. Check whether `website/src/pages/index.tsx` exists; if it does, update the hero to use the tagline, the three pillars, and one short code sample (a `modelRouter` registration plus the matching generated hook usage). If there is no custom landing page, note that in the PR body and skip the hero work.
-  - Files: `website/docusaurus.config.ts`, `website/src/pages/index.tsx` (if present)
-  - Depends on: Task 1.1
-  - Acceptance: `bun run website:build` succeeds; the built HTML contains the canonical tagline in the meta description; the hero (if present) shows the three pillars.
-
-## Phase 4: Agent surfaces
-
-- [ ] **Task 4.1**: `[RTK]` Update root agent context files
-  - Description: In `.rulesync/rules/00-root.md` (the source for `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/00-root.mdc`, and the copilot instructions), replace the opening "A monorepo containing shared packages…" with the `tagline` + `elevator` + `pillars`. Keep all existing conventions content unchanged. Apply the same opening to `CLAUDE-consumer.md`. Then run `bun run rules` and commit every generated mirror. Note: `CLAUDE.local.md` appears to be a stale duplicate of `CLAUDE.md` — verify and either update or delete it, reporting which you chose and why.
-  - Files: `.rulesync/rules/00-root.md`, `CLAUDE-consumer.md`, possibly `CLAUDE.local.md`, generated mirrors
-  - Depends on: Task 1.1
-  - Acceptance: `bun run rules:check` exits 0; `AGENTS.md` and `CLAUDE.md` both open with the positioning; no conventions content was lost (diff review); the `CLAUDE.local.md` decision is explained in the PR body.
-
-- [ ] **Task 4.2**: Update the MCP overview resource
-  - Description: Update `mcp-server/src/docs/resources/overview.md` to open with the positioning blocks so agents reading `terreno://docs/overview` describe Terreno consistently. Check the other resource bundles (`api`, `ui`, `rtk`/`syncdb`, `patterns`) for stale positioning language in their intros and fix those too.
-  - Files: `mcp-server/src/docs/resources/*.md`
-  - Depends on: Task 4.1
-  - Acceptance: `bun run mcp:build` succeeds; the overview resource opens with the tagline; no resource intro describes Terreno as "a monorepo of shared packages".
-
-## Phase 5: Metadata
-
-- [ ] **Task 5.1**: Standardize `package.json` descriptions
-  - Description: For every package published by `publish-on-tag.yml`, set `description` to the pattern `<what it does> — part of Terreno, the batteries-included TypeScript framework for universal apps.` Keep the first clause specific and accurate per package (do not make them all identical). Also confirm `keywords`, `repository`, `homepage`, and `bugs` fields are present and correct on every published package — missing `repository` fields hurt npm discoverability.
-  - Files: every published `package.json`
-  - Depends on: Task 1.1
-  - Acceptance: every published package has a `description` matching the pattern, plus `repository`, `homepage`, and `bugs` fields; `bun install` still resolves cleanly.
-
-- [ ] **Task 5.2**: Document the GitHub repository metadata
-  - Description: The repo description and topics cannot be set from a commit. Add a "Repository metadata" subsection to `docs/explanation/positioning.md` giving the exact description string (the short tagline variant from PO1 option C) and the exact topic list to set: `typescript`, `react-native`, `expo`, `express`, `mongoose`, `framework`, `mcp`, `ai`, `universal-apps`, `full-stack`. Mark it as a maintainer action.
-  - Files: `docs/explanation/positioning.md`
-  - Depends on: Task 1.1
-  - Acceptance: the exact description string and full topic list are present and marked as a manual maintainer step.
-
-- [ ] **Task 5.3**: Consistency sweep
-  - Description: Grep the repo for stale positioning language and fix every hit: `rg -n "monorepo containing shared packages"`, `rg -ni "cross-platform"` (should be "universal app" in prose; library-internal technical uses are fine — judge case by case), and `rg -n "88\+ components|90\+ components"` (component counts drift; either verify the number against `ui/src/index.tsx` exports or replace with "a large component library"). Report the count of fixes in the PR body.
-  - Files: various
-  - Depends on: Task 4.1, Task 3.1
-  - Acceptance: no prose surface says "monorepo containing shared packages"; component counts are either verified against the export list or removed; `bun run rules:check` exits 0.

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

@@ -1,112 +0,0 @@
-# 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

@@ -1,163 +0,0 @@
-# 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/TerrenoLabs/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/syncdb-local-first.md

@@ -1,117 +0,0 @@
-# Task List: SyncDB Local-First Data Layer
-
-*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
-
-## Phase 1: Foundation
-
-- [ ] **Task 1.1**: Scaffold `@terreno/syncdb` package
-  - Description: Create the package with core entrypoints, lifecycle interfaces, and typed configuration.
-  - Files: `syncdb/package.json` (new), `syncdb/src/index.ts` (new), `syncdb/src/types.ts` (new), `syncdb/README.md` (new)
-  - Depends on: none
-  - Acceptance: package compiles and exports `createSyncDbClient` and configuration types.
-
-- [ ] **Task 1.2**: Define storage and sync contracts
-  - Description: Add canonical interfaces for entities, outbox records, sync cursors, conflicts, and keyring entries.
-  - Files: `syncdb/src/storage/types.ts` (new), `syncdb/src/sync/types.ts` (new), `syncdb/src/crypto/types.ts` (new)
-  - Depends on: Task 1.1
-  - Acceptance: type checks enforce required fields and operations.
-
-## Phase 2: Local DB and Encryption
-
-- [ ] **Task 2.1**: Implement IndexedDB adapter with migrations
-  - Description: Add object stores for entities/outbox/cursors/conflicts/keyring and schema version migration support.
-  - Files: `syncdb/src/storage/indexedDb.ts` (new), `syncdb/src/storage/migrations.ts` (new), `syncdb/src/storage/indexedDb.test.ts` (new)
-  - Depends on: Task 1.2
-  - Acceptance: storage CRUD + migration tests pass.
-
-- [ ] **Task 2.2**: Implement key manager (Web Crypto)
-  - Description: Add DEK generation + wrap/unwrap logic and persistence integration.
-  - Files: `syncdb/src/crypto/keyManager.ts` (new), `syncdb/src/crypto/keyManager.test.ts` (new)
-  - Depends on: Task 1.2
-  - Acceptance: key lifecycle tests pass for generate/wrap/unwrap/reload.
-
-- [ ] **Task 2.3**: Encrypt IndexedDB payloads at rest
-  - Description: Add AES-GCM envelope encryption/decryption and integrate in storage read/write paths.
-  - Files: `syncdb/src/crypto/envelope.ts` (new), `syncdb/src/storage/secureStorage.ts` (new), `syncdb/src/crypto/envelope.test.ts` (new)
-  - Depends on: Task 2.1, Task 2.2
-  - Acceptance: tests verify no plaintext persistence and successful decrypt roundtrip.
-
-## Phase 3: Local Mutation Engine
-
-- [ ] **Task 3.1**: Add optimistic local mutation application
-  - Description: Apply local patches immediately and retain inverse patches for rollback.
-  - Files: `syncdb/src/mutations/optimistic.ts` (new), `syncdb/src/mutations/optimistic.test.ts` (new)
-  - Depends on: Task 2.3
-  - Acceptance: immediate local apply and rollback tests pass.
-
-- [ ] **Task 3.2**: Implement durable outbox state machine
-  - Description: Persist queued mutations and manage transitions `queued -> inFlight -> acked/conflicted/failed`.
-  - Files: `syncdb/src/mutations/outbox.ts` (new), `syncdb/src/mutations/outbox.test.ts` (new)
-  - Depends on: Task 3.1
-  - Acceptance: replay transition and retry logic tests pass.
-
-- [ ] **Task 3.3**: Implement conflict capture and resolution
-  - Description: Persist conflict records and support `useServer` and `keepMine` resolution paths.
-  - Files: `syncdb/src/mutations/conflicts.ts` (new), `syncdb/src/mutations/conflicts.test.ts` (new)
-  - Depends on: Task 3.2
-  - Acceptance: both resolution strategies correctly update local state and queue state.
-
-## Phase 4: Websocket Delta Sync
-
-- [ ] **Task 4.1**: Build sync transport client
-  - Description: Add websocket connect/auth/reconnect lifecycle and sync event channel handling.
-  - Files: `syncdb/src/sync/transport.ts` (new), `syncdb/src/sync/transport.test.ts` (new)
-  - Depends on: Task 1.2
-  - Acceptance: transport lifecycle tests pass including reconnect behavior.
-
-- [ ] **Task 4.2**: Implement cursor-aware delta applier
-  - Description: Apply deltas idempotently with monotonic cursor checks and gap handling.
-  - Files: `syncdb/src/sync/deltaApplier.ts` (new), `syncdb/src/sync/deltaApplier.test.ts` (new)
-  - Depends on: Task 2.3, Task 4.1
-  - Acceptance: ordered delta tests pass; duplicate/out-of-order deltas are safely handled.
-
-- [ ] **Task 4.3**: Wire ack/nack replay coordinator
-  - Description: Connect outbox replay to server ack/nack responses and conflict creation.
-  - Files: `syncdb/src/sync/replayCoordinator.ts` (new), `syncdb/src/sync/replayCoordinator.test.ts` (new)
-  - Depends on: Task 3.3, Task 4.2
-  - Acceptance: ack finalizes queued mutations; nack creates conflict records.
-
-## Phase 5: App Integration and Migration Bridge
-
-- [ ] **Task 5.1**: Implement React hooks and provider
-  - Description: Add `useEntity`, `useQuery`, `useMutation`, `useSyncStatus`, and context provider wiring.
-  - Files: `syncdb/src/react/provider.tsx` (new), `syncdb/src/react/hooks.ts` (new), `syncdb/src/react/hooks.test.tsx` (new)
-  - Depends on: Task 3.3, Task 4.3
-  - Acceptance: hooks update on local mutations and remote deltas.
-
-- [ ] **Task 5.2**: Add Redux migration bridge
-  - Description: Provide optional adapter for Redux-based consumers transitioning from `@terreno/rtk`.
-  - Files: `syncdb/src/bridge/reduxBridge.ts` (new), `syncdb/src/bridge/reduxBridge.test.ts` (new)
-  - Depends on: Task 5.1
-  - Acceptance: bridge supports selector and dispatch-driven mutation usage.
-
-- [ ] **Task 5.3**: Integrate `example-frontend` todos behind `USE_SYNCDB`
-  - Description: Switch todos flow to syncdb under a feature flag while keeping legacy path available.
-  - Files: `example-frontend/store/index.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/(tabs)/index.tsx`, `example-frontend/app/_layout.tsx`
-  - Depends on: Task 5.1, Task 5.2
-  - Acceptance: flagged path supports offline local create/update/delete and sync reconciliation.
-
-## Phase 6: Codegen and Validation
-
-- [ ] **Task 6.1**: Prototype `@terreno/syncdb-codegen`
-  - Description: Create codegen package that emits typed syncdb operation descriptors from OpenAPI.
-  - Files: `syncdb-codegen/package.json` (new), `syncdb-codegen/src/index.ts` (new), `syncdb-codegen/src/*.test.ts` (new)
-  - Depends on: Task 1.1
-  - Acceptance: generator produces valid descriptors for one sample domain.
-
-- [ ] **Task 6.2**: Author migration docs
-  - Description: Document migration path from `@terreno/rtk` to `@terreno/syncdb` and rollout strategy.
-  - Files: `syncdb/README.md`, `docs/implementationPlans/syncdb-local-first.md`
-  - Depends on: Task 5.3
-  - Acceptance: docs include setup, API usage, and feature-flag rollout playbook.
-
-- [ ] **Task 6.3**: Run validation suite
-  - Description: Execute compile, lint, and tests for touched packages and resolve regressions.
-  - Files: as needed in touched packages
-  - Depends on: Task 6.2
-  - Acceptance: relevant compile/lint/test commands pass with no blockers.

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

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