@terreno/mcp 57.17.0 → 57.19.2

package/src/docs/versioned/57.18.0/tasks/oss-governance-baseline.md

@@ -0,0 +1,129 @@
+# Task List: OSS Governance Baseline
+
+See: [`docs/implementationPlans/oss-governance-baseline.md`](../implementationPlans/oss-governance-baseline.md)
+
+**RTK deprecation flag:** None. No task here touches `@terreno/rtk`, syncdb, or auth. Safe to implement before PR #869.
+
+## Instructions for the implementing agent
+
+- Do **not** change any source code under `*/src/`. This IP is documentation, metadata, and CI configuration only.
+- Do **not** rewrite existing `README.md` prose. Only append the new governance section and badge.
+- Answer keys used below follow the IP decisions recorded 2026-07-29 (**MIT**, DCO, Contributor Covenant 2.1, `security@terreno.app`, `conduct@terreno.app`, Conventional Commits CI-enforced). If the IP decision table changes, follow the IP.
+- Run `bun run lint` before each commit. Run `bun run rules:check` if you touch anything under `.rulesync/`.
+- One commit per task unless a task explicitly says otherwise.
+
+## Phase 1: Legal baseline
+
+- [x] **Task 1.1**: Add root `LICENSE` and `NOTICE`
+  - Description: Copy the MIT License text to a new root `LICENSE` (use the standard MIT template; `mcp-server` already ships MIT). Create `NOTICE` containing the project name, the copyright line `Copyright 2026 Flourish Health, Inc.`, and a one-line statement that the project is licensed under MIT. Include acknowledgement of vendored `api/src/vendor/wesleytodd-openapi/` with a pointer to its own `LICENSE`.
+  - Files: `LICENSE` (new), `NOTICE` (new)
+  - Depends on: none
+  - Acceptance: `LICENSE` exists at repo root with standard MIT text; `NOTICE` mentions the vendored openapi code. Do not compare against `api/LICENSE` or `ui/LICENSE` — those remain Apache-2.0 until Task 1.4.
+
+- [x] **Task 1.2**: Audit license coverage across published packages
+  - Description: Read `.github/workflows/publish-on-tag.yml` and list every package it publishes. For each one, record in a scratch table: whether a `LICENSE` file exists, whether `package.json` has a `files` array, whether `LICENSE` is included in that array, and the `license` field value. Write the findings as a markdown table in the PR description. Do not fix anything in this task.
+  - Files: none (findings go in the PR body)
+  - Depends on: none
+  - Acceptance: PR body contains a table with one row per published package and the four columns above; the table is derived from the actual repo, not copied from the IP.
+
+- [x] **Task 1.3**: Add `LICENSE` to every published package
+  - Description: For each package identified in Task 1.2 that lacks a `LICENSE`, create one by copying the root `LICENSE`. Packages to cover: `rtk`, `ai`, `admin-backend`, `admin-frontend`, `admin-spa`, `api-health`, `feature-flags`, `mcp-server`, `test`. Do not create `LICENSE` files in non-published directories (`demo`, `example-frontend`, `example-backend`, `website`, `terraform`).
+  - Files: `rtk/LICENSE`, `ai/LICENSE`, `admin-backend/LICENSE`, `admin-frontend/LICENSE`, `admin-spa/LICENSE`, `api-health/LICENSE`, `feature-flags/LICENSE`, `mcp-server/LICENSE`, `test/LICENSE` (all new)
+  - Depends on: Task 1.1, Task 1.2
+  - Acceptance: every published package directory contains a `LICENSE` identical to the root `LICENSE`.
+
+- [x] **Task 1.4**: Align `license` fields and `files` arrays
+  - Description: Set `"license": "MIT"` in the root `package.json` and in every published package's `package.json` (relicense `api`/`ui` from Apache-2.0). For every package that has an explicit `files` array, add `"LICENSE"` to it (`ui`, `rtk`, `admin-frontend`, `admin-spa`, `mcp-server` at minimum — confirm against Task 1.2 findings). Do not otherwise reorder or reformat `package.json`.
+  - Files: `package.json`, `ui/package.json`, `rtk/package.json`, `admin-frontend/package.json`, `admin-spa/package.json`, `mcp-server/package.json`, plus any others found in Task 1.2
+  - Depends on: Task 1.3
+  - Acceptance: `bun pm pack --dry-run` run inside each published package lists `LICENSE` among the packed files; no `package.json` declares a license other than `MIT`.
+
+- [x] **Task 1.5**: Verify relicensing consent for `api` and `ui`
+  - Description: Run `git log --format='%an <%ae>' -- api/ ui/ | sort -u` and list every distinct author. Report the list in the PR body, flagging any address that is not a `@flourish.health` address or a known bot. Do **not** proceed to merge the Apache-2.0 → MIT change for `api`/`ui` if a non-Flourish human contributor appears; instead leave a `TODO` note in the PR body requesting sign-off. (`mcp-server` is already MIT.)
+  - Files: none (findings go in the PR body)
+  - Depends on: Task 1.4
+  - Acceptance: PR body lists all `api`/`ui` authors and explicitly states either "all Flourish/bot — safe to relicense" or names the contributors needing sign-off.
+
+- [x] **Task 1.6**: Add a license-coverage CI check
+  - Description: Create `scripts/check-license-coverage.ts` (Bun, TypeScript, `const` arrow functions, explicit return types). It should: read the list of published packages from `.github/workflows/publish-on-tag.yml` (parse job names or a hardcoded list with a comment pointing at the workflow), then for each assert (a) `LICENSE` exists, (b) `package.json` `license` equals the root `package.json` `license`, (c) if a `files` array exists it contains `LICENSE`. Print one line per failure and `process.exit(1)` when any check fails. Add a `check:licenses` script to the root `package.json` and a job to `.github/workflows/repo-policies.yml` that runs it.
+  - Files: `scripts/check-license-coverage.ts` (new), `package.json`, `.github/workflows/repo-policies.yml`
+  - Depends on: Task 1.4
+  - Acceptance: `bun run check:licenses` exits 0 on a clean tree; temporarily deleting `rtk/LICENSE` makes it exit 1 with a message naming `rtk`; the new CI job appears in `repo-policies.yml`.
+
+## Phase 2: Contribution process
+
+- [x] **Task 2.1**: Write `CONTRIBUTING.md`
+  - Description: Create `CONTRIBUTING.md` covering, in this order: (1) Code of Conduct link; (2) ways to contribute (issue, discussion, docs fix, code); (3) development setup — `bun run bootstrap`, Bun version requirement, MongoDB replica-set requirement for `example-backend` (single-node replset is enough, change streams need it), the seeded users `test@example.com` / `superuser@example.com` with password `testpassword123`; (4) per-package commands table pulled from the root `package.json` scripts (`bun run api:test`, `bun run ui:test`, `bun run lint`, `bun run compile`); (5) code style pointers — link `AGENTS.md`, call out the no-barrel-imports rule and `bun run check:no-barrel-imports`, the Luxon requirement, and the logging conventions; (6) test expectations — new features ship with tests, coverage must not drop; (7) the IP process — link `docs/implementationPlans/README.md` and `IP_TEMPLATE.md`, explain when an IP is required (new package, new public API, cross-package change) versus not (bug fix, docs); (8) DCO sign-off instructions (`git commit -s`); (9) PR expectations — draft by default, CI green, screenshots for UI changes.
+  - Files: `CONTRIBUTING.md` (new)
+  - Depends on: none
+  - Acceptance: every command shown in `CONTRIBUTING.md` exists in a `package.json` `scripts` block; the seeded credentials match `example-backend/src/scripts/`; no reference to `.claude/` or other agent-private paths.
+
+- [x] **Task 2.2**: Add `CODE_OF_CONDUCT.md`
+  - Description: Add Contributor Covenant 2.1 verbatim, with the enforcement contact set to `conduct@terreno.app`. Do not modify the covenant text other than the contact line and the project name.
+  - Files: `CODE_OF_CONDUCT.md` (new)
+  - Depends on: none
+  - Acceptance: file states "Contributor Covenant" and version 2.1; contact address is present and is not a placeholder.
+
+- [x] **Task 2.3**: Add `SECURITY.md`
+  - Description: Create `SECURITY.md` with: a supported-versions table (current minor supported; previous minor receives security fixes only), reporting instructions naming GitHub private vulnerability reporting as the primary channel and `security@terreno.app` as fallback, a 5-business-day acknowledgement commitment, a statement that reporters should not open public issues for vulnerabilities, and a note that CodeQL runs on the repo (`.github/workflows/codeql-analysis.yml`).
+  - Files: `SECURITY.md` (new)
+  - Depends on: none
+  - Acceptance: file exists at repo root so GitHub surfaces it under Security → Policy; both reporting channels are named.
+
+- [x] **Task 2.4**: Add a DCO check for external PRs
+  - Description: Add a workflow job (either in `repo-policies.yml` or a new `.github/workflows/dco.yml`) that, for pull requests whose head repository differs from the base repository, verifies every commit message contains a `Signed-off-by:` line matching the commit author. Skip the check for PRs from the same repo and for bot authors (`dependabot[bot]`, `cursor[bot]`). Follow the repo's existing convention of validating required inputs before use.
+  - Files: `.github/workflows/dco.yml` (new) or `.github/workflows/repo-policies.yml`
+  - Depends on: Task 2.1
+  - Acceptance: the job's condition explicitly excludes same-repo PRs and the named bots; the workflow parses as valid YAML (`bunx yaml-lint` or equivalent).
+
+## Phase 3: Changelog
+
+- [x] **Task 3.1**: Create the root `CHANGELOG.md` and backfill releases
+  - Description: Create `CHANGELOG.md` in Keep-a-Changelog format with an `## [Unreleased]` section at the top, then one section per released version, newest first. Source the content from `gh release list --limit 40` and `gh release view <tag>` for each release from 0.20.0 to the current version. Group each entry under `Added` / `Changed` / `Fixed` / `Deprecated` / `Removed`. Include a header note that all `@terreno/*` packages are versioned in lockstep and a link to `docs/implementationPlans/oss-launch-program.md` is **not** needed here. Do not invent entries — if a release has no notes, write `- No published release notes.` under that version.
+  - Files: `CHANGELOG.md` (new)
+  - Depends on: none
+  - Acceptance: every version tag returned by `gh release list` between 0.20.0 and current has a section; no section is empty; the file states the lockstep versioning rule.
+
+- [x] **Task 3.2**: Reduce `api/CHANGELOG.md` to a pointer
+  - Description: Replace the contents of `api/CHANGELOG.md` with a short note that the changelog moved to the repo root, linking `../CHANGELOG.md`. Preserve the historical entries by moving them into the corresponding root `CHANGELOG.md` sections first if they contain detail the GitHub releases lack.
+  - Files: `api/CHANGELOG.md`, `CHANGELOG.md`
+  - Depends on: Task 3.1
+  - Acceptance: `api/CHANGELOG.md` is under 10 lines and links to the root changelog; no historical detail was lost.
+
+- [x] **Task 3.3**: Make changelog updates part of the release process
+  - Description: Edit `.rulesync/skills/release/SKILL.md` to add a required step: before tagging, move `## [Unreleased]` content into a new version section in the root `CHANGELOG.md` with today's date (via Luxon-formatted ISO date), and confirm the section is non-empty. Then run `bun run rules` to regenerate the mirrored skill files under `.cursor/`, `.claude/`, `.devin/`, `.github/`, and `.agents/`.
+  - Files: `.rulesync/skills/release/SKILL.md`, plus generated mirrors
+  - Depends on: Task 3.1
+  - Acceptance: `bun run rules:check` exits 0 (no uncommitted diff after regeneration); the release skill mentions `CHANGELOG.md` as a required pre-tag step.
+
+## Phase 4: GitHub templates
+
+- [x] **Task 4.1**: Add issue forms
+  - Description: Create three GitHub issue forms. `bug_report.yml`: fields for affected package (dropdown listing all published `@terreno/*` packages plus `docs`, `examples`, `mcp`), version, platform (dropdown: iOS / Android / Web / Backend / N/A), reproduction steps (required textarea), expected vs actual, and a checkbox confirming the reporter searched existing issues. `feature_request.yml`: problem statement (required), proposed solution, alternatives considered, and a checkbox asking whether the requester is willing to open a PR. `docs_issue.yml`: page URL, what is wrong or missing, and suggested fix. Add `config.yml` with `blank_issues_enabled: false` and contact links to Discussions (Q&A and Ideas categories) and `SECURITY.md`.
+  - Files: `.github/ISSUE_TEMPLATE/bug_report.yml`, `.github/ISSUE_TEMPLATE/feature_request.yml`, `.github/ISSUE_TEMPLATE/docs_issue.yml`, `.github/ISSUE_TEMPLATE/config.yml` (all new)
+  - Depends on: Task 2.3
+  - Acceptance: all four files parse as valid YAML; the package dropdown in `bug_report.yml` matches the packages published by `publish-on-tag.yml`; `config.yml` disables blank issues.
+
+- [x] **Task 4.2**: Add a PR template
+  - Description: Create `.github/PULL_REQUEST_TEMPLATE.md` with sections: Summary; Related IP or issue; Type of change (checkboxes); Testing performed (with a reminder that frontend changes require screenshots or video per `AGENTS.md`); Checklist (tests added, `bun run lint` passes, `bun run compile` passes, docs updated, changelog `Unreleased` entry added for user-facing changes, DCO signed off). Keep it short enough that contributors actually fill it in — under 40 lines.
+  - Files: `.github/PULL_REQUEST_TEMPLATE.md` (new)
+  - Depends on: Task 2.1, Task 3.1
+  - Acceptance: template is under 40 lines; references the changelog and the frontend-verification requirement.
+
+- [x] **Task 4.3**: Add `CODEOWNERS`
+  - Description: Create `.github/CODEOWNERS` mapping each package directory to its owning team or maintainer, plus a catch-all root owner. Use GitHub team handles if they exist; otherwise use individual maintainer usernames. Include entries for `docs/`, `.github/`, `.rulesync/`, and `terraform/`.
+  - Files: `.github/CODEOWNERS` (new)
+  - Depends on: none
+  - Acceptance: every top-level package directory has an owner; the file has a catch-all `*` line; GitHub's CODEOWNERS validation (visible in repo settings) reports no errors.
+
+- [x] **Task 4.4**: Document required repository settings
+  - Description: Add a short section to `CONTRIBUTING.md` (or a new `docs/explanation/repository-settings.md` if it exceeds 30 lines) listing the GitHub settings a maintainer must enable manually because they cannot be committed: Discussions enabled with the categories from [`public-roadmap-github.md`](../implementationPlans/public-roadmap-github.md), private vulnerability reporting enabled, branch protection on `master` requiring the CI checks, "Allow squash merging" only, and auto-delete of merged branches.
+  - Files: `CONTRIBUTING.md` or `docs/explanation/repository-settings.md`
+  - Depends on: Task 2.1
+  - Acceptance: the list names each setting and where to find it in the GitHub UI; no setting is described as already enabled unless verified.
+
+- [x] **Task 4.5**: Append the governance section to `README.md`
+  - Description: Add a `## License` section and a `## Contributing` section near the end of `README.md`, plus a license badge next to the existing npm badges. Link `LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md`. Do not modify any other README content — positioning changes belong to a different IP.
+  - Files: `README.md`
+  - Depends on: Task 1.1, Task 2.1, Task 2.2, Task 2.3
+  - Acceptance: `git diff README.md` shows only additions (badge line plus two new sections); all four links resolve to files that exist.

