@terreno/mcp 57.17.0 → 57.19.2

package/src/docs/versioned/57.1.0/tasks/feature-flags-openfeature.md

@@ -1,77 +0,0 @@
-# Feature Flags → OpenFeature — Task List
-
-See `docs/implementationPlans/feature-flags-openfeature.md` for full details.
-
-## Phase 0: Catalog & deps
-
-- [x] **0.1** Add `@openfeature/server-sdk`, `@openfeature/web-sdk`, `@openfeature/react-sdk`, `@openfeature/core` to the root `package.json` `catalog` (pin minor; check latest at time of work). Verify with `bun install` from root.
-
-## Phase 1: Backend OpenFeature integration
-
-- [x] **1.1** Add `@openfeature/server-sdk` (catalog version) to `feature-flags/package.json` dependencies. Run `bun install`.
-- [x] **1.2** Add `defaultVariant` field to `FeatureFlag` schema (`feature-flags/src/featureFlagModel.ts`) with description and validation. **No getter** — use a `pre("save")` hook that populates `defaultVariant` when undefined (boolean → "off"; variant → first variant key). Validation: if set, boolean must be `"on"`/`"off"`; variant must be one of `variants[].key`. Add `defaultVariant` to `featureFlagAdminConfig.listFields`.
-- [x] **1.3** Update `FeatureFlagDocument` type in `feature-flags/src/types.ts` with optional `defaultVariant`. Add `FlagDefinition` and `FlagConfigurationResponse` interfaces.
-- [x] **1.4** Create `feature-flags/src/openFeatureProvider.ts` exporting `MongoFeatureFlagProvider` implementing OpenFeature's `Provider` interface. Use `findOneOrNone` (per repo rule — never `findOne`). Returns `FLAG_NOT_FOUND` / `TYPE_MISMATCH` `ResolutionDetails` shapes for missing or wrong-type flags. Delegates the targeting math to existing `evaluateFlag()`.
-- [x] **1.5** Update `FeatureFlagsApp.register()` (`feature-flags/src/featureFlagsApp.ts`): construct provider, call `OpenFeature.setProvider(domain, provider)` (default domain `"feature-flags"`), register new `/flagConfiguration` route, keep `/evaluate` with `Deprecation: true` + `Sunset: <90d>` headers + one-shot warn log.
-- [x] **1.6** Add `buildFlagDefinition(flag, targetingKey, user, segments)` helper. **Critical filter**: `/flagConfiguration` matches today's `evaluateAllFlags` filter (`archived: $ne true, enabled: true`) — disabled flags are omitted entirely. Every returned `FlagDefinition` has `disabled: false`.
-- [x] **1.7** Update `FeatureFlagsOptions` type (`feature-flags/src/types.ts`) to add `liveUpdates` and `openFeatureDomain` fields.
-- [x] **1.8** Update `feature-flags/src/index.ts` to export `MongoFeatureFlagProvider`, `FlagDefinition`, `FlagConfigurationResponse`.
-- [x] **1.9** Add `feature-flags/src/tests/openFeatureProvider.test.ts` covering: boolean and variant resolution; disabled flag returns default + reason "DISABLED"; `TYPE_MISMATCH` on wrong-type call; `FLAG_NOT_FOUND` on missing flag; rule-match path; segment-match path; deterministic-hash path; missing `targetingKey`; variant default fallback; `resolveNumberEvaluation` and `resolveObjectEvaluation` return `FLAG_NOT_FOUND`.
-- [x] **1.10** Extend `feature-flags/src/tests/featureFlagsApp.test.ts`: `/flagConfiguration` returns the right shape for both flag types; **explicitly verifies disabled flags are OMITTED**; verifies `defaultVariant` flows through; verifies `/evaluate` still works AND now includes `Deprecation` + `Sunset` headers. Add `featureFlagModel.test.ts` (or extend existing tests) with: legacy doc (no `defaultVariant`) can be saved and the hook populates a default; explicit `defaultVariant: "on"` on boolean passes; `defaultVariant: "bad"` on boolean is rejected.
-- [x] **1.11** Run `bun run --filter=@terreno/feature-flags compile test lint`. Fix issues.
-
-## Phase 2: Frontend OpenFeature integration
-
-- [x] **2.0 (blocking spike)** Verify `@openfeature/react-sdk` works under React Native. Write a tiny `bun test` using `@testing-library/react-native` that wraps a component in `<OpenFeatureProvider>` with a `TypedInMemoryProvider` and asserts `useBooleanFlagValue("k", false)` returns `true` after `PROVIDER_READY`. If it fails on RN, fall back to importing only from `@openfeature/web-sdk` and writing a thin React adapter inside `@terreno/rtk` that uses `useSyncExternalStore` against the OF client's event emitter. Do not proceed to 2.1 until this is green.
-- [x] **2.1** Add `@openfeature/web-sdk` + `@openfeature/react-sdk` as **peerDependencies** (NOT direct deps) in `rtk/package.json`. Add `@openfeature/core` as a direct dep for types. Run `bun install` from root.
-- [x] **2.2** Create `rtk/src/useTerrenoFeatureFlags.ts`. Critical behaviors:
-  - RTK Query endpoint cache key includes `userId` so user switching invalidates cache.
-  - On data success, `await OpenFeature.setProvider(domain, new TypedInMemoryProvider(data))`; subscribe to `PROVIDER_READY` via `client.addHandler`.
-  - `isLoading` stays `true` until BOTH RTK has data AND `PROVIDER_READY` has fired (gated by a ref-tracked boolean).
-  - On `userId` change: `OpenFeature.setContext(domain, {targetingKey: userId})` BEFORE the refetch resolves.
-  - Module-level ref counter for provider lifetime; do not clear provider on individual unmount; clear only when count returns to zero (last consumer leaves).
-  - StrictMode safety: ref tracks in-flight `setProvider` promise to dedupe double-effect.
-  - If `options.socket` is provided, subscribe to `socketEventName ?? "featureFlagsChanged"` → `refetch()`. Cleanup on unmount.
-  - Return `{flags, isLoading, error, refetch, client}`.
-- [x] **2.3** Rewrite `rtk/src/useFeatureFlags.ts` as a BC wrapper over `useTerrenoFeatureFlags`. Preserve overloaded signature (`string | UseFeatureFlagsOptions`). `getFlag` uses `client.getBooleanValue(key, false)`. `getVariant` returns `null` when `!flags[key]` (the flag is disabled/missing — disabled flags are filtered out of `/flagConfiguration`); otherwise returns `client.getStringValue(key, "") || null`. Build `flatFlags: Record<string, boolean | string | null>` from the raw `FlagConfiguration` map by projecting each `FlagDefinition`: boolean → `variants[defaultVariant]`, variant → `defaultVariant`. Add explicit type tests.
-- [x] **2.4** Update `rtk/src/index.ts` to export `useTerrenoFeatureFlags` and its types. Do **not** re-export OpenFeature hooks (consumers add `@openfeature/react-sdk` directly).
-- [x] **2.5** Update `rtk/src/useFeatureFlags.test.ts` to match the new wire shape. Cover: legacy options shape (string), modern options shape (object), `skip`, `getFlag`/`getVariant` for boolean and variant flags, `null` on disabled/missing, timing logs preserved, **snapshot test** locking the `flatFlags` projection so `profile.tsx`'s render output is byte-identical to before.
-- [x] **2.6** Add `rtk/src/useTerrenoFeatureFlags.test.ts` covering: provider is set on success; `isLoading` stays `true` until `PROVIDER_READY`; domain isolation (default provider not affected); refetch path; no-op when `skip: true`; `userId` change triggers context + refetch + provider replacement; StrictMode double-mount does not double-set provider; ref count prevents premature provider clearing; socket event triggers refetch.
-- [x] **2.7** Run `bun run --filter=@terreno/rtk compile test lint`. Fix issues.
-
-## Phase 3: Live updates (opt-in)
-
-- [x] **3.1** In `FeatureFlagsApp.register()`, when `options.liveUpdates?.socketIoServer` is provided (accept either a value or a `() => Server | null` getter — example-backend's `io` is lazily initialized), start `FeatureFlag.watch([], {fullDocument: "updateLookup"})`. On each change, emit `featureFlagsChanged` (configurable event name) plus call `provider.emitConfigurationChanged()`. Log on stream `error`; one auto-reconnect attempt, then disable + warn.
-- [x] **3.2** Add `feature-flags/src/tests/featureFlagsApp.liveUpdates.test.ts`. Test approach: **mock `FeatureFlag.watch`** to return a fake `EventEmitter` with the change-stream interface (`on`, `close`). The tests do NOT spin up a replica-set Mongo. Cover: emission on insert/update/delete (via emitting fake change events), custom event name, error handler logs a warn, double-error disables the stream.
-- [x] **3.3** In `useTerrenoFeatureFlags`, when `options.socket` is provided, subscribe to `options.socketEventName ?? "featureFlagsChanged"` and call `refetch()` on each event. Cleanup on unmount. Acknowledge that the emit is global broadcast (all connected clients) — no PII in the payload.
-- [x] **3.4** Add a test in `useTerrenoFeatureFlags.test.ts` proving: when a fake `EventEmitter` socket emits the event, the hook refetches and OF consumers re-render.
-- [x] **3.5** Document the Mongoose replica-set requirement (production must use a replica set, including single-node replica set) and Socket.io wiring in `docs/how-to/add-feature-flags.md` (new "Live updates" section). Also document the broadcast scope (flag-key payload visible to every authenticated socket) — acceptable since flag keys ship to every authed client via `/flagConfiguration` anyway.
-
-## Phase 4: Example apps + docs + SDK regen
-
-- [x] **4.1** Update `example-backend` `FeatureFlagsApp` construction to pass `liveUpdates: {socketIoServer: () => io}` — use a getter, since `example-backend/src/websockets.ts:24` initializes `io` lazily during `connectToWebsockets`.
-- [x] **4.2** Update `example-backend/src/scripts/seed-feature-flags.ts`: add `defaultVariant` to each `SEED_FLAGS` entry (`"off"` for boolean flags; for the `profile-layout` variant flag, `"compact"`). **Bump the seed**: either add a `seedVersion` field to FeatureFlag (skip if too invasive) OR add an idempotent "patch missing defaultVariant" upsert at the top of the script that updates existing docs in dev DBs to populate the new field. Document the dev-db backfill in the migration note.
-- [x] **4.3** Update `example-frontend/app/_layout.tsx` to wrap children in `<OpenFeatureProvider domain="feature-flags">` and call `useTerrenoFeatureFlags(terrenoApi, {socket, userId})` once user is authenticated.
-- [x] **4.4** Update `example-frontend/app/(tabs)/profile.tsx`: add a small section that uses `useBooleanFlagDetails("dark-mode-toggle", false)` and renders `reason` alongside value — verifies OF metadata is plumbed through and proves the `reason` field shape downstream.
-- [x] **4.5** Add `example-frontend/types/openfeature.d.ts` demonstrating the type-safe flag keys augmentation. Reference it from the docs.
-- [ ] **4.6** Regenerate frontend SDK: `cd example-frontend && bun run sdk`. Verify the new endpoint is in `openApiSdk.ts` and document that consumers should NOT call the generated hook directly; use `useTerrenoFeatureFlags`/`useFeatureFlags` instead.
-- [x] **4.7** Update `docs/reference/feature-flags.md`: new endpoint shape, `MongoFeatureFlagProvider` export, `defaultVariant` field semantics, recommended OF hooks for new code, BC notes, **number/object flag types not supported** (always returns default), **type-safe flag keys drift warning**, dev-db backfill note for existing seeded flags.
-- [x] **4.8** Update `docs/how-to/add-feature-flags.md`: recommend OF hooks for new code; show `useFeatureFlags` only in a "BC / migration" section.
-- [x] **4.9** Add a short note at the top of `docs/implementationPlans/feature-flags.md` linking to this new IP.
-- [x] **4.10** Add `example-frontend/e2e/feature-flags.spec.ts` Playwright test:
-  - Login as admin
-  - PATCH a flag via `/feature-flags/flags/:id` (e.g., toggle `enabled` on `todo-summary-card`)
-  - Within ~5s, assert the example-frontend's todos screen shows/hides the summary card accordingly **without** a page reload
-  - Verifies the full live-update loop (change stream → socket emit → hook refetch → OF re-render)
-  - Skip the test if the test environment does not have a Mongo replica set (use `test.skip` with a clear message) so CI doesn't fail when devs run without one.
-- [ ] **4.11** Run full workspace check: `bun run lint && bun run compile && bun run test`. Run example stack manually (`bun run backend:dev` + `bun run frontend:web`) and verify the profile screen shows flags identical to before.
-
-## Definition of Done
-
-- All workspace tests pass.
-- `example-frontend` runs end-to-end with seeded flags, showing identical values to before the migration.
-- Admin edits to a flag (via the admin panel) propagate to an open example-frontend session within ~1 second without a manual refresh.
-- A consumer using only `useFeatureFlags(api)` requires zero code changes.
-- A consumer can now also use `useBooleanFlagValue("key", false)` directly from `@openfeature/react-sdk`.
-- Type-safe flag keys augmentation is documented and demonstrated in `example-frontend`.
-- The legacy `/evaluate` endpoint still works, returns the old shape, and includes a `Deprecation` header.

package/src/docs/versioned/57.1.0/tasks/migrate-cicd-to-circleci.md

@@ -1,219 +0,0 @@
-# Task List: Migrate CI/CD to CircleCI
-
-See: [`docs/implementationPlans/migrate-cicd-to-circleci.md`](../implementationPlans/migrate-cicd-to-circleci.md)  
-Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../implementationPlans/migrate-cicd-to-circleci-research.md)
-
-## Instructions for the implementing agent
-
-- Dual-run every phase: CircleCI green → flip required checks → delete GHA twin. Never enable tag publish on both systems.
-- Do not store plaintext GCP JSON keys in CircleCI if OIDC is available; migrate `preview-cleanup` off `GCP_SA_KEY`.
-- Pin orb versions (including `circleci/node` with Bun support ≥7.2.0).
-- Prefer path parameters that mirror existing GHA path filters.
-- Update docs in the same PR that changes the source of truth for how CI runs.
-- After Phase 0, confirm CircleCI project follows the GitHub default branch `master`.
-
-## Phase 0: Prerequisites
-
-- [ ] **Task 0.1**: Confirm CircleCI org/plan and project link
-  - Description: Verify the requester-created CircleCI organization, plan, and that `TerrenoLabs/terreno` is connected with permission to report GitHub checks. Enable **dynamic config** / setup workflows for the project. Record org slug + project slug in the IP header or how-to doc.
-  - Files: `docs/how-to/circleci.md` (stub OK)
-  - Depends on: none (human prerequisite)
-  - Acceptance: a manual “hello” pipeline can be triggered from the project; dynamic config is enabled.
-  - Note: hello scaffold merged (#1052). Dynamic config + org slug still need maintainer confirmation.
-
-- [ ] **Task 0.2**: Create CircleCI Contexts (empty shells)
-  - Description: Create contexts named in the IP (`terreno-npm`, `terreno-netlify`, `terreno-expo`, `terreno-gcp`, `terreno-e2e`, `terreno-release`, `terreno-agentic`, `terreno-github-api`). Document which GitHub secrets map into each. Do not paste secret values into the repo.
-  - Files: `docs/how-to/circleci.md`
-  - Depends on: Task 0.1
-  - Acceptance: contexts exist; mapping table is complete; access restrictions noted for `terreno-release`.
-  - Note: mapping table documented in how-to; contexts themselves are still a human step.
-
-- [x] **Task 0.3**: Inventory required GitHub checks
-  - Description: List current branch-protection required checks and map each to the GHA job `name:` and the future CircleCI job name. Start from `docs/explanation/repository-settings.md` and live settings.
-  - Files: `docs/how-to/circleci.md` or a short table in the IP
-  - Depends on: none
-  - Acceptance: table covers policies, rulesync, package CI, fingerprint, and CD-related checks.
-
-## Phase 1: Foundation
-
-- [x] **Task 1.1**: Add setup + continue config skeleton
-  - Description: Create `.circleci/config.yml` with `setup: true` using `circleci/path-filtering` (and `circleci/continuation`). Create `.circleci/continue-config.yml` with parameters for each package/area and a no-op `config-ok` job that always runs.
-  - Files: `.circleci/config.yml`, `.circleci/continue-config.yml`
-  - Depends on: Task 0.1
-  - Acceptance: push triggers setup → continuation; `config-ok` is green.
-
-- [x] **Task 1.2**: Shared Bun + cache commands
-  - Description: Add reusable commands (inline or orb) for installing Bun via `circleci/node`, `bun install --frozen-lockfile`, and cache keys equivalent to today’s GHA bun cache. Pin Bun policy (`latest` vs pin) consistently with EAS jobs that need a pin.
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 1.1
-  - Acceptance: a sample job restores cache on second run; install is frozen-lockfile.
-
-- [x] **Task 1.3**: Path-filter mapping
-  - Description: Encode path → parameter mapping for api, ai, ui, rtk, comms, mcp-server, admin-*, example-*, demo, docs/website, terraform, e2e-relevant sets, matching current workflow path filters.
-  - Files: `.circleci/config.yml`
-  - Depends on: Task 1.1
-  - Acceptance: a docs-only change sets docs/deploy params without setting `run-api`.
-  - Note: deploy path params omitted until Phase 4+.
-
-## Phase 2: Package CI + policy
-
-- [x] **Task 2.1**: Port package CI jobs
-  - Description: Port api/ai/rtk/ui/ui-demo/comms/mcp-server/example-frontend/example-backend(+script)/admin-spa CI to CircleCI jobs gated by path params. Include Mongo service where GHA used it. Fix mcp branch filter to `master`.
-  - Files: `.circleci/continue-config.yml`, possibly package scripts unchanged
-  - Depends on: Task 1.2, Task 1.3
-  - Acceptance: dual-run green for each package on a change that touches it; GHA still required.
-
-- [x] **Task 2.2**: Port Docker build-only job
-  - Description: Port `example-backend-docker.yml` to CircleCI remote Docker / machine with layer caching replacement for `type=gha`.
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 2.1
-  - Acceptance: PR touching `example-backend/**` builds the image without pushing.
-
-- [x] **Task 2.3**: Port repo-policies + rulesync + DCO
-  - Description: Port `repo-policies.yml`, `rulesync-check.yml`, and fork DCO checks. DCO must use GitHub API via `terreno-github-api` context.
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 0.2, Task 1.2
-  - Acceptance: intentional barrel-import / dirty rulesync / missing DCO on a fork PR fails the CircleCI job.
-  - Note: DCO skips cleanly if `GITHUB_TOKEN` unset until context is created.
-
-- [ ] **Task 2.4**: Dual-run cutover for Phase 2
-  - Description: Add CircleCI checks to branch protection; remove GHA package/policy workflows once trusted; delete corresponding `.github/workflows/*-ci.yml` and policy workflows.
-  - Files: `.github/workflows/*`, `docs/explanation/repository-settings.md`
-  - Depends on: Task 2.1, Task 2.2, Task 2.3
-  - Acceptance: required checks are CircleCI-only for these surfaces; GHA files gone.
-
-## Phase 3: Playwright E2E
-
-- [x] **Task 3.1**: Port `e2e-ci` and `admin-spa-integration`
-  - Description: Mongo replica set, E2E secrets context, Playwright browsers, artifact store for reports. Skip Dependabot-equivalent if applicable.
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 2.1, Task 0.2
-  - Acceptance: matrix (or equivalent) passes on master; artifacts downloadable.
-
-- [ ] **Task 3.2**: Dual-run cutover for E2E
-  - Description: Flip required checks if any; delete GHA e2e/admin-spa-integration workflows.
-  - Files: `.github/workflows/e2e-ci.yml`, `admin-spa-integration.yml`, `admin-spa-ci.yml` as applicable
-  - Depends on: Task 3.1
-  - Acceptance: GHA twins deleted; CircleCI owns e2e.
-
-## Phase 4: Netlify deploys
-
-- [ ] **Task 4.1**: Port demo / frontend-example / docs Netlify workflows
-  - Description: Build + `netlify-cli` deploy prod/preview; preserve alias naming (`pr-N`); recreate GitHub Deployment statuses via API if still desired.
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 0.2, Task 1.3
-  - Acceptance: preview deploy URL posted or visible; prod deploy on master path filter.
-
-- [ ] **Task 4.2**: Preview cleanup port
-  - Description: On PR close, clean Netlify/GCP preview resources from CircleCI (webhook or GitHub App → pipeline). Prefer OIDC over `GCP_SA_KEY`.
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 4.1
-  - Acceptance: closing a PR removes preview resources; no orphaned Cloud Run `pr-N` services in a test PR.
-
-- [ ] **Task 4.3**: Dual-run cutover for Netlify
-  - Description: Delete GHA deploy workflows after CircleCI trusted.
-  - Files: `.github/workflows/demo-deploy.yml`, `frontend-example-deploy.yml`, `docs-deploy.yml`, `preview-cleanup.yml`
-  - Depends on: Task 4.1, Task 4.2
-  - Acceptance: GHA deploy twins deleted.
-
-## Phase 5: EAS + fingerprint
-
-- [ ] **Task 5.1**: Relocate CI scripts
-  - Description: Move EAS/fingerprint shell scripts from `.github/workflows/scripts/` to `scripts/ci/` (or `.circleci/scripts/`) and update callers.
-  - Files: `scripts/ci/*`, old script paths
-  - Depends on: none
-  - Acceptance: scripts runnable locally with documented env; no broken references.
-
-- [ ] **Task 5.2**: Port eas-pr, eas-dev-build, fingerprint-gate
-  - Description: CircleCI jobs using `EXPO_TOKEN`; PR comments and label gate via GitHub API; manual pipeline for eas-dev-build.
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 5.1, Task 0.2
-  - Acceptance: fingerprint change fails until `fingerprint-acknowledged`; EAS update/build path works on a test PR.
-
-- [ ] **Task 5.3**: Dual-run cutover for EAS
-  - Description: Delete GHA eas/fingerprint workflows after trust.
-  - Files: `.github/workflows/eas-pr.yml`, `eas-dev-build.yml`, `fingerprint-gate.yml`
-  - Depends on: Task 5.2
-  - Acceptance: GHA twins deleted; CircleCI checks required where fingerprint was required.
-
-## Phase 6: GCP CD + OIDC
-
-- [ ] **Task 6.1**: Add CircleCI OIDC provider in terraform
-  - Description: Extend or add module so GCP trusts CircleCI OIDC alongside GitHub during dual-run. Wire terreno terraform root; document outputs for CircleCI project settings.
-  - Files: `terraform/modules/**`, terreno/Flourish terraform roots, `terraform/README.md`
-  - Depends on: Task 0.1
-  - Acceptance: `gcloud` auth from a CircleCI job succeeds with WIF (no JSON key).
-
-- [ ] **Task 6.2**: Port `cd.yml`
-  - Description: Path-filtered terraform fmt/preview/apply + Docker build/push + Cloud Run deploys + mcp-test/deploy. Preserve concurrency semantics (do not cancel in-flight prod applies).
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 6.1
-  - Acceptance: terraform preview on PR; apply+deploy on master for a safe test path; GitHub Deployment records optional but documented.
-
-- [ ] **Task 6.3**: Dual-run cutover for CD
-  - Description: Single deployer: disable GHA `cd.yml` when CircleCI CD is required; remove GitHub OIDC provider only after GHA CD is gone (or keep read-only if other repos need it — document).
-  - Files: `.github/workflows/cd.yml`, terraform OIDC
-  - Depends on: Task 6.2
-  - Acceptance: only CircleCI performs terreno CD; no double apply.
-
-## Phase 7: npm publish
-
-- [ ] **Task 7.1**: Port publish-on-tag + manual feature-flags publish
-  - Description: Reproduce package publish graph, upgrade-docs gate, version bump, Zoom notify, demo dispatch, docs version cut. Use `terreno-release` + `terreno-npm` contexts.
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 0.2, Task 2.1
-  - Acceptance: dry-run or package-by-package rehearsal documented; Zoom path tested against a sandbox webhook if available.
-
-- [ ] **Task 7.2**: Single-writer tag cutover
-  - Description: In one coordinated change: enable CircleCI tag pipeline; delete/disable `.github/workflows/publish-on-tag.yml` and manual GHA publish; verify no double publish.
-  - Files: `.github/workflows/publish-on-tag.yml`, `publish-feature-flags-manual.yml`
-  - Depends on: Task 7.1
-  - Acceptance: next tag publishes once from CircleCI only.
-
-## Phase 8: Mobile (post-v1, required for CC1)
-
-- [ ] **Task 8.1**: Port Maestro + Appium Android
-  - Description: Port `maestro-e2e` and Android half of `demo-appium-ci` to CircleCI Linux VM with emulator strategy documented.
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 5.2
-  - Acceptance: manual pipeline runs Android Appium and Maestro successfully.
-
-- [ ] **Task 8.2**: Port Appium iOS on CircleCI macOS
-  - Description: Select macOS resource class/image with Working WDA; port iOS job; compare flake rate to GHA `macos-15`.
-  - Files: `.circleci/continue-config.yml`
-  - Depends on: Task 8.1
-  - Acceptance: iOS Appium green on a representative run; then delete GHA Appium workflow.
-
-## Phase 9: GitHub-native + agentic replacements
-
-- [ ] **Task 9.1**: Replace CodeQL workflow
-  - Description: Implement SARIF upload to GitHub Code Scanning from CircleCI or an approved SAST substitute; delete `codeql-analysis.yml` only when coverage is accepted.
-  - Files: `.circleci/continue-config.yml`, `.github/workflows/codeql-analysis.yml`
-  - Depends on: Task 0.2
-  - Acceptance: Security tab still receives results **or** explicit maintainer sign-off on alternative.
-
-- [ ] **Task 9.2**: Replace Dependabot auto-merge + triage + roadmap-generate + docs-audit
-  - Description: Implement CircleCI (or Renovate) equivalents; wire issue/schedule triggers without leaving required logic on GHA.
-  - Files: `.circleci/continue-config.yml`, corresponding GHA deletions
-  - Depends on: Task 0.2
-  - Acceptance: each former workflow’s acceptance behavior has an owner on CircleCI; GHA files deleted.
-
-- [ ] **Task 9.3**: Replace architectural review + gh-aw agentics
-  - Description: Per lockfile (`update-rules`, `update-docs`, daily improvers) and `architectural-pr-review` / `agentics-maintenance`: either port to CircleCI scheduled/PR pipelines with the same scripts or **retire** with maintainer sign-off. CC1 forbids leaving them on GHA.
-  - Files: `.github/workflows/*lock*`, `architectural-pr-review.yml`, `agentics-maintenance.yml`, `.circleci/continue-config.yml`
-  - Depends on: Task 0.2
-  - Acceptance: written retire-or-port decision for each; no gh-aw workflows remain if ported/retired.
-
-## Phase 10: Cleanup
-
-- [ ] **Task 10.1**: Docs sweep
-  - Description: Update CONTRIBUTING, repository-settings, terraform README, deploy guides, AGENTS/Cursor Cloud CI notes to CircleCI-first. Remove stale GHA instructions.
-  - Files: `docs/**`, `CONTRIBUTING.md`, `AGENTS.md` / rules as needed
-  - Depends on: Phases 2–7 at minimum; 8–9 for full CC1
-  - Acceptance: `rg -n "GitHub Actions" docs/explanation/repository-settings.md` and deploy docs reflect CircleCI as source of truth.
-
-- [ ] **Task 10.2**: Final GHA workflow purge + IP close
-  - Description: Ensure `.github/workflows` has no CI/CD yml left (except intentionally empty dir or README). Set the IP `**Status:**` to Complete and archive the IP.
-  - Files: `.github/workflows/`, `docs/implementationPlans/migrate-cicd-to-circleci.md`
-  - Depends on: Task 9.3, Task 10.1, Task 8.2
-  - Acceptance: `ls .github/workflows/*.yml` is empty (or only an agreed stub); IP status Complete.

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

@@ -1,70 +0,0 @@
-# Tasks: Organizations, teams, and multi-tenant scoping
-
-IP: [orgs-and-teams](../implementationPlans/orgs-and-teams.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

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

@@ -1,60 +0,0 @@
-# Tasks: Password reset and email verification
-
-IP: [password-reset-and-email-verification](../implementationPlans/password-reset-and-email-verification.md)
-
-## Phase 1 — Token infrastructure
-
-- [ ] **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
-- [ ] **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
-
-- [ ] **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
-- [ ] **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
-- [ ] **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
-
-- [ ] **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
-
-- [ ] **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
-- [ ] **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
-- [ ] **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.1.0/tasks/positioning-django-rails-universal.md

@@ -1,100 +0,0 @@
-# Task List: Positioning — "Django/Rails for TypeScript, with Universal Apps"
-
-See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../implementationPlans/positioning-django-rails-universal.md)
-
-**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` touch the architecture diagram, package list, or integration flow and must run after PR #869 merges and after [`rtk-to-syncdb-migration-docs`](rtk-to-syncdb-migration-docs.md) Phase 6. Unmarked tasks are safe earlier.
-
-## Instructions for the implementing agent
-
-- Write the copy blocks **once** in `docs/explanation/positioning.md` (Task 1.1), then copy them verbatim everywhere else. Do not paraphrase per surface — drift is the problem this IP exists to fix.
-- Do not claim any feature listed under "Where Terreno is headed" as shipped. If you are unsure whether something ships today, grep for it in the package source before writing about it.
-- When moving content out of the README, use `git mv`-style discipline: cut from one file, paste into the other in the same commit, and grep for inbound links.
-- Run `bun run website:build` and `bun run rules:check` before each commit that touches `website/` or `.rulesync/`.
-
-## Phase 1: Canonical copy
-
-- [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
-
-- [ ] **Task 2.1**: Restructure the README's opening
-  - Description: Rewrite `README.md` above the packages list to this order: title with badges (preserve existing npm badges and the license badge from the governance IP), the `tagline` block as the subtitle, the `elevator` block, the three `pillars`, then a "Quickstart" section, then "Packages". Preserve the existing Vision and Philosophy content but fold it into the pillars rather than repeating it. Per IP question PO5, replace the "Where Terreno is headed" list with a two-line summary linking `ROADMAP.md`.
-  - Files: `README.md`
-  - Depends on: Task 1.1
-  - Acceptance: "Django/Rails for TypeScript" appears within the first two sentences; the pillars appear in the IP's order; the roadmap section is two lines plus a link; no feature claimed that is not shipped.
-
-- [ ] **Task 2.2**: Move maintainer content out of the README
-  - Description: Move these README sections to their correct homes: local development / bootstrap / linking instructions → `CONTRIBUTING.md`; the "Feature flags: OpenFeature migration" walkthrough → a new or existing page under `docs/how-to/` (check `docs/how-to/add-feature-flags.md` first — it may already cover this, in which case delete the README copy and link it); GCP project names, Cloud Run URLs, and Netlify hosts → `infra/flourish/README.md` (created by [`deploy-to-gcp`](../implementationPlans/deploy-to-gcp.md)) or a short "Live examples" list with URLs only and no infra detail; release instructions → `CONTRIBUTING.md`. After moving, grep the repo and `website/` for links to the removed anchors and fix them.
-  - Files: `README.md`, `CONTRIBUTING.md`, `docs/how-to/add-feature-flags.md`, `infra/flourish/README.md`
-  - Depends on: Task 2.1
-  - Acceptance: `rg -i "flourish-terreno|a\.run\.app|Slack" README.md` returns nothing; no content was deleted without a new home; `bun run website:build` reports no new broken links.
-
-- [ ] **Task 2.3**: `[RTK]` Update the README architecture and package list
-  - Description: Confirm the architecture diagram and published-package list reflect syncdb (this may already be done by `rtk-to-syncdb-migration-docs` Task 6.5 — check first and skip if so). Ensure every package in `publish-on-tag.yml` appears in the list exactly once with a one-line description matching its `package.json` description.
-  - Files: `README.md`
-  - Depends on: Task 2.2, `rtk-to-syncdb-migration-docs` Task 6.5
-  - Acceptance: package list matches `publish-on-tag.yml` one-to-one; each description matches the package's `package.json`; diagram names syncdb not rtk.
-
-## Phase 3: Docs site
-
-- [ ] **Task 3.1**: `[RTK]` Rewrite `docs/README.md`
-  - Description: Replace the opening line ("shared packages for full-stack applications with React Native and Express/Mongoose") with the `tagline` + `elevator` + `pillars` blocks. Keep the Diátaxis structure section. Rebuild the package table so it contains every published package including `@terreno/ai`, `@terreno/syncdb`, `@terreno/admin-spa`, and `@terreno/feature-flags`, with `rtk` under a Legacy heading. Update the Quick links section: remove the `.cursorrules` link if that file no longer exists, add `positioning.md`, `ROADMAP.md`, and `CONTRIBUTING.md`.
-  - Files: `docs/README.md`
-  - Depends on: Task 1.1, `rtk-to-syncdb-migration-docs` Task 2.3
-  - Acceptance: tagline appears in the first two sentences; package table complete and matching `publish-on-tag.yml`; every Quick link resolves to an existing file.
-
-- [ ] **Task 3.2**: Update the docs site configuration
-  - Description: In `website/docusaurus.config.ts`, set `tagline` to the canonical tagline and confirm `title`, `themeConfig.metadata` (og description), and navbar title read consistently. Check whether `website/src/pages/index.tsx` exists; if it does, update the hero to use the tagline, the three pillars, and one short code sample (a `modelRouter` registration plus the matching generated hook usage). If there is no custom landing page, note that in the PR body and skip the hero work.
-  - Files: `website/docusaurus.config.ts`, `website/src/pages/index.tsx` (if present)
-  - Depends on: Task 1.1
-  - Acceptance: `bun run website:build` succeeds; the built HTML contains the canonical tagline in the meta description; the hero (if present) shows the three pillars.
-
-## Phase 4: Agent surfaces
-
-- [ ] **Task 4.1**: `[RTK]` Update root agent context files
-  - Description: In `.rulesync/rules/00-root.md` (the source for `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/00-root.mdc`, and the copilot instructions), replace the opening "A monorepo containing shared packages…" with the `tagline` + `elevator` + `pillars`. Keep all existing conventions content unchanged. Apply the same opening to `CLAUDE-consumer.md`. Then run `bun run rules` and commit every generated mirror. Note: `CLAUDE.local.md` appears to be a stale duplicate of `CLAUDE.md` — verify and either update or delete it, reporting which you chose and why.
-  - Files: `.rulesync/rules/00-root.md`, `CLAUDE-consumer.md`, possibly `CLAUDE.local.md`, generated mirrors
-  - Depends on: Task 1.1
-  - Acceptance: `bun run rules:check` exits 0; `AGENTS.md` and `CLAUDE.md` both open with the positioning; no conventions content was lost (diff review); the `CLAUDE.local.md` decision is explained in the PR body.
-
-- [ ] **Task 4.2**: Update the MCP overview resource
-  - Description: Update `mcp-server/src/docs/resources/overview.md` to open with the positioning blocks so agents reading `terreno://docs/overview` describe Terreno consistently. Check the other resource bundles (`api`, `ui`, `rtk`/`syncdb`, `patterns`) for stale positioning language in their intros and fix those too.
-  - Files: `mcp-server/src/docs/resources/*.md`
-  - Depends on: Task 4.1
-  - Acceptance: `bun run mcp:build` succeeds; the overview resource opens with the tagline; no resource intro describes Terreno as "a monorepo of shared packages".
-
-## Phase 5: Metadata
-
-- [ ] **Task 5.1**: Standardize `package.json` descriptions
-  - Description: For every package published by `publish-on-tag.yml`, set `description` to the pattern `<what it does> — part of Terreno, the batteries-included TypeScript framework for universal apps.` Keep the first clause specific and accurate per package (do not make them all identical). Also confirm `keywords`, `repository`, `homepage`, and `bugs` fields are present and correct on every published package — missing `repository` fields hurt npm discoverability.
-  - Files: every published `package.json`
-  - Depends on: Task 1.1
-  - Acceptance: every published package has a `description` matching the pattern, plus `repository`, `homepage`, and `bugs` fields; `bun install` still resolves cleanly.
-
-- [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.
-
-- [ ] **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.