@terreno/mcp 56.0.0-beta.0 → 56.0.0-beta.2

package/src/docs/versioned/next/implementationPlans/migrate-cicd-to-circleci.md

@@ -0,0 +1,269 @@
+# Implementation Plan: Migrate CI/CD to CircleCI
+
+**Status:** Draft — decisions recorded; awaiting Approval  
+**Discussion:** _(none)_  
+**Roadmap issue:** _(pending — hand off via `roadmap-item` when Approved)_  
+**Linear:** _(none)_  
+**Priority:** High  
+**Effort:** Large (cross-cutting infra; many workflows)  
+**Owner:** unassigned (CircleCI org/plan: requester)  
+**Created:** 2026-08-17  
+**Branch:** `cursor/migrate-cicd-circleci-2b6d`  
+**Research:** [`migrate-cicd-to-circleci-research.md`](migrate-cicd-to-circleci-research.md)  
+**Depends on:** CircleCI org + paid plan created by requester; GCP project access for OIDC terraform  
+
+## Goal
+
+Move Terreno’s CI/CD from GitHub Actions to CircleCI end-to-end: every pipeline that builds, tests, deploys, publishes, or gates PRs runs on CircleCI. Use a dual-run cutover (GHA stays required until the matching CircleCI workflow is green, then delete the GHA workflow). End state: no `.github/workflows/*.yml` CI/CD jobs remain; GitHub keeps only what CircleCI cannot replace (if any residual is accepted, document it explicitly under Not Included).
+
+## Non-Goals
+
+- Changing what tests assert (only where they run), except for runner-parity fixes.
+- Migrating sibling repos (Flourish, Zapling, etc.).
+- Redesigning product deploy topology (Cloud Run / Netlify / EAS stay; only the orchestrator changes).
+- Shipping Appium **iOS** on CircleCI in **v1** (deferred to a late phase; Android Appium may move earlier if ubuntu parity is easy).
+- Rewriting gh-aw agentic *prompt* content; only re-home or replace the *runner*.
+
+## Decisions
+
+Recorded 2026-08-17 from Blend clarification.
+
+| # | Question | Decision |
+|---|----------|----------|
+| CC1 | Scope | **A — Full cutover.** All CI/CD moves to CircleCI; GHA workflows deleted after dual-run proves green. |
+| CC2 | Cutover style | **A — Dual-run.** Keep GHA required checks until the CircleCI twin is trusted, then remove GHA. |
+| CC3 | v1 must include | **GCP CD + terraform**, **npm publish-on-tag**, **Netlify** (demo / example-frontend / docs), **EAS PR + fingerprint gate**. Not Appium iOS in v1. |
+| CC4 | CircleCI account | Requester creates the CircleCI plan/org and links the GitHub repo. |
+| CC5 | Branch protection | Remapping required checks is in scope; maintainers apply GitHub settings when CircleCI check names are stable. |
+| CC6 | Config shape | **A — Dynamic config** (`setup: true`) + **path-filtering** orb. |
+
+## Architecture
+
+### Target topology
+
+```mermaid
+flowchart TB
+  subgraph gh [GitHub]
+    PUSH[push / PR / tag / schedule]
+    BP[branch protection required checks]
+  end
+
+  subgraph cci [CircleCI]
+    SETUP[setup workflow path-filtering]
+    CONT[continue config]
+    PKG[package CI + policy]
+    E2E[Playwright e2e]
+    NET[Netlify deploys]
+    EAS[EAS + fingerprint]
+    GCP[GCP CD via OIDC]
+    PUB[npm publish on tag]
+    MOB[Appium / Maestro late phase]
+    REP[replacements: CodeQL alt, bots, triage]
+  end
+
+  PUSH --> SETUP --> CONT
+  CONT --> PKG & E2E & NET & EAS & GCP & PUB & MOB & REP
+  PKG & E2E & EAS --> BP
+  GCP --> CR[Cloud Run / Artifact Registry / Infra Manager]
+  NET --> NL[Netlify sites]
+  PUB --> NPM[npmjs @terreno/*]
+  EAS --> EXPO[EAS Cloud]
+```
+
+### Config layout
+
+```
+.circleci/
+  config.yml              # setup: true — path-filtering only
+  continue-config.yml     # all real workflows/jobs
+  src/                    # optional: generated fragments if we split by package
+```
+
+- Use `circleci/path-filtering` to set boolean parameters (`run-api`, `run-ui`, `run-cd`, …) from changed paths (mirror today’s path filters).
+- Use `circleci/node` orb (≥7.2.0) for Bun install + cache (`pkg-manager: bun`).
+- Shared commands: `bun_install`, `start_mongo` (Docker service or `cimg` + mongo service), `compile_workspace_deps`.
+- Prefer a **private org orb** later for reuse; v1 may inline commands in `continue-config.yml` to ship faster, then extract.
+
+### Secrets: CircleCI Contexts
+
+| Context | Contents (from current GHA) |
+|---------|------------------------------|
+| `terreno-npm` | `NPM_TOKEN` |
+| `terreno-netlify` | `NETLIFY_AUTH_TOKEN`, site IDs |
+| `terreno-expo` | `EXPO_TOKEN` |
+| `terreno-gcp` | CircleCI OIDC (no long-lived key for CD); migrate `GCP_SA_KEY` off preview-cleanup onto OIDC |
+| `terreno-e2e` | `E2E_TOKEN_SECRET`, `E2E_REFRESH_TOKEN_SECRET`, `E2E_SESSION_SECRET` |
+| `terreno-release` | `REPO_ADMIN_TOKEN`, `ZOOM_WEBHOOK_URL`, `ZOOM_WEBHOOK_TOKEN` |
+| `terreno-agentic` | `CURSOR_API_KEY` (and replacements for Copilot/gh-aw tokens if re-homed) |
+| `terreno-github-api` | PAT with `pull-requests`, `deployments`, `contents` as needed for comments / Deployments API / roadmap |
+
+Restrict context access by project + environment (e.g. `release` context only on tag workflows).
+
+### GCP identity (blocking infra for Phase GCP)
+
+Today `terraform/modules/github_oidc` trusts **only** `https://token.actions.githubusercontent.com`. CircleCI CD requires:
+
+1. New Workload Identity pool provider for CircleCI’s OIDC issuer.
+2. Attribute condition on org/project/VCS origin.
+3. Bind `roles/iam.workloadIdentityUser` for deployer + terraform SAs.
+4. Dual-trust during dual-run (GitHub + CircleCI providers both valid), then remove GitHub provider when GHA CD is deleted.
+
+Prefer extending the module (`circleci_oidc` or rename to `ci_oidc` with multiple providers) over a one-off in Flourish terraform only — keep consumer docs honest.
+
+### GitHub ↔ CircleCI integration
+
+- CircleCI GitHub App (or OAuth) on `FlourishHealth/terreno`.
+- Status checks reported to GitHub for branch protection (job names documented in `docs/explanation/repository-settings.md`).
+- PR comments / labels / Deployments API: call GitHub REST via `gh` or `curl` with `terreno-github-api` context (replaces `GITHUB_TOKEN` action privileges).
+- Tag + schedule triggers: CircleCI pipeline triggers (or GitHub → CircleCI API webhook) for cron jobs currently on GHA.
+
+### Dual-run protocol (every phase)
+
+1. Land CircleCI twin; name check `cci/<old-job-name>` or stable CircleCI job name.
+2. Add CircleCI check as **non-required** optional signal; keep GHA required.
+3. Observe green on `master` + representative PRs.
+4. Flip branch protection: require CircleCI; unrequire GHA.
+5. Delete the GHA workflow file in the same PR window as the protection flip (or immediately after).
+6. Never leave tag publish listening on **both** systems.
+
+## Models / APIs / Notifications / UI
+
+None (infra-only). Zoom release notify stays a webhook call from the publish workflow.
+
+## Phases
+
+### Phase 0 — Prerequisites (human + docs)
+
+- Create CircleCI org/plan; link repo; enable dynamic config.
+- Create empty Contexts; document secret migration checklist.
+- Inventory required check names vs today’s GHA job `name:` fields.
+
+### Phase 1 — Foundation
+
+- Add `.circleci/config.yml` + `continue-config.yml` skeleton.
+- Path-filtering parameter map covering all packages + terraform + docs + demo.
+- Shared Bun + cache + Mongo patterns.
+- Smoke workflow on every push that only validates config.
+
+### Phase 2 — Package CI + repo policy (v1)
+
+Port and dual-run:
+
+- `api-ci`, `ai-ci`, `rtk-ci`, `ui-ci`, `ui-demo-ci`, `comms-ci`, `mcp-server-ci`
+- `example-frontend-ci`, `example-backend-ci`, `example-backend-script-runner`, `example-backend-docker`
+- `admin-spa-ci`
+- `repo-policies`, `rulesync-check`, `dco` (DCO via GitHub API + CircleCI)
+
+### Phase 3 — Playwright E2E (v1)
+
+- `e2e-ci`, `admin-spa-integration` (Mongo replica set + secrets context).
+
+### Phase 4 — Netlify deploys (v1)
+
+- `demo-deploy`, `frontend-example-deploy`, `docs-deploy`
+- Recreate preview aliases + optional GitHub Deployments via API.
+- `preview-cleanup` equivalent for Netlify/GCP previews as applicable.
+
+### Phase 5 — EAS + fingerprint (v1)
+
+- Port `eas-pr`, `eas-dev-build`, `fingerprint-gate` scripts under `.circleci/` or keep scripts in `.github/workflows/scripts/` and invoke from CircleCI until relocated to `scripts/ci/`.
+- PR comment + `fingerprint-acknowledged` label via GitHub API.
+
+### Phase 6 — GCP CD + OIDC (v1)
+
+- Terraform: CircleCI OIDC provider + dual-trust.
+- Port `cd.yml` (detect → terraform → backend/mcp deploy).
+- Port `preview-cleanup` onto OIDC (eliminate `GCP_SA_KEY`).
+- Dual-run CD carefully (concurrency: one deployer).
+
+### Phase 7 — npm publish (v1)
+
+- Port `publish-on-tag` + `publish-feature-flags-manual`.
+- **Single-writer rule:** disable GHA tag trigger in the same change that enables CircleCI tag pipeline.
+- Keep Zoom notify + master version bump + docs cut + demo dispatch.
+
+### Phase 8 — Mobile runners (post-v1 / still required for full cutover)
+
+- Maestro (`maestro-e2e`).
+- Appium Android on Linux VM.
+- Appium iOS on CircleCI macOS resource class (image pin parity with `macos-15` intent).
+- Then delete `demo-appium-ci.yml` / `maestro-e2e.yml`.
+
+### Phase 9 — GitHub-native + agentic replacements (full cutover)
+
+| Current GHA | Replacement approach |
+|-------------|----------------------|
+| `codeql-analysis` | CircleCI job uploading SARIF to GitHub Code Scanning API **or** third-party SAST orb; preserve Security tab if possible |
+| `dependabot-auto-merge` | Keep Dependabot PRs on GitHub; auto-merge via CircleCI on Dependabot branches **or** Renovate on CircleCI |
+| `triage.yml` | CircleCI pipeline trigger on `issues` via GitHub Apps webhook → CircleCI API, or GitHub Action **stub** only if product accepts residual GHA (conflicts with CC1 — prefer webhook) |
+| `roadmap-generate` | Scheduled CircleCI job with `ROADMAP_PROJECT_TOKEN` |
+| `architectural-pr-review` | CircleCI job + `CURSOR_API_KEY` (lose `pull_request_target` free fork safety — use least privilege + fork policy) |
+| `agentics-maintenance` + `*.lock.yml` gh-aw | Re-home to CircleCI scheduled pipelines calling the same scripts **or** retire features; do not leave gh-aw as the only runner if CC1 holds |
+| `docs-audit` | Scheduled CircleCI job |
+
+### Phase 10 — Cleanup + docs
+
+- Delete remaining `.github/workflows/*.yml` (and lock sources if retired).
+- Update `CONTRIBUTING.md`, `docs/explanation/repository-settings.md`, `terraform/README.md`, deploy how-tos, AGENTS.md Cloud CI notes.
+- Archive research; mark IP Complete.
+
+## Feature Flags & Migrations
+
+- No product feature flags.
+- Infra migration: dual OIDC trust window; dual CI check window; **no dual tag-publish**.
+- Secret migration checklist is the migration artifact (Contexts populated before jobs go required).
+
+## Activity Log & User Updates
+
+- Announce in Discord/Slack/Zoom when required checks flip and when tag publish moves.
+- Changelog: under Unreleased chore — “CI/CD runs on CircleCI”.
+
+## Not Included / Future Work
+
+- Private orb publication + versioning pipeline (nice follow-up after Phase 1–2 stabilize).
+- Moving Netlify sites to GCS+CDN (separate deploy architecture IPs).
+- Self-hosted CircleCI runners.
+- Credit-cost optimization beyond path-filtering (test splitting, resource-class tuning).
+
+## Risks & Mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Double npm publish | Single-writer cutover for tags; disable GHA first or in same commit |
+| GCP deploy from wrong IdP | Dual-trust then remove GitHub provider; dry-run terraform preview on CircleCI first |
+| Branch protection gaps during flip | Document exact check names; flip in a dedicated maintainer window |
+| macOS/Appium flake | Deferred to Phase 8; keep GHA Appium until CircleCI macOS proven |
+| gh-aw feature loss | Phase 9 explicit replace-or-retire decision per lockfile before deleting |
+| Credit burn during dual-run | Path filters; timebox dual-run per phase (target: days, not months) |
+| `mcp-server-ci` still filters `main` | Normalize to `master` while porting |
+
+## Files to Create / Modify
+
+**Create**
+
+- `.circleci/config.yml`
+- `.circleci/continue-config.yml`
+- `docs/how-to/circleci.md` (or `docs/explanation/ci-cd-circleci.md`)
+- `terraform/modules/circleci_oidc/` or extend `github_oidc` → multi-provider `ci_oidc`
+- `scripts/ci/` (relocated EAS/fingerprint helpers)
+
+**Modify**
+
+- `docs/explanation/repository-settings.md`
+- `terraform/README.md`, Flourish/terreno terraform roots that wire OIDC
+- `CONTRIBUTING.md`, root/CI docs references to GitHub Actions
+- Delete `.github/workflows/*` progressively per phase
+
+## Task List
+
+See [`docs/tasks/migrate-cicd-to-circleci.md`](../tasks/migrate-cicd-to-circleci.md).
+
+## Acceptance Criteria
+
+- [ ] All v1 workflows (package CI, policy, Playwright e2e, Netlify, EAS/fingerprint, GCP CD, npm publish) are green on CircleCI and required on `master` where applicable.
+- [ ] Matching GHA workflows for those surfaces are deleted; tag publish has exactly one listener.
+- [ ] CircleCI OIDC can deploy Cloud Run without `GCP_SA_KEY` for CD paths.
+- [ ] Path-filtering skips unrelated package jobs on a docs-only change.
+- [ ] `repository-settings.md` lists CircleCI check names; branch protection matches.
+- [ ] Phase 8–9 either complete (full cutover) or are tracked as blocking follow-ups before calling CC1 done.
+- [ ] CONTRIBUTING / terraform / deploy docs no longer instruct maintainers to use GHA for Terreno CI/CD.