package/src/docs/versioned/57.18.0/tasks/password-reset-and-email-verification.md

@@ -0,0 +1,60 @@
+# Tasks: Password reset and email verification
+
+IP: [password-reset-and-email-verification](../implementationPlans/password-reset-and-email-verification.md)
+
+## Phase 1 — Token infrastructure
+
+- [x] **Task 1.1**: `AuthToken` model + issue/consume statics
+  - Description: hashed single-use tokens with TTL expiry per IP
+  - Files: `api/src/authTokens.ts`, type files
+  - Depends on: none
+  - Acceptance: atomic single-use test (parallel consumes → one winner); expiry test
+- [x] **Task 1.2**: `emailVerificationPlugin`
+  - Description: `emailVerified` field plugin for user schemas
+  - Files: `api/src/plugins.ts`
+  - Depends on: none
+  - Acceptance: plugin test; example User adopts it
+
+## Phase 2 — JWT routes + mail
+
+- [x] **Task 2.1**: forgot/reset routes
+  - Description: 202-always forgot; reset validates+consumes token, `setPassword`, invalidates refresh tokens; RTK client path/shape contract verified
+  - Files: `api/src/authRecovery.ts`, `api/src/auth.ts`
+  - Depends on: 1.1, comms-abstraction
+  - Acceptance: enumeration-safety + happy-path supertest; RTK-shape test
+- [x] **Task 2.2**: verification routes + `requireEmailVerification` option
+  - Description: sendVerification/verifyEmail; 403 `email-not-verified` gating on login when enabled
+  - Files: `api/src/authRecovery.ts`, `api/src/auth.ts`
+  - Depends on: 1.2, 2.1
+  - Acceptance: gating on/off supertest
+- [x] **Task 2.3**: Mail templates
+  - Description: `resetPassword` + `verifyEmail` templates with app-override hook and `publicAppUrl` links
+  - Files: `comms/src/templates.ts`
+  - Depends on: comms-abstraction Phase 1
+  - Acceptance: rendered output snapshot tests
+
+## Phase 3 — Better Auth parity
+
+- [x] **Task 3.1**: Better Auth hooks
+  - Description: `sendResetPassword`/`sendVerificationEmail` wired to the same templates
+  - Files: `api/src/betterAuthSetup.ts`
+  - Depends on: 2.3
+  - Acceptance: parity test asserting identical template usage
+
+## Phase 4 — Client + docs
+
+- [x] **Task 4.1**: example-frontend reset screen + verify banner
+  - Description: `/resetPassword` route + profile banner with re-send; SDK regen
+  - Files: `example-frontend/app/resetPassword.tsx`, `app/(tabs)/profile.tsx`, `store/openApiSdk.ts`
+  - Depends on: Phase 2
+  - Acceptance: end-to-end flow with console adapter; UI verification evidence per verify-ui-changes
+- [x] **Task 4.2**: `LoginScreen` forgot-password link prop
+  - Description: optional `onForgotPassword` on `@terreno/ui` LoginScreen
+  - Files: `ui/src/login/LoginScreen.tsx` + tests + demo story
+  - Depends on: none
+  - Acceptance: renders only when provided; story added
+- [x] **Task 4.3**: Docs
+  - Description: how-to + env reference + rulesync
+  - Files: `docs/how-to/password-reset.md`, `docs/reference/environment-variables.md`, `.rulesync/**`
+  - Depends on: Phase 2
+  - Acceptance: `bun run rules:check` passes

