@terreno/mcp 56.0.0-beta.0 → 57.0.0-beta.1

package/dist/docs/versioned/next/tasks/deployment-foundation.md

@@ -13,19 +13,19 @@ See: [`docs/implementationPlans/deployment-foundation.md`](../implementationPlan
 
 ## Phase 1: Environment variable reference
 
-- [ ] **Task 1.1**: Audit every environment variable in the repo
+- [x] **Task 1.1**: Audit every environment variable in the repo
   - Description: Run `rg -n "process\.env\.[A-Z_]+" --glob '!node_modules' --glob '!*.test.ts'` and `rg -n "EXPO_PUBLIC_[A-Z_]+"` across the repo. Build a complete list of distinct variables with the file and package where each is read. Also check `Constants.expoConfig?.extra` reads in `rtk/src/constants.ts` (and the syncdb equivalent post-#869) since those are configured through `app.json` rather than the environment. Save the raw findings in the PR body.
   - Files: none (findings in the PR body)
   - Depends on: none
   - Acceptance: the list is generated from grep output, not hand-written; every entry names the reading file; `extra`-based config is listed separately from `process.env` reads.
 
-- [ ] **Task 1.2**: Complete `docs/reference/environment-variables.md`
+- [x] **Task 1.2**: Complete `docs/reference/environment-variables.md`
   - Description: Restructure the page into tables grouped by concern (Database, Auth — JWT, Auth — Better Auth, AI, Storage, Feature flags, Observability, MCP, Client/build-time). Each row: variable, read by (package), required or optional, default, secret (yes/no), and scope (server runtime / client build-time). Add an explicit callout explaining that `EXPO_PUBLIC_*` variables are inlined into the JavaScript bundle at build time — they are not secrets and cannot be changed without rebuilding. Every variable from Task 1.1 must appear exactly once.
   - Files: `docs/reference/environment-variables.md`
   - Depends on: Task 1.1
   - Acceptance: every variable from the Task 1.1 audit appears; no variable is listed that does not appear in the audit; the build-time callout is present; secrets are marked.
 
-- [ ] **Task 1.3**: `[RTK]` Update the `.env.example` files
+- [x] **Task 1.3**: `[RTK]` Update the `.env.example` files
   - Description: Update `example-backend/.env.example` and `example-frontend/.env.example` so each contains every required variable for that app with safe placeholder values and a one-line comment per variable. Verify no real secret values are present. Add the Better Auth variables to the backend example, commented out, with a note pointing at `docs/how-to/configure-better-auth.md`.
   - Files: `example-backend/.env.example`, `example-frontend/.env.example`
   - Depends on: Task 1.2
@@ -33,19 +33,19 @@ See: [`docs/implementationPlans/deployment-foundation.md`](../implementationPlan
 
 ## Phase 2: Deployment baseline
 
-- [ ] **Task 2.1**: Write `docs/explanation/deployment-baseline.md`
+- [x] **Task 2.1**: Write `docs/explanation/deployment-baseline.md`
   - Description: Explainer covering the seven baseline requirements from the IP. For each: what it is, why Terreno needs it, and the symptom when it is missing. Requirements 1, 3, and 5 need reproduced symptoms: (1) run the backend against a standalone `mongod` and quote the actual startup or change-stream error; (3) describe what happens to Socket.io on a platform with a short request timeout — cite the reconnect behavior in the client socket code; (5) build the web bundle with `EXPO_PUBLIC_API_URL` unset, then serve it and quote the resulting client-side failure. Requirement 6 must state that `@terreno/api-health` is part of the baseline (IP question DF4).
   - Files: `docs/explanation/deployment-baseline.md` (new)
   - Depends on: Task 1.2
   - Acceptance: all seven requirements documented; symptoms for 1, 3, and 5 are reproduced and quoted verbatim, not paraphrased.
 
-- [ ] **Task 2.2**: Add the web output-mode decision table
+- [x] **Task 2.2**: Add the web output-mode decision table
   - Description: Add a section to `docs/explanation/deployment-baseline.md` with the three-mode table from the IP (`single`, `static`, `server`) covering output shape, API-route support, SSR support, hosting requirements, and current Terreno status. State explicitly: `single` is today's default, `static` is available now and improves SEO, and `server` requires Expo SDK ≥ 55 while the repo catalog is on `~54.0.29` — link PR #779 and [`web-ssr-and-admin-spa`](../implementationPlans/web-ssr-and-admin-spa.md). Verify the current Expo version from the root `package.json` catalog rather than trusting this description.
   - Files: `docs/explanation/deployment-baseline.md`
   - Depends on: Task 2.1
   - Acceptance: table has all three modes with all five columns; the stated Expo version matches the root catalog; no text implies SSR is currently available.
 
-- [ ] **Task 2.3**: `[RTK]` Add the multi-environment section
+- [x] **Task 2.3**: `[RTK]` Add the multi-environment section
   - Description: Add a section listing exactly what differs between a staging and a production deployment: secret values, `MONGO_URI` (separate cluster or database), `EXPO_PUBLIC_API_URL` (requires a separate web build per environment — call this out, it is the non-obvious one), `corsOrigin`, Better Auth `trustedOrigins` and `BETTER_AUTH_URL`, and feature-flag defaults. Keep it under 40 lines; this is a checklist, not a guide.
   - Files: `docs/explanation/deployment-baseline.md`
   - Depends on: Task 2.2
@@ -53,25 +53,25 @@ See: [`docs/implementationPlans/deployment-foundation.md`](../implementationPlan
 
 ## Phase 3: Backend container
 
-- [ ] **Task 3.1**: Verify and fix the backend's port and host binding
+- [x] **Task 3.1**: Verify and fix the backend's port and host binding
   - Description: Read `example-backend/src/server.ts` and `api/src/expressServer.ts` to determine how the listen port and host are resolved. Confirm the port comes from `process.env.PORT` with a fallback and that the server binds `0.0.0.0` (or Express's default, which is all interfaces — verify rather than assume). If either is wrong for containerized deployment, fix it in the smallest possible change and add a test. If both are already correct, make no code change and record that finding.
   - Files: `example-backend/src/server.ts` and/or `api/src/expressServer.ts` (only if a fix is needed), plus a test
   - Depends on: none
   - Acceptance: running `PORT=9999 bun run backend:dev` serves on 9999; the finding (fixed or already correct) is stated in the PR body with file citations.
 
-- [ ] **Task 3.2**: Write the backend Dockerfile
+- [x] **Task 3.2**: Write the backend Dockerfile
   - Description: Create `example-backend/Dockerfile` as a multi-stage build on `oven/bun:1-slim` (IP question DF2). Stage 1: copy the lockfile and workspace manifests, run `bun install --frozen-lockfile`, then compile the workspace packages the backend depends on (`@terreno/test`, `@terreno/api`, then the rest — mirror the ordering in the root `compile` script). Stage 2: copy only the built output and production dependencies, create and switch to a non-root user, set `ENV NODE_ENV=production`, expose the port, and set the entrypoint. Add a `HEALTHCHECK` hitting the health endpoint. Create `example-backend/.dockerignore` excluding `node_modules`, `.git`, `.env*`, test files, and build caches.
   - Files: `example-backend/Dockerfile` (new), `example-backend/.dockerignore` (new)
   - Depends on: Task 3.1
   - Acceptance: `docker build -f example-backend/Dockerfile .` succeeds from the repo root; the image runs and `curl localhost:$PORT/health` returns `"healthy":true` against an external MongoDB replica set; `docker run` with `--user` unset shows a non-root user via `id`; the final image is under 500 MB.
 
-- [ ] **Task 3.3**: Add a Docker build CI job
+- [x] **Task 3.3**: Add a Docker build CI job
   - Description: Create `.github/workflows/example-backend-docker.yml` that builds the image on pull requests touching `example-backend/**`, `api/**`, `package.json`, or `bun.lock`. Build only — do not push. Use layer caching. Follow the repo's convention of validating required inputs before use even though this job needs no secrets.
   - Files: `.github/workflows/example-backend-docker.yml` (new)
   - Depends on: Task 3.2
   - Acceptance: the workflow parses as valid YAML; the path filter covers all four inputs; the job does not push an image or require registry credentials.
 
-- [ ] **Task 3.4**: Reference the Dockerfile from the docs
+- [x] **Task 3.4**: Reference the Dockerfile from the docs
   - Description: Add a "Containerizing the backend" section to `docs/explanation/deployment-baseline.md` that explains the Dockerfile's structure and links `example-backend/Dockerfile` as the canonical copy rather than duplicating its contents (per IP question DF1). Call out the three details consumers get wrong: reading `PORT` from the environment, running as non-root, and compiling workspace packages in the right order.
   - Files: `docs/explanation/deployment-baseline.md`
   - Depends on: Task 3.2
@@ -79,13 +79,13 @@ See: [`docs/implementationPlans/deployment-foundation.md`](../implementationPlan
 
 ## Phase 4: Web build documentation
 
-- [ ] **Task 4.1**: `[RTK]` Write `docs/how-to/build-for-web.md`
+- [x] **Task 4.1**: `[RTK]` Write `docs/how-to/build-for-web.md`
   - Description: How-to covering: the build command (verify the exact script in `example-frontend/package.json` — do not assume `expo export -p web`), what the output directory contains for the current output mode, setting `EXPO_PUBLIC_API_URL` before the build with an explicit warning that it is inlined into the bundle, the `app.json` `extra` alternative (`BASE_URL`) and how the two interact — check the base-URL resolution priority order in the client package and document it accurately, serving the output locally to verify before deploying, and the SPA-routing requirement (all unknown paths must serve `index.html`) with a note that each host configures this differently. Link the provider guides.
   - Files: `docs/how-to/build-for-web.md` (new), `docs/how-to/README.md`
   - Depends on: Task 2.2
   - Acceptance: the build command matches an actual script; the base-URL priority order matches the client source and cites the file; the local-verification step works; the guide is listed in the how-to index.
 
-- [ ] **Task 4.2**: Cross-link the deployment documentation
+- [x] **Task 4.2**: Cross-link the deployment documentation
   - Description: Add a "Deployment" grouping to `docs/how-to/README.md` and `docs/explanation/README.md` listing the baseline explainer, the web build guide, and the provider guides from [`deploy-to-vercel`](../implementationPlans/deploy-to-vercel.md) and [`deploy-to-gcp`](../implementationPlans/deploy-to-gcp.md). Ensure each provider guide links back to the baseline instead of restating the seven requirements.
   - Files: `docs/how-to/README.md`, `docs/explanation/README.md`
   - Depends on: Task 4.1

package/dist/docs/versioned/next/tasks/docs-reference-coverage.md

@@ -14,19 +14,19 @@ See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPl
 
 ## Phase 1: Missing reference pages
 
-- [ ] **Task 1.1**: Write `docs/reference/ai.md`
+- [x] **Task 1.1**: Write `docs/reference/ai.md`
   - Description: Convert `.cursor/rules/ai/00-ai.mdc` into a public reference page. Sections, following `docs/reference/api.md`'s shape: Install; Commands; Architecture (file structure); `AIService` setup and full method table; structured-output helpers (`generateJsonValue`, `generateJsonObject`, `generateJsonArray`) including the JSON-normalization behavior and error logging; temperature presets; the `AIRequest` and `GptHistory` models with field tables; route registrars (`addGptRoutes`, `addGptHistoryRoutes`, `addAiRequestsExplorerRoutes`) with endpoints, methods, and permissions; Langfuse integration; integration example with `setupServer`/`TerrenoApp`; environment variables; conventions; testing (including the mock-model pattern). Verify every symbol against `ai/src/index.ts`. Remove the internal-only conventions that make no sense to a consumer (for example instructions about not mocking `@terreno/api` belong in agent rules, not reference docs — use judgment).
   - Files: `docs/reference/ai.md` (new)
   - Depends on: none
   - Acceptance: every documented symbol appears in `ai/src/index.ts`; the method table lists all `AIService` methods; all three route registrars documented with their permissions; no `.claude/` or `.cursor/` path referenced.
 
-- [ ] **Task 1.2**: Write `docs/reference/admin-spa.md`
+- [x] **Task 1.2**: Write `docs/reference/admin-spa.md`
   - Description: New reference page for `@terreno/admin-spa`, sourced from `admin-spa/README.md` and `admin-spa/src/`. Cover: what the package is (standalone Expo Router web admin SPA plus an Express plugin that serves it), install, the `AdminSpaServeApp` plugin registration with its options, building the SPA, configuring `apiBase`/`routeBase`, how it relates to the embedded `@terreno/admin-frontend` approach and when to choose each, and environment variables. Verify the plugin options against the source and against how `example-backend/src/server.ts` registers it.
   - Files: `docs/reference/admin-spa.md` (new)
   - Depends on: none
   - Acceptance: every option documented exists in the source; includes a "standalone SPA vs embedded screens" decision paragraph; the registration example matches `example-backend/src/server.ts`.
 
-- [ ] **Task 1.3**: Write `docs/reference/test.md`
+- [x] **Task 1.3**: Write `docs/reference/test.md`
   - Description: New reference page for `@terreno/test`. Cover: what it provides (in-memory MongoDB management for bun test suites), install as a dev dependency, the `bunfig.toml` preload pattern, `setupEnvironment()`, the `TERRENO_TEST_USE_MEMORY_MONGO` / `TERRENO_TEST_MONGODB_URI` / `BUN_TEST_DISABLE_DB` environment variables, and the test-helper exports. Source the preload contract from `admin-backend/AGENTS.md`, `api/src/tests/bunSetup.ts`, and the `backend-test-env` skill. Keep it short — one page.
   - Files: `docs/reference/test.md` (new)
   - Depends on: none
@@ -40,7 +40,7 @@ See: [`docs/implementationPlans/docs-reference-coverage.md`](../implementationPl
 
 ## Phase 2: Package READMEs
 
-- [ ] **Task 2.1**: Define and apply the README template to the four stubs
+- [x] **Task 2.1**: Define and apply the README template to the four stubs
   - Description: Write the six-section template from the IP (Title/description, Install, Quick start, What's included, Documentation, License/Contributing) and apply it to the four stub READMEs: `ai/README.md` (source: the new `docs/reference/ai.md`), `admin-backend/README.md` (source: `.cursor/rules/admin-backend/00-admin-backend.mdc` + `docs/reference/admin-backend.md`), `admin-frontend/README.md` (same pattern), `api-health/README.md` (source: `api-health/src/`). Each Quick start must be a complete, runnable snippet — not a fragment. Every link absolute.
   - Files: `ai/README.md`, `admin-backend/README.md`, `admin-frontend/README.md`, `api-health/README.md`
   - Depends on: Task 1.1

package/dist/docs/versioned/next/tasks/infra-mcp.md

@@ -0,0 +1,43 @@
+# Tasks: Infrastructure MCP server (`@terreno/infra-mcp`)
+
+Plan: [docs/implementationPlans/infra-mcp.md](../implementationPlans/infra-mcp.md)
+Status: Blocked — Phase 1 RBAC wiring depends on the RBAC module PR ([rbac-permissions.md](../implementationPlans/rbac-permissions.md)). Scaffold/adapter tasks marked (unblocked) can start now.
+
+## Phase 1 — Read-only core
+
+- [ ] (unblocked) Scaffold `infra-mcp/` workspace package: package.json (catalog deps), tsconfig, biome, bun test setup, root workspace + catalog entries (zod 4, `@modelcontextprotocol/server`, `@better-auth/oauth-provider`, `@better-auth/mcp`)
+- [ ] (unblocked) `src/config.ts`: `defineInfraMcp` config schema (zod), secret resolution (env/Secret Manager), boot validation
+- [ ] (unblocked) `src/server.ts`: Express/TerrenoApp server with SDK v2 `/mcp` endpoint (`createMcpHandler`, `legacy: "stateless"`, `toNodeHandler`) + `/health`
+- [ ] (unblocked) `src/auth.ts`: Better Auth OAuth 2.1 setup — authorization server, RFC 9728 protected-resource metadata, bearer verification middleware; login page flow verified with Cursor and Claude Code
+- [ ] `src/access.ts`: `infraStatements`, default roles (`infra-readonly`, `infra-operator`), `createAccess` wiring, `Mcp-Name`-keyed authz middleware, per-user filtered `tools/list` (**blocked on RBAC PR**)
+- [ ] `src/models/infraAuditLog.ts` + audit middleware around `tools/call` (statuses: allowed/denied/confirmed/rejected/error; per-tool arg redaction)
+- [ ] (unblocked) Integration adapter types + registry (`src/integrations/types.ts`, `registry.ts`)
+- [ ] (unblocked) GCP native adapter (ADC): `gcp_query_logs`, `gcp_list_log_names`, `gcp_query_metrics`, `gcp_list_error_groups`, `gcp_list_cloud_run_services`, `gcp_get_cloud_run_service`
+- [ ] (unblocked) Sentry native adapter (REST + static token): `sentry_search_issues`, `sentry_get_issue`, `sentry_list_issue_events`, `sentry_get_event`
+- [ ] (unblocked) Mongo native adapter (read URI): `mongo_list_collections`, `mongo_collection_schema`, `mongo_find`, `mongo_aggregate` (reject `$out`/`$merge`). Extract the shared read-query/schema logic from `mcp-server/src/local/tools/databaseQuery.ts` + `databaseSchema.ts` into a reusable module both packages import — do not fork copies into infra-mcp (per architectural review)
+- [ ] Admin panel registration (`@terreno/admin-backend`): Users, InfraAuditLog (read-only)
+- [ ] Terraform: `infra_mcp_service` Cloud Run module instance, Artifact Registry, runtime SA with viewer/logging IAM only
+- [ ] Tests: authz matrix (role × tool × tools/list filtering), adapter handlers, audit records, legacy-client fallback
+- [ ] Deploy + end-to-end verification from a real MCP client; docs: `.cursor/rules/infra-mcp/00-infra-mcp.mdc`, AGENTS.md/CLAUDE.md package lists
+- [ ] Roadmap: open the tracking issue from [roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md#infra-mcp) once the IP is Approved, add it to the Terreno Roadmap board, and register `@terreno/infra-mcp` → `area:mcp` in `scripts/issueAreaLabels.ts` + the bug-report package dropdown when the package lands
+
+## Phase 2 — Write tier + machine callers
+
+- [ ] `confirmWrite` elicitation wrapper; fail-closed behavior for clients without elicitation support
+- [ ] Config override (`confirmWrites: false`) gated by `infra:writeUnconfirmed`; tests for both paths
+- [ ] Write tools: `sentry_resolve_issue`, `sentry_assign_issue`, `gcp_rollback_cloud_run_revision`, `gcp_update_cloud_run_traffic`, `mongo_update_one`, `mongo_delete_one`; widen runtime SA IAM minimally
+- [ ] Service tokens: spike Better Auth `apiKey` plugin; fallback `ServiceToken` model; machine users (`isServiceAccount`) with role assignment; admin surface (token shown once)
+- [ ] Cloud agent migration: `INFRA_MCP_URL` + service token in agent environments; verify log-digging flows; remove `GCP_SA_*` injection; update AGENTS.md Cursor Cloud instructions
+
+## Phase 3 — Proxied adapters + remaining vendors
+
+- [ ] `ProxiedAdapter`: `@modelcontextprotocol/client` (stdio + HTTP), deny-by-default `allowedTools` with mandatory tier annotations, tool name prefixing, upstream lifecycle management
+- [ ] Reference proxied integration (`@sentry/mcp-server` stdio or `@google-cloud/observability-mcp`) with parity tests against native tools
+- [ ] Expo/EAS native adapter (`EXPO_TOKEN`): build status, update status, submission status (read); trigger tools deferred to write expansion
+- [ ] Vercel native adapter (API token): deployments, logs, project info (read)
+
+## Phase 4 — OSS packaging
+
+- [ ] `defineInfraMcp` config reference + quickstart docs (website); one-man-shop deploy path (container anywhere)
+- [ ] Publish `@terreno/infra-mcp`; changelog + upgrade notes
+- [ ] Dogfood writeup: our deployment as the reference architecture

package/dist/docs/versioned/next/tasks/migrate-cicd-to-circleci.md

@@ -0,0 +1,215 @@
+# 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 `FlourishHealth/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.
+
+- [ ] **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`.
+
+- [ ] **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
+
+- [ ] **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.
+
+- [ ] **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.
+
+- [ ] **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`.
+
+## Phase 2: Package CI + policy
+
+- [ ] **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.
+
+- [ ] **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.
+
+- [ ] **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.
+
+- [ ] **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
+
+- [ ] **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). Update `PLAN_INDEX.md`; archive IP when Complete.
+  - Files: `.github/workflows/`, `docs/implementationPlans/PLAN_INDEX.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/dist/docs/versioned/next/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/dist/docs/versioned/next/tasks/orgs-and-teams.md

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