@terreno/mcp 0.30.0 → 0.31.0

package/src/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/src/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/src/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/src/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/src/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

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

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

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

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

@@ -13,19 +13,19 @@ See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../imple
 
 ## Phase 1: Canonical copy
 
-- [ ] **Task 1.1**: Write `docs/explanation/positioning.md`
+- [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.
 
-- [ ] **Task 1.2**: Verify every claim in the comparison table
+- [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/`.
 
-- [ ] **Task 1.3**: Gate the pipeline claim on its portability work
+- [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
@@ -87,7 +87,7 @@ See: [`docs/implementationPlans/positioning-django-rails-universal.md`](../imple
   - Depends on: Task 1.1
   - Acceptance: every published package has a `description` matching the pattern, plus `repository`, `homepage`, and `bugs` fields; `bun install` still resolves cleanly.
 
-- [ ] **Task 5.2**: Document the GitHub repository metadata
+- [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