package/src/docs/versioned/57.18.0/tasks/pluggable-database-sqlite.md

@@ -0,0 +1,44 @@
+# Tasks: Pluggable database layer and SQLite adapter
+
+IP: [pluggable-database-sqlite.md](../implementationPlans/pluggable-database-sqlite.md)
+
+## Phase 1 — Adapter seam + Mongoose adapter (no behavior change)
+
+- [ ] Define `DatabaseAdapter`, `AdapterCollection`, `AdapterCapabilities`, `PopulatePath`, and `MongoFilter` types in `api/src/db/adapter.ts`
+- [ ] Implement `MongooseAdapter` in `api/src/db/mongooseAdapter.ts` delegating to today's exact Mongoose calls (including the `docLoader.ts` native soft-delete probe)
+- [ ] Refactor `api/src/api.ts` list/read/create/update/delete/array handlers to use the adapter
+- [ ] Refactor `api/src/sync/executors.ts` and `api/src/docLoader.ts` to use the adapter
+- [ ] Refactor permissions doc loading (`permissionMiddleware`) to use the adapter
+- [ ] Add `TerrenoAppOptions.database` with Mongoose adapter default; export adapter types + `mongooseAdapter()` from `api/src/index.ts`
+- [ ] Add capability checks (`changeStreams`, `transactions`, `textSearch`) to realtime, syncdb, feature-flag, and search registration paths (all pass on Mongo)
+- [ ] Gate: full existing api test suite green with zero test edits
+
+## Phase 2 — @terreno/db-sqlite core
+
+- [ ] Scaffold `db-sqlite/` workspace package (catalog deps, tsconfig, biome, CI wiring)
+- [ ] Driver injection layer (`bun:sqlite` default; accept `better-sqlite3` / `node:sqlite` / `libsql` handles); connection defaults (WAL, busy_timeout, foreign_keys off)
+- [ ] Schema → DDL mapping per the IP table (String/Number/Boolean/Date/ObjectId/enum/JSON/`DateOnly`/`_id`/`__v`; NOT NULL; JS-layer defaults; indexes incl. unique + sparse-as-partial)
+- [ ] `ensureSchema` additive migration with `_terreno_schema` metadata table; destructive changes → startup error + generated SQL file
+- [ ] CRUD: create / findById / save (validate + changed-path persist) / delete (soft + hard) with `model.hydrate()` documents
+- [ ] Plugin semantics: created/updated timestamps, soft-delete read filter, `__v` optimistic-concurrency conflict path, document save middleware via the hook registry
+- [ ] Query compiler for the modelRouter filter subset (equality, `$in/$nin/$ne/$exists/$gt/$gte/$lt/$lte`, `$and`/`$or`, date ranges) incl. `json_extract` and `json_each` paths; unknown operators → 400
+- [ ] Sort / skip / limit / count
+- [ ] Population: batched two-phase loads per path, field selection in SQL, single + array refs, dangling ref → null, soft-delete filter on referenced models, populate on findById/list and post-create/update re-reads
+- [ ] Adapter conformance suite in `api/src/db/conformance/` (CRUD, query operators, pagination, plugins, population) run against both adapters
+
+## Phase 3 — Auth + capability hardening
+
+- [ ] `adapter.getBetterAuthDatabase()` seam in `betterAuthSetup.ts` (Mongo adapter returns today's `mongodbAdapter` client)
+- [ ] Better Auth on SQLite: driver handle → Kysely adapter; schema tables created from `ensureSchema` via Better Auth migration tooling; signup/login/session → `req.user` end-to-end test
+- [ ] Gate `setupAuth`/passport path to the Mongo adapter with an actionable startup error
+- [ ] Startup errors for missing capabilities name the capability and the feature that needs it (tested)
+- [ ] `@terreno/test`: `TERRENO_TEST_DB=sqlite` mode (temp-file DB per suite, no mongod)
+
+## Phase 4 — Example, docs, and integration
+
+- [ ] `example-backend` `DB_ADAPTER=sqlite` mode: adapter wiring, skip change-stream features via capability flags, seed script works, boot + CRUD smoke test with no mongod
+- [ ] Parity checks: `/openapi.json` and admin `/admin/config` identical across adapters for example models
+- [ ] Docs: `docs/how-to/run-on-sqlite.md`, `docs/explanation/database-adapters.md`; update positioning docs' MongoDB-only claims
+- [ ] MCP: `terreno_generate_model` / bootstrap templates mention adapter choice
+- [ ] Changelog + upgrade note (no action needed for existing apps)
+- [ ] `bun run lint`, `bun run compile`, api + db-sqlite tests green in CI

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

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

@@ -0,0 +1,70 @@
+# Tasks: API rate limiting
+
+IP: [rate-limiting.md](../implementationPlans/rate-limiting.md)  
+**Closes:** https://github.com/TerrenoLabs/terreno/issues/1187
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (memory, TerrenoApp)
+
+- [x] **Task 1.1**: Rate-limit module + TerrenoApp mount
+  - Delivers: `rateLimit: {}` on `TerrenoApp` limits HTTP; omitted option is a no-op; `POST /auth/login` uses the auth bucket (20 / 15 min); modelRouter list uses `api` (600 / 15 min); skip `/health` and `/openapi.json`; 429 `APIError` `code: "rate-limit-exceeded"` with `Retry-After` and IETF `RateLimit` / `RateLimit-Policy`; memory store; `trust proxy` default `1` when enabled
+  - Files: `api/src/rateLimit/types.ts`, `api/src/rateLimit/store.ts`, `api/src/rateLimit/memoryStore.ts`, `api/src/rateLimit/policies.ts`, `api/src/rateLimit/middleware.ts`, `api/src/rateLimit/rateLimit.test.ts`, `api/src/terrenoApp.ts`, `api/src/index.ts`, `api/src/api.ts` (remove `TODO add rate limit`)
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `backend-test-env`, `update-docs`
+  - Docs: stub section in `docs/reference/api.md` (`rateLimit` option) so the tracer is documented when it lands
+  - Acceptance: bun tests — default off (burst login no 429); auth 20 then 429; 21st list GET still 200; 601st list 429; `/health` never 429; 429 body/headers; login classified auth
+
+## Phase 2 — Shared stores
+
+- [x] **Task 2.1**: Redis store
+  - Delivers: `store: "redis"` uses `VALKEY_URL` then `REDIS_URL`; missing URL fails startup with a clear `APIError`; consume contract matches memory
+  - Files: `api/src/rateLimit/redisStore.ts`, tests with a fake client; optional skip-if-no-redis integration
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`
+  - Docs: store table in `docs/how-to/rate-limiting.md` (create page if 4.1 not started — Pick may write the Redis rows into the how-to started in 1.1/4.1)
+  - Acceptance: unit tests against the store interface; startup failure without URL
+
+- [x] **Task 2.2**: Mongo store
+  - Delivers: `store: "mongo"` uses the process mongoose connection and `rateLimitHits` with TTL expiry; same consume contract
+  - Files: `api/src/rateLimit/mongoStore.ts` (+ schema/types if a model is used), tests against in-memory Mongo via existing `@terreno/test` harness
+  - Blocked by: 1.1
+  - Skills: `mongoose-schema-safety` (if a Mongoose schema is added), `backend-test-env`
+  - Docs: Mongo collection / TTL note on the how-to
+  - Acceptance: two keys isolated; expiry/window reset; no public modelRouter for hits
+
+## Phase 3 — Paths and proxy
+
+- [x] **Task 3.1**: Auth path table + Better Auth / GitHub
+  - Delivers: GitHub OAuth start/callback on auth bucket; Better Auth `basePath` sign-in/sign-up/forget-password on auth; `/auth/me` on api; extra `skip` callback honored
+  - Files: `api/src/rateLimit/policies.ts`, tests
+  - Blocked by: 1.1
+  - Acceptance: supertest (or middleware unit tests with req.url) for each classified prefix
+
+- [x] **Task 3.2**: Trust-proxy keying
+  - Delivers: with `trustProxy: 1`, `X-Forwarded-For` client IP is the unauthenticated key; `trustProxy: false` ignores spoofed forwarded-for; override hop count works
+  - Files: `api/src/rateLimit/*.ts`, `api/src/terrenoApp.ts`, tests
+  - Blocked by: 1.1
+  - Acceptance: two tests (trust on vs off) with distinct `X-Forwarded-For` values
+
+## Phase 4 — Docs and example
+
+- [x] **Task 4.1**: Diátaxis + changelog + rules
+  - Delivers: operator how-to, reference, auth explanation, env reference (no enable env), replace misleading `RATE_LIMIT_*` snippet in configuration-system, Terreno 58 default-on note, `.rulesync/rules/api/00-api.mdc`, `CHANGELOG.md` Added
+  - Files: `docs/how-to/rate-limiting.md`, `docs/reference/api.md`, `docs/reference/environment-variables.md`, `docs/explanation/authentication.md`, `docs/explanation/configuration-system.md`, `.rulesync/rules/api/00-api.mdc`, `CHANGELOG.md`; `bun run rules` / `skills:sync` if required after rulesync
+  - Blocked by: 1.1 (content can land with 2.x/3.x; must match shipped stores)
+  - Skills: `update-docs`
+  - Acceptance: a stranger can enable Redis on Cloud Run from the how-to; 58 default-on is explicit; `bun run website:build` if docs site is in the slice
+
+- [x] **Task 4.2**: example-backend snippet (limiter stays off)
+  - Delivers: commented `rateLimit: process.env.RATE_LIMIT_ENABLED === "true" ? {store: "memory"} : undefined` (or equivalent) showing app-owned env
+  - Files: `example-backend/src/server.ts` (or `index`/`terrenoApp` bootstrap)
+  - Blocked by: 1.1
+  - Acceptance: default example server still has no limiter; comment compiles if uncommented
+
+- [x] **Task 4.3**: Roadmap seed + 58 upgrade stub
+  - Delivers: `docs/explanation/roadmap-seed-issues.md` `rate-limiting` section points at IP/task GitHub URLs and `IP=rate-limiting`; how-to or `mcp-server/src/docs/upgrades/` notes that Terreno 58 defaults the limiter on
+  - Files: `docs/explanation/roadmap-seed-issues.md`; upgrade note path named in how-to until 58 exists
+  - Blocked by: 4.1
+  - Skills: `update-docs`
+  - Acceptance: seed `Implementation plan` / `Tasks` links are not `*(not yet written)*`

package/src/docs/versioned/57.18.0/tasks/remove-legacy-realtime.md

@@ -0,0 +1,59 @@
+# Task List: Remove legacy RTK realtime in Terreno 58
+
+See: [`docs/implementationPlans/remove-legacy-realtime.md`](../implementationPlans/remove-legacy-realtime.md)
+
+**Target:** Terreno **58.0.0**. Do not execute Phase 2 on the 57.x line.
+
+`RealtimeApp` is **not** in this deletion. It remains the Socket.io / change-stream host for `@terreno/syncdb`.
+
+## Phase 1: Deprecate on 57.x (current)
+
+- [x] **Task 1.1**: Runtime and JSDoc deprecation for `modelRouter` `realtime`
+  - Delivers: one-time `logger.warn` per model/path; `@deprecated` on `ModelRouterOptions.realtime`, `RealtimeConfig`, and `RealtimeEvent`
+  - Files: `api/src/realtime/deprecation.ts`, `api/src/api.ts`, `api/src/realtime/types.ts`, `api/src/realtime/deprecation.test.ts`
+  - Blocked by: none
+  - Acceptance: tests prove one warning per model/path; message names Terreno 58 and `@terreno/syncdb`
+
+- [x] **Task 1.2**: Runtime and JSDoc deprecation for RTK cache-patching helpers
+  - Delivers: one-time `console.warn`; `@deprecated` on `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`, `RealtimeEvent`
+  - Files: `rtk/src/realtime.ts`, `rtk/src/realtime.test.ts`
+  - Blocked by: none
+  - Acceptance: tests prove a single warning across the three helpers; message names Terreno 58 and `@terreno/syncdb`
+
+- [x] **Task 1.3**: Docs, changelog, and agent skills
+  - Delivers: consumers can find the sunset date and replacement without reading source
+  - Files: `docs/reference/api.md`, `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/legacy/rtk.md`, `changelog/unreleased/`, `.rulesync/skills/`
+  - Blocked by: Task 1.1, Task 1.2
+  - Acceptance: docs say `RealtimeApp` stays; `modelRouter` `realtime` and RTK helpers go away in 58
+
+## Phase 2: Delete in Terreno 58
+
+- [ ] **Task 2.1**: Remove `modelRouter` `realtime` registration
+  - Delivers: passing `realtime` is a type error; no `registerRealtime` from `modelRouter`
+  - Files: `api/src/api.ts`, `api/src/realtime/types.ts`, `api/src/realtime/deprecation.ts`, `api/src/index.ts`, `api/src/api.test.ts`
+  - Blocked by: Terreno 58 major
+  - Acceptance: TypeScript and tests fail if a router still passes `realtime`; `sync` registration is unchanged
+
+- [ ] **Task 2.2**: Stop emitting legacy `sync` (RTK) websocket events
+  - Delivers: change streams emit `sync:delta` only for synced models; no RTK `sync` payload
+  - Files: `api/src/realtime/changeStreamWatcher.ts`, `api/src/realtime/realtimeApp.ts`, `api/src/realtime/registry.ts`, related tests
+  - Blocked by: Task 2.1
+  - Acceptance: a model with only `sync` still emits `sync:delta`; no `sync` events for collection CRUD; `admin:model.changed` still works when `admin.realtime` is true
+
+- [ ] **Task 2.3**: Remove `@terreno/rtk` cache-patching helpers
+  - Delivers: `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket` are gone from the package
+  - Files: `rtk/src/realtime.ts`, `rtk/src/realtime.test.ts`, `rtk/src/index.ts`, `rtk/README.md`
+  - Blocked by: Task 2.1
+  - Acceptance: package compile fails if those symbols are imported; `useSocketConnection` still exists
+
+- [ ] **Task 2.4**: Remove example and bootstrap usage
+  - Delivers: example-backend/example-frontend/MCP bootstrap do not configure RTK realtime
+  - Files: `example-backend/src/api/todos.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/_layout.tsx`, MCP bootstrap templates
+  - Blocked by: Task 2.3
+  - Acceptance: todos stay on `sync` + syncdb; `setRealtimeSocket` / `realtimeList` / `realtimeDocument` are gone; `RealtimeApp` remains registered
+
+- [ ] **Task 2.5**: Docs, skills, changelog, 58.0.0 upgrade note
+  - Delivers: upgrade note lists every removed symbol and the syncdb replacement
+  - Files: `docs/how-to/migrate-rtk-to-syncdb.md`, `docs/reference/api.md`, `.rulesync/skills/terreno-data-fetching/references/realtime.md`, `.rulesync/skills/terreno-backend-api/references/model-router.md`, `mcp-server/src/docs/upgrades/58.0.0.md`, changelog
+  - Blocked by: Task 2.4
+  - Acceptance: `bun run check:changelog` passes for 58.0.0; upgrade note exists; no skill tells agents to set `modelRouter` `realtime` for collection CRUD