package/src/docs/versioned/next/implementationPlans/native-module-baseline.md

@@ -0,0 +1,105 @@
+# Implementation Plan: Native module baseline for the next major release
+
+**Status:** Draft
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1026
+**Priority:** High
+**Effort:** Small batch (code) — coordination cost is the release itself
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** decisions D1/D3/D7 (resolved 2026-08-09)
+**RTK deprecation flag:** None
+
+## Goal
+
+Adding a native module to an Expo app invalidates every existing dev-client and store
+binary, so each addition after a release costs consumers a rebuild cycle. This IP lands
+**all** native dependencies the B2B program needs in one breaking (major) release, so every
+subsequent program feature — billing UI, MFA, dark mode, SSO, push, mobile IAP — ships as a
+JS/OTA update against the same binary.
+
+## Non-Goals
+
+- Implementing any feature that uses these modules (their own IPs).
+- Expo SDK version upgrades (separate effort; this IP targets the current SDK).
+- `@10play/tentap-editor` — excluded by decision D3 (markdown stays).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Manifest (D7, resolved) | `@stripe/stripe-react-native`, `react-native-purchases` + `react-native-purchases-ui`, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, `react-native-otp-verify` |
+| Where dependencies live | Root catalog entries; linked in `example-frontend` and `demo` app manifests; `@terreno/ui`/feature packages reference them only when their feature IPs land (this IP is binary readiness, not usage) |
+| Stripe Android constraints | Pin Kotlin 2.x / `compileSdkVersion` 36 via `expo-build-properties` per stripe-react-native requirements |
+| Expo Go story | Document which flows degrade in Expo Go (purchases → RevenueCat Preview API mode; stripe/local-auth → dev build required); CI smoke keeps web unaffected |
+| Release process | Follows the `release` skill + the upgrade-notes-for-breaking-releases CI gate (PR #987): major tag, upgrade note required |
+
+## Architecture
+
+Changes are dependency + config only:
+
+1. **Root `package.json` catalog:** add the seven packages (sorted), per the dependency
+   catalog rule (shared by `example-frontend` + `demo`).
+2. **`example-frontend/app.json` + `demo/app.json` plugins:**
+   `@stripe/stripe-react-native` (merchantIdentifier placeholder, `enableGooglePay:
+   true`), `react-native-purchases`, and `expo-build-properties` with the Kotlin/compileSdk
+   pins.
+3. **EAS builds:** refresh dev-client profiles via the existing `eas-dev-build` workflow;
+   verify Android + iOS builds compile with the new pods/gradle deps.
+4. **Upgrade note:** `docs` upgrade note describing the new binary requirement and the
+   consumer checklist (rebuild dev clients, add config plugins, set merchant id when using
+   Stripe).
+
+## Models / APIs / Notifications
+
+None.
+
+## UI
+
+None visible — binary-only change. `demo` gains a hidden diagnostics story listing
+resolved native module versions so builds are verifiable at runtime.
+
+## Phases
+
+1. **Dependencies + config:** catalog entries, app.json plugins, build-properties pins,
+   `bun install` + compile green, web export unaffected.
+2. **Builds + verification:** EAS dev builds for iOS/Android; diagnostics story confirms
+   modules resolve on device; Expo Go degradation documented.
+3. **Release:** upgrade note, coordinate the major tag via the release process.
+
+## Feature Flags & Migrations
+
+None. Runtime behavior is unchanged until feature IPs consume the modules.
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- TenTap (revisit in a later major if WYSIWYG is adopted — decision D3).
+- Any feature wiring of the added modules.
+
+## Files to Create / Modify
+
+- Root `package.json` (catalog), `example-frontend/package.json`, `demo/package.json`
+- `example-frontend/app.json`, `demo/app.json`
+- `demo` diagnostics story
+- `docs/` upgrade note for the major release
+- (No `@terreno/ui` source changes)
+
+## Task List
+
+See [docs/tasks/native-module-baseline.md](../tasks/native-module-baseline.md).
+
+## Acceptance Criteria
+
+- [ ] `bun install`, full compile, and `example-frontend` web export succeed with the
+      seven packages added.
+- [ ] iOS and Android EAS dev builds compile; the diagnostics story shows all seven
+      modules resolved on device.
+- [ ] Android build carries the Kotlin 2.x / compileSdk 36 pins without breaking
+      gesture-handler or other existing native deps.
+- [ ] Expo Go still launches the app with documented degradations only.
+- [ ] The release PR carries the required upgrade note and the breaking-release CI gate
+      passes.

package/src/docs/versioned/next/implementationPlans/orgs-and-teams.md

@@ -0,0 +1,158 @@
+# Implementation Plan: Organizations, teams, and multi-tenant scoping
+
+**Status:** Draft
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1024
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** none (soft: [rbac-permissions](rbac-permissions.md) for role vocabulary; this IP ships coarse org roles that RBAC later subsumes)
+**RTK deprecation flag:** None — backend only; frontend surfaces are `org-management-ui`
+
+## Goal
+
+Terreno's entire access story is per-user: `ownerId` fields, `OwnerQueryFilter`,
+`Permissions.IsOwner`. A B2B app needs data owned by an **organization** and accessed by
+its **members**. This IP adds the tenant analog of the owner stack to `@terreno/api`:
+Organization and Membership models, an org-context middleware, an `orgScopedPlugin` for
+schemas, `OrgQueryFilter` and `Permissions.IsOrgMember`/`IsOrgAdmin` for modelRouter, and
+CRUD routes for orgs and memberships — so `modelRouter(Todo, {queryFilter: OrgQueryFilter,
+permissions: {...IsOrgMember}})` is all an app needs for tenant-safe endpoints.
+
+## Non-Goals
+
+- Invitations, seat counting (`invitations-and-seats` item).
+- Fine-grained RBAC (roles beyond `member`/`admin` — [rbac-permissions](rbac-permissions.md)).
+- Org switcher and management screens (`org-management-ui` item).
+- Billing linkage (`billing-stripe` maps customers to orgs later).
+- Cross-org data sharing, nested teams/sub-orgs (future work).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| **D6 (resolved 2026-08-09):** native Mongoose models vs Better Auth `organization` plugin | **Native models.** The JWT/passport path (still supported and the example default) cannot use a Better-Auth-only construct; native models serve both auth paths, keep modelRouter/query-filter integration first-class, and can sync to Better Auth's plugin later if wanted |
+| Org context transport | `X-Organization-Id` header, resolved by middleware into `req.organization` + `req.membership`; explicit query/body override rejected |
+| One org or many per user? | Many (Membership join collection); apps wanting single-org enforce via option `maxOrgsPerUser: 1` |
+| Coarse roles now | `Membership.role: "admin" \| "member"` — deliberately minimal; RBAC IP replaces this enum with role references, migration documented there |
+| Scoping mechanism | `orgScopedPlugin` adds required indexed `organizationId`; `OrgQueryFilter` filters lists by active memberships; `preCreate` helper injects the context org |
+| Personal orgs? | No auto-created personal org; apps opt in via `createDefaultOrgOnSignup` option |
+
+## Architecture
+
+```
+api/src/orgs/
+  organizationModel.ts   # Organization + Membership schemas/models
+  orgContext.ts          # middleware: header → req.organization/req.membership
+  orgPlugin.ts           # orgScopedPlugin(schema) — organizationId field + index
+  orgPermissions.ts      # IsOrgMember, IsOrgAdmin, OrgQueryFilter
+  orgsApp.ts             # OrgsApp TerrenoPlugin — routes + options
+```
+
+`OrgsApp` options:
+
+```typescript
+new OrgsApp({
+  maxOrgsPerUser?: number;
+  createDefaultOrgOnSignup?: boolean;
+  onOrgCreated?: (org, owner) => Promise<void>;
+})
+```
+
+Request flow: `authenticateMiddleware` → `orgContextMiddleware` (loads org by header,
+verifies an active membership for `req.user`, 403 otherwise) → route. Routes that take
+`Permissions.IsOrgMember`/`IsOrgAdmin` require the context; `OrgQueryFilter` works with or
+without a context (no header → all orgs the user belongs to; header → that org only).
+
+## Models
+
+Both use the five-type pattern, `description` on every field, `createdUpdatedPlugin` +
+`isDeletedPlugin`, `strict: "throw"`.
+
+**Organization** — `name` (string, required), `slug` (string, unique, indexed, generated),
+`ownerId` (ref User, required — the creating user; ownership transferable), `settings`
+(Mixed, app-defined), `disabled` (boolean).
+
+**Membership** — `organizationId` (ref Organization, required, indexed), `userId` (ref
+User, required, indexed), `role` ("admin" | "member", default "member"), `status`
+("active" | "suspended", default "active"), compound unique index on
+`(organizationId, userId)`. Statics: `findActiveForUser`, `isMember`, `isOrgAdmin`.
+
+## APIs
+
+| Method | Path | Permissions | Notes |
+|---|---|---|---|
+| POST | `/orgs` | IsAuthenticated | Creates org + admin membership for creator; respects `maxOrgsPerUser` |
+| GET | `/orgs` | IsAuthenticated | Lists orgs the user belongs to (membership join) |
+| GET | `/orgs/:id` | IsOrgMember | |
+| PATCH | `/orgs/:id` | IsOrgAdmin | name/settings; ownership transfer admin-only |
+| DELETE | `/orgs/:id` | IsOrgAdmin | Soft delete; memberships cascade to suspended |
+| GET | `/orgs/:id/members` | IsOrgMember | Paginated membership list (populated user name/email) |
+| PATCH | `/orgs/:id/members/:memberId` | IsOrgAdmin | Role/status change; cannot demote last admin |
+| DELETE | `/orgs/:id/members/:memberId` | IsOrgAdmin | Remove member; cannot remove last admin |
+
+Member creation is **not** exposed here — members arrive via `invitations-and-seats`
+(or `createDefaultOrgOnSignup`). All routes via modelRouter where shapes fit, custom
+`createOpenApiBuilder` routes for member management.
+
+## Notifications
+
+None in this IP (invitation emails belong to `invitations-and-seats`).
+
+## UI
+
+None in this IP (`org-management-ui`). example-backend gains an org-scoped demo model
+(`Project`) exercising `orgScopedPlugin` + `OrgQueryFilter` end to end.
+
+## Phases
+
+1. **Models + plugin:** Organization, Membership, `orgScopedPlugin`, statics, unit tests.
+2. **Context + permissions:** middleware, `IsOrgMember`/`IsOrgAdmin`, `OrgQueryFilter`,
+   modelRouter integration tests (member of A cannot read B's rows — the critical suite).
+3. **Routes + app:** `OrgsApp`, org/member routes, last-admin guards, OpenAPI, supertest.
+4. **Example + docs:** example-backend `Project` model + routes, seeds, admin panel model
+   registration, `docs/how-to/add-organizations.md`, reference docs, SDK regen.
+
+## Feature Flags & Migrations
+
+No migration for existing apps (new collections; opt-in plugin). Adopting apps that
+backfill `organizationId` onto existing collections get a documented backfill recipe —
+formal tooling arrives with `mongo-migrations`.
+
+## Activity Log & User Updates
+
+Org create/delete and membership role changes fire an `onOrgAudit` hook (mirroring
+`onAdminAudit`) so apps can log them; framework-wide audit persistence is the
+`framework-audit-log` item.
+
+## Not Included / Future Work
+
+- Teams within orgs (the Membership schema reserves a `teamIds` extension point but ships
+  without it — YAGNI until a consumer needs it).
+- Org-level settings UI, domain capture/auto-join (SSO IP touches this).
+- Per-org rate limits, quotas.
+
+## Files to Create / Modify
+
+- `api/src/orgs/*` (new), `api/src/index.ts` exports
+- `api/src/permissions.ts` — export org permissions alongside existing ones
+- `example-backend/src/models/project.ts`, `api/projects.ts`, seeds, `server.ts`
+- `docs/how-to/add-organizations.md`, `docs/reference/api.md`
+- `example-frontend` SDK regen (`bun run sdk`) after backend routes land
+
+## Task List
+
+See [docs/tasks/orgs-and-teams.md](../tasks/orgs-and-teams.md).
+
+## Acceptance Criteria
+
+- [ ] A user can create an org, becoming its admin member; `maxOrgsPerUser` is enforced.
+- [ ] With two orgs seeded, a member of org A listing an org-scoped model with
+      `OrgQueryFilter` never receives org B documents — including via crafted `$or` /
+      query-param attempts.
+- [ ] Requests with an `X-Organization-Id` the user is not an active member of get 403.
+- [ ] The last admin of an org cannot be demoted or removed.
+- [ ] Org routes appear in `/openapi.json`; regenerated SDK compiles; admin panel can
+      browse Organizations and Memberships.
+- [ ] Soft-deleting an org suspends its memberships and hides its scoped data from lists.

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

@@ -1,6 +1,7 @@
 # Implementation Plan: OSS Governance Baseline
 
 **Status:** Approved — decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1003
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned