@terreno/mcp 57.15.0 → 57.16.1

package/src/docs/versioned/57.15.0/tasks/mongodb-migrations-tooling.md

@@ -0,0 +1,107 @@
+# Tasks: MongoDB migrations tooling
+
+IP: [mongodb-migrations-tooling.md](../implementationPlans/mongodb-migrations-tooling.md)  
+**Closes:** https://github.com/TerrenoLabs/terreno/issues/1189
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Runner, lock, history
+
+- [x] **Task 1.1**: Migration context + in-memory/programmatic runner
+  - Delivers: `runMigrations({migrations, dryRun})` runs pending `up` in order; dry-run calls `up({dryRun: true})` and does **not** record applied ids; wet records checksum + `appliedAt`; already-applied ids are skipped; checksum mismatch throws
+  - Files: `api/src/migrations/types.ts`, `api/src/migrations/runner.ts`, `api/src/migrations/runner.test.ts`
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `backend-test-env`, `mongoose-schema-safety`
+  - Docs: stub “Migrations” subsection in `docs/reference/api.md`
+  - Acceptance: bun tests — dry-run increments a counter inside `up` but history stays empty; wet applies once; second wet is a no-op; edited checksum fails
+
+- [x] **Task 1.2**: Lock collection (wait, heartbeat, 10-minute steal)
+  - Delivers: `withMigrationLock` uses `terreno_migrations` `_id: "_lock"`; concurrent second waiter proceeds after steal when `expiresAt` is past; holder heartbeats; `finally` releases
+  - Files: `api/src/migrations/lock.ts`, `api/src/migrations/lock.test.ts`; wire lock around wet `runMigrations`
+  - Blocked by: 1.1
+  - Skills: `backend-test-env`, `mongoose-schema-safety`
+  - Docs: lock TTL in the api.md stub
+  - Acceptance: two overlapping wet runs serialize; expired lock is stolen; crash-simulated missing release still steals after TTL (test injects past `expiresAt`)
+
+## Phase 2 — Files, CLI, production gate
+
+- [x] **Task 2.1**: File loader + `checkMigrationFiles`
+  - Delivers: load `migrations/<YYYYMMDDHHmmss>-<slug>.ts`; id must match filename; duplicate ids fail; optional `down`; `checkMigrationFiles` is the no-Mongo CI check
+  - Files: `api/src/migrations/load.ts`, `api/src/migrations/load.test.ts`, fixture files under `api/src/migrations/fixtures/`
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`
+  - Docs: file naming in api.md
+  - Acceptance: tests for sort order, bad id, missing export, successful load of `up`/`down`
+
+- [x] **Task 2.2**: Production gate + CLI `status`/`up`/`down`/`check`
+  - Delivers: `terreno-migrate` bin; prod wet requires `ALLOW_MIGRATIONS=true` and `--force`; `down --steps` stops with a clear error when `down` is missing; `--dry` never writes history
+  - Files: `api/src/migrations/cli.ts`, `api/src/migrations/cli.test.ts`, `api/package.json` `bin`, `api/src/index.ts` exports
+  - Blocked by: 1.2, 2.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: command table in `docs/how-to/run-mongodb-migrations.md` (create page); `ALLOW_MIGRATIONS` row in `docs/reference/environment-variables.md`
+  - Acceptance: argv tests (help, check, dry up, prod deny); integration up/down against memory Mongo; `down` without function fails
+
+## Phase 3 — Generate from schema snapshot
+
+- [x] **Task 3.1**: Schema catalog + diff
+  - Delivers: `buildSchemaCatalog(models)` and `diffSchemaCatalog(before, after)` covering indexes, optional fields, required, unique, rename heuristic
+  - Files: `api/src/migrations/schemaCatalog.ts`, `api/src/migrations/schemaCatalog.test.ts`
+  - Blocked by: none (can parallel 1.x in theory; Pick runs after 2.2)
+  - Skills: `mongoose-schema-safety`
+  - Docs: what generate can/cannot emit (how-to)
+  - Acceptance: fixture schemas produce stable catalogs; required+unique+rename classified unsafe; optional field + index classified safe
+
+- [x] **Task 3.2**: `generate` CLI writes a timestamped file
+  - Delivers: `terreno-migrate generate --dir --models`; uses last `schemaAfter`; no-op diff exits 0; unsafe ops emit throwing stub; generated `up` honors `dryRun` for safe index ops
+  - Files: `api/src/migrations/generate.ts`, `api/src/migrations/generate.test.ts`, CLI subcommand
+  - Blocked by: 2.2, 3.1
+  - Skills: `mongoose-schema-safety`, `update-docs`
+  - Docs: generate workflow on the how-to
+  - Acceptance: temp dir tests — first generate from empty snapshot; second generate no-op; required-field stub throws in dry-run and wet
+
+## Phase 4 — Boot hook
+
+- [x] **Task 4.1**: `TerrenoApp` `migrations.runOnStart`
+  - Delivers: option default off; when true, wet `up` after DB connect before listen; prod still needs `ALLOW_MIGRATIONS`; failure prevents listen
+  - Files: `api/src/terrenoApp.ts`, `api/src/terrenoApp.migrations.test.ts` (or extend existing app tests)
+  - Blocked by: 2.2
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: option table in api.md
+  - Acceptance: tests — omitted option does not query `terreno_migrations`; `runOnStart: true` applies pending; prod without env throws before listen
+
+## Phase 5 — Admin HTTP
+
+- [x] **Task 5.1**: Admin migrations routes + config flag
+  - Delivers: `GET /admin/migrations/status` and `POST /admin/migrations/run?wetRun=` as `modelRouter` collection actions; creates BackgroundTask and runs batch pending; poll/cancel via existing script task routes; prod wet 403 without `ALLOW_MIGRATIONS`; `GET /admin/config` includes `migrations.enabled`
+  - Files: `admin-backend/src/adminApp.ts`, `admin-backend/src/adminApp.migrations.test.ts`, AdminApp options type
+  - Blocked by: 1.2, 2.1
+  - Skills: `terreno-backend-api`, `building-admin-interfaces`, `backend-test-env`
+  - Docs: `docs/reference/admin-config.md` + admin-backend reference
+  - Acceptance: 201 + taskId; dry-run does not persist applied ids; non-admin 403; unknown when migrations not configured 404
+
+## Phase 6 — Admin UI
+
+- [x] **Task 6.1**: Migrations page, nav, spa route
+  - Delivers: `__migrations` screen distinct from `__scripts`; status list; Dry run / Apply pending; reuse task polling (script-runner modal or equivalent); shell nav when `migrations.enabled`
+  - Files: `admin-frontend/src/AdminMigrations.tsx`, tests, `AdminShell.tsx`, `AdminScreenRouter.tsx`, types; `admin-spa` route
+  - Blocked by: 5.1
+  - Skills: `terreno-ui`, `building-admin-interfaces`, `verify-ui-changes`, `update-docs`
+  - Docs: `docs/how-to/build-admin-screens.md` nav note
+  - Acceptance: frontend tests for routing/nav; browser verification of dry-run vs apply on example admin (artifacts under `/opt/cursor/artifacts/`)
+
+## Phase 7 — Example, CI, agent docs
+
+- [x] **Task 7.1**: example-backend wiring + reversible fixture
+  - Delivers: `example-backend/migrations/` with a reversible index (or no-op) migration; package scripts `migrate:check` / `migrate:up` / `migrate:status`; test `exerciseReversibleMigrations`; do not wipe `terreno_migrations` in seed reset
+  - Files: `example-backend/package.json`, `example-backend/src/server.ts` (pass `migrations` into AdminApp + TerrenoApp), seed reset guard, tests
+  - Blocked by: 2.2, 5.1
+  - Skills: `update-docs`, `backend-test-env`
+  - Docs: example commands on the how-to
+  - Acceptance: `bun test` in example-backend covers migrate check + up/down; seed `--reset` leaves history collection
+
+- [x] **Task 7.2**: Diátaxis, changelog, mongoose-schema-safety
+  - Delivers: how-to complete; api/env/admin reference; skill tells authors to use versioned migrations for backfills; `CHANGELOG.md` Added; `bun run skills:sync` / `bun run rules` if the skill source changed
+  - Files: `docs/how-to/run-mongodb-migrations.md`, `docs/how-to/README.md`, `docs/reference/*`, `docs/how-to/seed-a-database.md`, `plugins/terreno-planning/skills/mongoose-schema-safety/SKILL.md` (canonical then sync), `CHANGELOG.md`
+  - Blocked by: 3.2, 4.1, 6.1, 7.1 (content must match shipped CLI/UI)
+  - Skills: `update-docs`
+  - Acceptance: stranger can generate → dry-run → up from the how-to; skill no longer points only at ad-hoc `ScriptRunner` backfills

package/src/docs/versioned/57.15.0/tasks/native-module-baseline.md

@@ -0,0 +1,42 @@
+# Tasks: Native module baseline for the next major release
+
+IP: [native-module-baseline](../implementationPlans/native-module-baseline.md)
+
+## Phase 1 — Dependencies + config
+
+- [ ] **Task 1.1**: Catalog + app package manifests
+  - Description: add the seven packages to root catalog (sorted) and to example-frontend + demo deps via `catalog:`
+  - Files: root `package.json`, `example-frontend/package.json`, `demo/package.json`
+  - Depends on: none
+  - Acceptance: `bun install` + full compile green
+- [ ] **Task 1.2**: Config plugins + build properties
+  - Description: stripe + purchases plugins; `expo-build-properties` Kotlin 2.x / compileSdk 36 pins
+  - Files: `example-frontend/app.json`, `demo/app.json`
+  - Depends on: 1.1
+  - Acceptance: `expo config` resolves without errors; web export unaffected
+
+## Phase 2 — Builds + verification
+
+- [ ] **Task 2.1**: EAS dev builds
+  - Description: iOS + Android dev-client builds via existing eas-dev-build workflow
+  - Files: `eas.json` profiles if needed
+  - Depends on: Phase 1
+  - Acceptance: both builds compile
+- [ ] **Task 2.2**: Diagnostics story
+  - Description: hidden demo story listing resolved native module versions
+  - Files: `demo/stories/NativeModules.stories.tsx`, `demo/demoConfig.tsx`
+  - Depends on: 2.1
+  - Acceptance: story shows all seven modules on a dev build; screenshot evidence
+- [ ] **Task 2.3**: Expo Go degradation doc
+  - Description: document which flows need a dev build (stripe, local-auth) vs preview modes (purchases)
+  - Files: `docs/` upgrade note draft
+  - Depends on: 2.1
+  - Acceptance: reviewed checklist in the note
+
+## Phase 3 — Release
+
+- [ ] **Task 3.1**: Upgrade note + major release coordination
+  - Description: consumer checklist (rebuild dev clients, add plugins, merchant id); breaking-release CI gate
+  - Files: upgrade notes location per release process
+  - Depends on: Phase 2
+  - Acceptance: breaking-release CI gate passes on the release PR

package/src/docs/versioned/57.15.0/tasks/notification-center.md

@@ -0,0 +1,102 @@
+# Tasks: In-app notification center
+
+IP: [notification-center.md](../implementationPlans/notification-center.md)  
+**Closes:** https://github.com/TerrenoLabs/terreno/issues/1179
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (inbox write + sync)
+
+- [x] **Task 1.1**: Notification model + `NotificationsApp` + `notify()` inbox write
+  - Delivers: `new NotificationsApp()` registers owner-scoped `/notifications` with `create: []`, `sync: {scope: {type: "owner"}}`, `isDeletedPlugin` + `syncPlugin`; `getNotificationService().notify({userId, title, body, href?, kind?})` inserts a row and change-stream/sync can see it; HTTP/sync create is 403/nack
+  - Files: `api/src/models/notification.ts`, `api/src/types/notification.ts`, `api/src/notifications/notificationsApp.ts`, `api/src/notifications/notificationService.ts`, `api/src/notifications/notificationsApp.test.ts`, `api/src/index.ts`
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `update-docs`
+  - Docs: stub **In-app notifications** in `docs/reference/api.md` (do not mix with Slack/Zoom notifiers)
+  - Acceptance: bun + supertest — `notify` creates one owner row; unauthenticated list 401; other user cannot read; POST `/notifications` 403 or disabled; every schema field has `description`
+
+- [x] **Task 1.2**: Owner mark-read and dismiss
+  - Delivers: `preUpdate` allows only `readAt` (ISO/date or `null`); `delete` soft-deletes; other fields in PATCH are stripped/rejected; unread query is `readAt` unset/null
+  - Files: `api/src/notifications/notificationsApp.ts`, tests in `notificationsApp.test.ts`
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: one sentence on patch/delete in the api.md stub
+  - Acceptance: bun tests — PATCH `{readAt}` persists; PATCH `{title: "x"}` does not change title; DELETE hides from list; second user 403
+
+## Phase 2 — Preferences, comms fan-out, retention
+
+- [x] **Task 2.1**: Preference model + defaults + `notificationsBeforeSend`
+  - Delivers: `NotificationPreference` unique `ownerId`, four booleans default true; missing row treated as all on; export duck-typed `notificationsBeforeSend({channel, userId})` that cancels when that boolean is false (`verification` channel never cancelled by this hook)
+  - Files: `api/src/models/notificationPreference.ts`, `api/src/types/notificationPreference.ts`, preference router on `NotificationsApp`, tests
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`
+  - Docs: prefs table in api.md stub
+  - Acceptance: bun tests — no row → beforeSend does not cancel; `mail: false` → `{cancel: true}` for `channel: "mail"`; inapp false → `notify` does **not** insert a Notification
+
+- [x] **Task 2.2**: Optional comms fan-out from `notify()`
+  - Delivers: `NotificationsApp({getComms})`; after inbox write, call `sendMail` / `sendSms` / `sendPushToUser` when that pref is on and destination exists (email from User, phone if present on user, push via comms); missing `getComms` or missing destination skips that channel without failing `notify`; do not import `@terreno/comms` from `@terreno/api`
+  - Files: `api/src/notifications/notificationService.ts`, tests with a fake `getComms`
+  - Blocked by: 2.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: fan-out order in api.md
+  - Acceptance: bun tests — fake mail called when pref on + email present; mail not called when pref off; `notify` resolves when `getComms` throws after inbox write (log `logger.error`, still return the notification id)
+
+- [x] **Task 2.3**: Mark-all-read + `retainDays`
+  - Delivers: `POST /notifications/mark-all-read` sets `readAt` on the caller's unread rows; `retainDays` default `0` (no sweep); `retainDays > 0` tombstones (`deleted`) rows with `created` older than N days (best-effort on `notify` and/or a small `sweepExpired()`); **no** Mongo TTL index
+  - Files: `notificationsApp.ts`, `notificationService.ts`, tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: `retainDays` default 0 in api.md
+  - Acceptance: bun tests — mark-all-read only affects caller; retainDays 0 leaves old rows; retainDays 1 tombstones a row dated 2 days ago via Luxon; collection indexes do not include a TTL expireAfterSeconds on Notification
+
+## Phase 3 — UI
+
+- [x] **Task 3.1**: `NotificationBell` + `NotificationInbox`
+  - Delivers: presentational components (no syncdb import); bell shows badge from `unreadCount`; inbox lists items, mark read/unread, dismiss, tap calls `onOpen`; empty and loading states; `testID`s
+  - Files: `ui/src/NotificationBell.tsx`, `ui/src/NotificationInbox.tsx`, tests, `ui/src/index.tsx` exports
+  - Blocked by: none
+  - Skills: `terreno-ui`, `update-docs`, `verify-ui-changes`
+  - Docs: stub props in `docs/reference/ui.md`
+  - Acceptance: bun `ui` tests with `renderWithTheme`; badge hidden at 0; `onOpen` fired with the item; dismiss/mark callbacks fired
+
+- [x] **Task 3.2**: `NotificationPreferences`
+  - Delivers: four `BooleanField`s bound to `{inapp, mail, push, sms}`; `onChange` per channel
+  - Files: `ui/src/NotificationPreferences.tsx`, test, export
+  - Blocked by: none
+  - Skills: `terreno-ui`
+  - Docs: prefs props in ui.md
+  - Acceptance: bun tests — toggling mail calls `onChange("mail", false)`
+
+- [x] **Task 3.3**: Demo stories
+  - Delivers: demoConfig entries with fixture unread/read items and prefs toggles
+  - Files: `demo/stories/` + `demo/demoConfig.tsx` (or current demo registration)
+  - Blocked by: 3.1, 3.2
+  - Skills: `terreno-ui`, `verify-ui-changes`
+  - Docs: none (4.1)
+  - Acceptance: demo route renders bell + inbox + prefs without a backend
+
+## Phase 4 — Example app + docs
+
+- [x] **Task 4.1**: example-backend register + demo notify
+  - Delivers: `NotificationsApp({getComms: getCommsService})`; compose `notificationsBeforeSend` into `CommsApp` `beforeSend`; authenticated demo route (follow `commsDev`) that `notify`s the current user
+  - Files: `example-backend/src/server.ts`, `example-backend/src/api/` demo route + test
+  - Blocked by: 2.2, 2.3
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: none (4.3)
+  - Acceptance: bun tests — registered routes exist; demo notify 401 without auth; 200 with auth creates a row
+
+- [x] **Task 4.2**: example-frontend syncdb + bell + prefs
+  - Delivers: collections `notifications` and `notification-preferences`; bell on todos header; settings preferences screen; `onOpen` uses Expo Router for in-app `href`; optional “send test” calling the demo route
+  - Files: `example-frontend/store/syncdb.ts` (codegen/list), todos screen, settings route, tests if present
+  - Blocked by: 3.1, 3.2, 4.1
+  - Skills: `terreno-data-fetching`, `terreno-ui`, `verify-ui-changes`, `generate-sdk` (only if a non-sync demo route needs SDK)
+  - Docs: none (4.3)
+  - Acceptance: `useQuery` lists notify rows after demo send; mark read persists; prefs toggle survives reload (syncdb); no new RTK CRUD hooks for the collection
+
+- [x] **Task 4.3**: Diátaxis docs + rules + changelog
+  - Delivers: `docs/how-to/in-app-notifications.md`; finish `docs/reference/api.md` and `docs/reference/ui.md`; `docs/reference/comms.md` beforeSend composition; `docs/how-to/README.md` link; `.rulesync/rules/api` mention + `bun run rules`; `changelog/unreleased/notification-center.md`
+  - Files: those docs + rules
+  - Blocked by: 4.2
+  - Skills: `update-docs`
+  - Docs: (this task)
+  - Acceptance: a stranger can register the plugin and wire the bell from the how-to without reading the IP; website/how-to index lists the page

package/src/docs/versioned/57.15.0/tasks/offline-mode.md

@@ -0,0 +1,141 @@
+# Task List: Offline Mode
+
+**Status:** Closed (2026-08-20) — IP deferred; superseded by `@terreno/syncdb`. Open tasks below will not be executed.
+
+*Structured task breakdown for automated implementation. Each task should be independently implementable and testable.*
+
+## Phase 1: RTK Core Offline Framework
+
+- [ ] **Task 1.1**: Formalize offline state and queue record types
+  - Description: Extend the offline slice state to represent connection quality, auth-blocked replay, queue record statuses, base timestamps, optimistic/server IDs, and persisted queue versioning. Keep the slice default inert until offline mode is mounted by a consuming app.
+  - Files: `rtk/src/offlineSlice.ts`, `rtk/src/useOfflineStatus.ts`, `rtk/src/index.ts`, related `rtk/src/*.test.ts`
+  - Depends on: none
+  - Acceptance: Unit tests cover enqueue/dequeue/status transitions, conflict storage, auth-blocked state, queue version defaults, and selectors for `online`, `spotty`, `offline`, queued mutations, conflicts, and replay-paused state.
+
+- [ ] **Task 1.2**: Replace endpoint-name-only offline gating with modelRouter config
+  - Description: Introduce a typed `OfflineModelRouterConfig` that maps model names and modelRouter operations to generated RTK Query endpoint names. Preserve a migration path for existing endpoint-name configuration only if it is already shipped behavior; otherwise replace it with the modelRouter config.
+  - Files: `rtk/src/offlineGate.ts`, `rtk/src/offlineMiddleware.ts`, `rtk/src/index.ts`, `rtk/src/offlineGate.test.ts`
+  - Depends on: Task 1.1
+  - Acceptance: Tests prove disabled/default config never defers mutations, enabled modelRouter endpoints are deferred while offline, unconfigured custom routes are not deferred, and array operations can be configured separately from create/update/delete.
+
+- [ ] **Task 1.3**: Add optimistic create ID strategy
+  - Description: Add default ObjectId-compatible ID generation for optimistic modelRouter creates, inject the generated ID into the configured request field, and support per-model overrides for `generateId`, request field, and server ID reconciliation strategy.
+  - Files: `rtk/src/offlineMiddleware.ts`, `rtk/src/offlineGate.ts`, `rtk/src/offlineIds.ts` (new if useful), `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.2
+  - Acceptance: Tests verify default IDs are stable and ObjectId-shaped, custom generators are used, optimistic create cache entries use the same local ID as the queued mutation, and a server-returned replacement ID can be mapped when explicitly configured.
+
+- [ ] **Task 1.4**: Harden optimistic cache update strategies
+  - Description: Make optimistic cache updates explicit per modelRouter operation while providing safe defaults for create, update, delete, array push, array update, and array remove. Expose an override hook so app teams can customize cache updates for complex list filters or response shapes.
+  - Files: `rtk/src/offlineMiddleware.ts`, `rtk/src/offlineOptimistic.ts` (new if useful), `rtk/src/useOfflineStatus.ts`, related tests
+  - Depends on: Task 1.3
+  - Acceptance: Tests cover optimistic insert, patch, remove, and array mutations against RTK Query cache entries, including rollback or conflict marking when replay fails with a non-network/non-auth error.
+
+- [ ] **Task 1.5**: Pause replay on auth refresh failure without clearing cache
+  - Description: Separate token-refresh failure from explicit logout. If refresh cannot complete because the server/network is unavailable or refresh returns a retryable failure, mark replay as auth-blocked and keep RTK Query cache, queue, conflicts, and optimistic records intact. Reserve destructive cleanup for the actual logout action.
+  - Files: `rtk/src/emptyApi.ts`, `rtk/src/authSlice.ts`, `rtk/src/offlineMiddleware.ts`, `rtk/src/offlineSlice.ts`, related tests
+  - Depends on: Task 1.1
+  - Acceptance: Tests simulate expired access tokens with unreachable refresh endpoint and verify queued mutations are held, cache data remains, and replay resumes after auth is refreshed; explicit logout still clears tokens and configured offline/cache state.
+
+- [ ] **Task 1.6**: Implement keep-mine and use-server conflict resolution
+  - Description: Add conflict resolution actions/helpers. `useServer` should discard the queued mutation and patch cache to the server value. `keepMine` should update the queued mutation with the latest server timestamp, reapply the local optimistic value, and retry replay with fresh precondition headers.
+  - Files: `rtk/src/offlineSlice.ts`, `rtk/src/offlineMiddleware.ts`, `rtk/src/useOfflineStatus.ts`, `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.4
+  - Acceptance: Tests cover `409 Conflict` replay responses, stored local/server values, resolving with `useServer`, resolving with `keepMine`, and preventing duplicate conflict records for the same queued mutation.
+
+## Phase 2: Connection Quality and UI
+
+- [ ] **Task 2.1**: Upgrade server status monitoring to connection quality
+  - Description: Extend `useServerStatus` to compute `online`, `spotty`, and `offline` from browser/native reachability events, health-check failures, latency, and recent failure rate. Make health URL, interval, timeout, latency threshold, failure count, and failure-rate thresholds configurable.
+  - Files: `rtk/src/useServerStatus.ts`, `rtk/src/offlineSlice.ts`, `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.1
+  - Acceptance: Tests cover all three connection states, threshold overrides, transition from spotty back to online, transition to offline after configured consecutive failures, and no polling when status monitoring is disabled.
+
+- [ ] **Task 2.2**: Expose richer offline status hooks
+  - Description: Expand `useOfflineStatus` to return connection quality, queue length, syncing state, auth-blocked state, conflicts, local-only helpers, and conflict resolution callbacks while preserving low-level selectors for custom UI.
+  - Files: `rtk/src/useOfflineStatus.ts`, `rtk/src/offlineSlice.ts`, `rtk/src/index.ts`, related tests
+  - Depends on: Task 1.6, Task 2.1
+  - Acceptance: Hook tests or focused unit tests verify returned state and callbacks for queued, syncing, auth-blocked, conflicted, local-only, and healthy states.
+
+- [ ] **Task 2.3**: Update offline banner for online, spotty, offline, syncing, and auth-blocked states
+  - Description: Evolve `OfflineBanner` so apps can show offline, spotty connection, syncing queued changes, pending changes, and auth-blocked sync messaging. Keep props simple enough for custom state sources.
+  - Files: `ui/src/OfflineBanner.tsx`, `ui/src/index.tsx`, `ui/src/OfflineBanner.test.tsx` (new if absent), `demo/stories/OfflineBanner.stories.tsx` (new or update)
+  - Depends on: Task 2.1
+  - Acceptance: UI tests or stories cover hidden/online, spotty, offline, syncing, pending queue, and auth-blocked variants with clear copy and accessible test IDs.
+
+- [ ] **Task 2.4**: Add conflict resolution UI components
+  - Description: Add reusable conflict UI that renders unresolved conflicts and lets users choose "Keep mine" or "Use server". Keep it generic by accepting display renderers for local and server values.
+  - Files: `ui/src/OfflineConflictList.tsx` (new), `ui/src/OfflineConflictCard.tsx` (new), `ui/src/index.tsx`, `ui/src/*.test.tsx`, `demo/stories/OfflineConflict*.stories.tsx`
+  - Depends on: Task 2.2
+  - Acceptance: Tests or stories cover no-conflict, single-conflict, multiple-conflict, keep-mine click, use-server click, dismissed/resolved conflict filtering, and custom value rendering.
+
+## Phase 3: modelRouter Backend Contract
+
+- [ ] **Task 3.1**: Verify client-provided modelRouter create IDs
+  - Description: Add backend tests that prove modelRouter create accepts a client-provided ObjectId-compatible `_id` when the schema allows it and rejects invalid IDs through existing validation/error handling.
+  - Files: `api/src/api.ts`, `api/src/tests/*.test.ts` or existing modelRouter test file, `api/src/tests.ts`
+  - Depends on: Task 1.3
+  - Acceptance: API tests pass for create with client `_id`, returned document keeps that `_id`, duplicate IDs fail safely, and invalid IDs return a clear validation/error response.
+
+- [ ] **Task 3.2**: Formalize conflict response tests for modelRouter updates
+  - Description: Add/extend modelRouter tests for `If-Unmodified-Since` and `X-Unmodified-Since-ISO` headers to guarantee stale updates return `409 Conflict` with the current server document and fresh updates succeed.
+  - Files: `api/src/api.ts`, `api/src/tests/*.test.ts` or existing modelRouter test file
+  - Depends on: none
+  - Acceptance: API tests cover conflict by HTTP-date header, conflict by ISO header, success with current timestamp, missing timestamp behavior, and response body shape consumed by `@terreno/rtk`.
+
+- [ ] **Task 3.3**: Document the modelRouter offline contract
+  - Description: Add docs for modelRouter offline compatibility: supported CRUD/array endpoints, client-provided IDs, conflict headers, expected `409` response shape, permissions behavior, and explicit non-support for custom sync endpoints in v1.
+  - Files: `api/README.md` or package docs, `rtk/README.md` or package docs, `docs/implementationPlans/offline-mode.md`
+  - Depends on: Task 3.1, Task 3.2
+  - Acceptance: Docs show a modelRouter route configuration and matching frontend offline config, and clearly state that custom route sync is future work.
+
+## Phase 4: Example App Integration
+
+- [ ] **Task 4.1**: Enable offline mode for example todos
+  - Description: Wire the example frontend store to mount the offline reducer, persist the offline slice, configure todos modelRouter endpoints for offline create/update/delete, and keep API cache persistence consistent with the offline plan.
+  - Files: `example-frontend/store/index.ts`, `example-frontend/store/sdk.ts`, `example-frontend/app/_layout.tsx`, `example-frontend/package.json` if scripts need updates
+  - Depends on: Task 1.6, Task 2.2
+  - Acceptance: Example app can create, update, and delete todos while offline; queued todos survive app reload when persistence is enabled; replay syncs after the backend is reachable again.
+
+- [ ] **Task 4.2**: Integrate connection banner and sync state in the example app
+  - Description: Add root-level status monitoring and display `OfflineBanner` for offline, spotty, syncing, pending queue, and auth-blocked states. Ensure copy is visible without disrupting auth navigation.
+  - Files: `example-frontend/app/_layout.tsx`, `example-frontend/app/(tabs)/_layout.tsx`, `example-frontend/app/(tabs)/index.tsx`
+  - Depends on: Task 2.3, Task 4.1
+  - Acceptance: Manual test can trigger offline/spotty/syncing/auth-blocked states and see the correct banner copy and pending queue count.
+
+- [ ] **Task 4.3**: Add example conflict resolution flow
+  - Description: Show unresolved todo conflicts in the example app and wire "Keep mine" / "Use server" actions to the RTK conflict resolution helpers.
+  - Files: `example-frontend/app/(tabs)/index.tsx`, `example-frontend/components/*` if a local wrapper is useful
+  - Depends on: Task 2.4, Task 4.1
+  - Acceptance: Manual test can create a stale update conflict, see local/server values, choose "Use server" to accept server state, and choose "Keep mine" to replay local state.
+
+- [ ] **Task 4.4**: Add example backend support tests or fixtures for offline scenarios
+  - Description: Ensure the example backend todo model and route can support client IDs and conflict timestamps. Add tests or fixtures that make the example integration verifiable without modifying generated SDK files manually.
+  - Files: `example-backend/src/models/todo.ts`, `example-backend/src/api/todos.ts`, `example-backend/src/**/*.test.ts`
+  - Depends on: Task 3.1, Task 3.2
+  - Acceptance: Example backend tests pass and confirm todos work with the modelRouter offline contract.
+
+## Phase 5: Verification, Documentation, and Release Readiness
+
+- [ ] **Task 5.1**: Add package-level offline mode docs
+  - Description: Write consumer documentation for enabling offline mode, configuring modelRouter endpoints, selecting ID strategy, configuring connection quality, handling auth-blocked replay, and rendering conflict UI.
+  - Files: `rtk/README.md`, `ui/README.md` if present, `docs/implementationPlans/offline-mode.md`
+  - Depends on: Task 1.6, Task 2.4, Task 3.3
+  - Acceptance: Docs include copy-pasteable store setup, model config, status hook usage, `OfflineBanner`, and conflict resolution examples.
+
+- [ ] **Task 5.2**: Add end-to-end manual verification guide
+  - Description: Document the exact local steps to verify offline create/update/delete, replay, auth-blocked behavior, spotty status, and conflict resolution using example backend and frontend.
+  - Files: `docs/offline-mode-verification.md` (new) or relevant docs directory, `docs/implementationPlans/offline-mode.md`
+  - Depends on: Task 4.3
+  - Acceptance: Guide lists setup commands, offline simulation steps, expected UI states, and cleanup steps; it does not require editing generated SDK files manually.
+
+- [ ] **Task 5.3**: Run focused validation suite
+  - Description: Run and fix failures for the focused packages touched by offline mode.
+  - Files: no source changes expected unless validation finds failures
+  - Depends on: Task 5.1, Task 5.2
+  - Acceptance: `bun run rtk:compile` or equivalent package compile passes, `bun run ui:test` passes for new UI tests, `bun run api:test` passes for modelRouter tests, and example package checks used by the repo pass or have documented blockers.
+
+- [ ] **Task 5.4**: Regenerate SDK only if backend API surface changes
+  - Description: If implementation changes OpenAPI output for modelRouter conflict responses or example backend route schemas, regenerate `example-frontend/store/openApiSdk.ts` using the SDK generation workflow. If no OpenAPI surface changed, explicitly skip this task in the implementation PR notes.
+  - Files: `example-frontend/store/openApiSdk.ts`, `example-frontend/openapi-config.ts`
+  - Depends on: Task 3.3, Task 4.4
+  - Acceptance: Generated SDK is updated only from the backend OpenAPI spec and never edited manually; PR notes state whether SDK regeneration was required.

package/src/docs/versioned/57.15.0/tasks/org-management-ui.md

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

package/src/docs/versioned/57.15.0/tasks/orgs-and-teams.md

@@ -0,0 +1,72 @@
+# Tasks: Organizations, teams, and multi-tenant scoping
+
+**Superseded.** Do not execute. Canonical tasks: [org-management-ui](org-management-ui.md).
+
+IP: [orgs-and-teams](../implementationPlans/orgs-and-teams.md) (superseded by [org-management-ui](../implementationPlans/org-management-ui.md))
+
+## Phase 1 — Models + plugin
+
+- [ ] **Task 1.1**: Organization + Membership models
+  - Description: schemas per IP (five-type pattern, descriptions, plugins, compound unique index), statics `findActiveForUser`/`isMember`/`isOrgAdmin`
+  - Files: `api/src/orgs/organizationModel.ts`, type files
+  - Depends on: none
+  - Acceptance: unit tests incl. duplicate-membership rejection
+- [ ] **Task 1.2**: `orgScopedPlugin`
+  - Description: adds required indexed `organizationId` to a schema
+  - Files: `api/src/orgs/orgPlugin.ts`
+  - Depends on: 1.1
+  - Acceptance: plugin test on a sample schema; save without org fails
+
+## Phase 2 — Context + permissions
+
+- [ ] **Task 2.1**: Org context middleware
+  - Description: `X-Organization-Id` → `req.organization`/`req.membership`; 403 on non-membership; no header → no context
+  - Files: `api/src/orgs/orgContext.ts`
+  - Depends on: 1.1
+  - Acceptance: supertest for member/non-member/missing header
+- [ ] **Task 2.2**: `IsOrgMember`, `IsOrgAdmin`, `OrgQueryFilter`
+  - Description: permission methods + query filter (header-scoped or all-memberships)
+  - Files: `api/src/orgs/orgPermissions.ts`
+  - Depends on: 2.1
+  - Acceptance: **tenant isolation suite** — org A member never reads org B rows, incl. crafted `$or`/query-param attempts
+- [ ] **Task 2.3**: modelRouter integration + `preCreate` org injection helper
+  - Description: end-to-end org-scoped CRUD on a test model
+  - Files: `api/src/orgs/*`, `api/src/tests.ts`
+  - Depends on: 2.2
+  - Acceptance: create injects context org; list/read/update/delete respect scope
+
+## Phase 3 — Routes + app
+
+- [ ] **Task 3.1**: `OrgsApp` plugin + org CRUD routes
+  - Description: create (with `maxOrgsPerUser`), list-my-orgs, read, patch, soft delete with membership cascade
+  - Files: `api/src/orgs/orgsApp.ts`
+  - Depends on: Phase 2
+  - Acceptance: supertest per route; OpenAPI entries present
+- [ ] **Task 3.2**: Member management routes + last-admin guards
+  - Description: list/patch/delete members; cannot demote/remove last admin
+  - Files: `api/src/orgs/orgsApp.ts`
+  - Depends on: 3.1
+  - Acceptance: guard tests pass
+- [ ] **Task 3.3**: `onOrgAudit` hook + exports
+  - Description: audit hook mirroring `onAdminAudit`; public exports from `@terreno/api`
+  - Files: `api/src/orgs/orgsApp.ts`, `api/src/index.ts`
+  - Depends on: 3.1
+  - Acceptance: hook fires for create/role-change/delete in tests
+
+## Phase 4 — Example + docs
+
+- [ ] **Task 4.1**: example-backend org-scoped `Project` model + routes + seeds
+  - Description: demo model with `orgScopedPlugin` + `OrgQueryFilter`; seed two orgs with distinct data
+  - Files: `example-backend/src/models/project.ts`, `src/api/projects.ts`, `scripts/seed*`
+  - Depends on: Phase 3
+  - Acceptance: seeded backend proves isolation via curl/supertest
+- [ ] **Task 4.2**: Admin registration + SDK regen
+  - Description: register Organization/Membership in AdminApp; `cd example-frontend && bun run sdk`
+  - Files: `example-backend/src/server.ts`, `example-frontend/store/openApiSdk.ts`
+  - Depends on: 4.1
+  - Acceptance: admin panel lists orgs; SDK compiles
+- [ ] **Task 4.3**: Docs
+  - Description: `docs/how-to/add-organizations.md`, reference updates, rulesync
+  - Files: `docs/how-to/add-organizations.md`, `docs/reference/api.md`, `.rulesync/**`
+  - Depends on: Phase 3
+  - Acceptance: `bun run rules:check` passes