@terreno/mcp 57.17.0 → 57.18.0

package/dist/docs/versioned/57.17.0/implementationPlans/org-management-ui.md

@@ -0,0 +1,362 @@
+# Implementation Plan: Organizations as a first-class primitive (admin UI + RBAC)
+
+**Status:** Complete
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1024 (absorbs `orgs-and-teams`; retitle on approve)
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-08-24
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** [rbac-permissions](rbac-permissions.md) (Complete — PR #932)
+**Supersedes:** [orgs-and-teams](orgs-and-teams.md)
+**RTK deprecation flag:** Partial — admin screens use generated OpenAPI SDK / `useAdminApi`, not syncdb
+
+## Goal
+
+Organizations are a first-class Terreno primitive: native Organization and Membership
+models, request org context, tenant-safe `modelRouter` filters, and RBAC so **org-admins**
+run one org, **operators** run every org, and **superadmin** remains `*`.
+
+The product surface is the **admin panel** (`@terreno/admin-backend` +
+`@terreno/admin-frontend`, hosted by admin-spa and example-frontend `/admin`). Operators
+get a platform org directory. Org-admins get a switcher and only see the current org.
+No admin screen lists users, todos, or other tenant objects across orgs.
+
+## Non-Goals
+
+- Nested teams / sub-orgs.
+- Self-serve `POST /orgs` or create-org UI in the product (non-admin) app.
+- Invite-by-email tokens, accept/decline, seat counts (`invitations-and-seats`).
+- Billing checkout, plans, or Stripe (`billing-stripe`).
+- In-app org switcher outside admin.
+- Cross-org object lists (users, todos, projects, …).
+- Personal auto-created orgs (`createDefaultOrgOnSignup`).
+- Better Auth `organization` plugin as the source of truth (B2B D6: native models).
+
+Claude Design still specifies invite and billing frames so UI can be designed once; those
+frames are **not** acceptance criteria for this IP (see [Claude Design brief](#claude-design-brief)).
+
+## Decisions
+
+| ID | Question | Choice |
+| --- | --- | --- |
+| Q1 | IP vs `orgs-and-teams` | This IP owns backend **and** admin UI; `orgs-and-teams` is superseded |
+| Q2 | Roles | Three layers: `org-admin` (one org), `operator` (all orgs), `superadmin` (`*`) |
+| Q3/Q7 | UI home | `@terreno/admin-frontend` + `@terreno/admin-backend`; both admin-spa and example `/admin` |
+| Q4/Q6 | Invites + billing code | Out. Design brief includes those frames marked later |
+| Q5 | Design coverage | Switcher, settings, members, operator directory, **plus** invite wizard and billing settings as later frames |
+| Q8/Q11 | Surfaces | Operator-only `/admin/orgs` directory. Org-admins never see all orgs; switcher of orgs they admin only |
+| Q9 | Old IP | Supersede `orgs-and-teams`; B2B program points here |
+| Q10/Q13 | Org selection | Org entity routes: `/admin/orgs/:orgId`. Other admin screens: `X-Organization-Id`. Header optional if the caller admins exactly one org; **required** for `operator`/`superadmin` on tenant-scoped screens (400 if missing). Never unscoped lists |
+| Q12 | Who creates orgs | `operator` and `superadmin` only (API + `/admin/orgs`) |
+
+**Recorded assumptions (not grilled):** `org-admin` / `member` live on Membership (per org).
+`operator` / `superadmin` live on `user.roles`. Organizations are **opt-in**
+(`createAccess({ organizations: true })` + `TerrenoApp({ organizations: true })` or `OrgsApp`);
+existing single-tenant apps omit that flag. New apps from bootstrap enable organizations by
+default. Inherit native models, slugs, soft-delete,
+last-admin guards, and `X-Organization-Id` from the superseded IP. Admin data layer stays
+RTK/OpenAPI.
+
+## Architecture
+
+```
+@terreno/api
+  src/orgs/
+    organizationModel.ts   # Organization + Membership
+    orgPlugin.ts           # orgScopedPlugin → required indexed organizationId
+    orgContext.ts          # header / single-org inference → req.organization, req.membership
+    orgPermissions.ts      # OrgQueryFilter, IsOrgMember, requireOrgContext
+    orgsApp.ts             # OrgsApp TerrenoPlugin — public org/member routes
+  src/rbac/statements.ts   # + organization actions
+  src/rbac/roleModel.ts    # + operator, org-admin (locked); member stays empty globally
+
+@terreno/admin-backend
+  org admin routes under /admin/orgs
+  AdminApp list/create filters: OrgQueryFilter + requireOrgContext for org-scoped models
+
+@terreno/admin-frontend
+  orgs/OrgDirectoryScreen.tsx      # operator: all orgs
+  orgs/OrgSwitcher.tsx             # org-admin (and operator-in-org): current org
+  orgs/OrgSettingsScreen.tsx
+  orgs/OrgMembersScreen.tsx
+  orgs/useOrgContext.tsx           # URL + header for generated SDK
+```
+
+### Role storage
+
+| Role | Stored on | Scope |
+| --- | --- | --- |
+| `superadmin` | `user.roles` | Platform. `*` including operator powers |
+| `operator` | `user.roles` | Platform. Create/list/disable any org; enter any org context; assign org-admins |
+| `org-admin` | `Membership.roleName` | That organization only |
+| `member` | `Membership.roleName` | That organization only. No admin shell |
+
+Do not put `org-admin` on `user.roles`. A user may be `org-admin` of A and `member` of B.
+
+`can()` for `organization:*` on a specific org uses Membership in `req.organization`.
+`operator` / `superadmin` skip membership and still **must** send `X-Organization-Id` for
+tenant-scoped model lists (Q13). Platform `GET /admin/orgs` does not use the header.
+
+### Header resolution (`orgContextMiddleware`)
+
+Order:
+
+1. `X-Organization-Id` present → load org; allow if `operator`/`superadmin` **or** active membership; else 403.
+2. Tenant-scoped route and caller is `operator`/`superadmin` → **400** missing org context.
+3. Caller is `org-admin` of exactly one org → use that org.
+4. Caller is `org-admin` of many orgs → **400** must select (switcher).
+5. Else 403 for admin tenant routes. Plain members do not get the admin shell.
+
+`Permissions.IsOrganizationMember` / `OrgQueryFilter` read **memberships + context**, not
+`User.organizationIds`. Example-backend’s `organizationIds` array is removed in this IP.
+
+### Admin surfaces
+
+| Who | Sees | Never sees |
+| --- | --- | --- |
+| `operator`, `superadmin` | `/admin/orgs` (all orgs, create, disable, open). After picking an org: same org-scoped screens as org-admin | Unscoped Users/Todos/… tables |
+| `org-admin` | Switcher of orgs they admin; `/admin/orgs/:orgId` settings + members; other admin models with header | `/admin/orgs` directory of **all** orgs; any cross-org list |
+| `member` | Not this admin | — |
+
+Org entity URLs: `/admin/orgs`, `/admin/orgs/:orgId`, `/admin/orgs/:orgId/members`.
+Client sends `X-Organization-Id` from the switcher (or the path id) on every other admin
+request.
+
+### Request flow
+
+```
+authenticateMiddleware
+  → orgContextMiddleware (rules above)
+  → requireAccess / IsPermitted
+  → OrgQueryFilter (always {organizationId: context.id} when context exists)
+  → route
+```
+
+## Models
+
+Five-type pattern, `description` on every field, `createdUpdatedPlugin` + `isDeletedPlugin`,
+`strict: "throw"`. Skill: `mongoose-schema-safety`.
+
+**Organization** — `name` (required), `slug` (unique, indexed, generated), `ownerId` (creating
+operator/user; transferable), `settings` (Mixed, app-defined), `disabled` (boolean).
+
+**Membership** — `organizationId`, `userId`, `roleName` (`org-admin` \| `member`, default
+`member`), `status` (`active` \| `suspended`), compound unique `(organizationId, userId)`.
+Statics: `findActiveForUser`, `isOrgAdmin`, `isMember`.
+
+No `Membership.role: admin|member` enum from the old IP — RBAC names only.
+
+## RBAC vocabulary
+
+Add to `terrenoStatements`:
+
+```typescript
+organization: [
+  "create",
+  "list",
+  "read",
+  "update",
+  "delete",
+  "manageMembers",
+  "disable",
+]
+```
+
+Seeded locked roles (in addition to existing `superadmin`, `admin`, `auditor`, `member`):
+
+| name | permissions (sketch) |
+| --- | --- |
+| `operator` | `organization: *`, `admin: ["access"]`, `user: ["list","read","update"]` (always org-scoped by context) |
+| `org-admin` | Not a global `user.roles` seed used for grants. Statement bundle used when resolving Membership `roleName === "org-admin"`: `organization: ["read","update","manageMembers"]`, `admin: ["access"]` |
+
+Existing global `admin` role does **not** imply operator. Platform org directory is
+`organization:list` + `organization:create` (`operator` / `superadmin` only).
+
+## APIs
+
+### OrgsApp (framework)
+
+| Method | Path | Who | Notes |
+| --- | --- | --- | --- |
+| POST | `/orgs` | operator, superadmin | Create org; no membership required |
+| GET | `/orgs` | operator, superadmin | **All** orgs. Org-admins do not use this list |
+| GET | `/orgs/mine` | org-admin (and operator) | Orgs the caller may switch into (memberships they admin; operators: all) |
+| GET | `/orgs/:id` | org-admin of id, operator, superadmin | |
+| PATCH | `/orgs/:id` | org-admin of id, operator, superadmin | name/settings; disable is `organization:disable` (operator/superadmin) |
+| DELETE | `/orgs/:id` | operator, superadmin | Soft delete; memberships → suspended |
+| GET | `/orgs/:id/members` | org-admin of id, operator, superadmin | Paginated; populated user name/email |
+| POST | `/orgs/:id/members` | org-admin of id, operator, superadmin | Attach **existing** user by id/email; set `roleName`. No invite email |
+| PATCH | `/orgs/:id/members/:memberId` | org-admin of id, operator, superadmin | role/status; cannot demote last `org-admin` |
+| DELETE | `/orgs/:id/members/:memberId` | org-admin of id, operator, superadmin | Cannot remove last `org-admin` |
+
+Admin-backend may mount the same handlers at `/admin/orgs` with admin OpenAPI tags, or
+proxy OrgsApp. Prefer **one implementation** in `OrgsApp`, registered once; admin UI calls
+those paths (or `/admin/orgs` aliases). Pick chooses aliases vs shared router without
+changing permissions.
+
+Member **invite** is not exposed. UI shows a disabled Invite control (later IP).
+
+### Tenant-scoped modelRouter (example `Project`, admin Users if org-scoped)
+
+`queryFilter: OrgQueryFilter` (context org only). `preCreate` injects `organizationId`
+from context; client-supplied org id cannot win. Missing context for operators → 400.
+
+## Notifications
+
+None. Invitation email is `invitations-and-seats`.
+
+## UI
+
+Admin v2: org directory and switcher live in `navGlobal` (switcher) and `main` (directory,
+settings, members). Do not add a `home.slots` cross-org user table.
+
+Components use `@terreno/ui` (`Page`, `Box`, `DataTable`, `SelectField`, `Modal`, `Button`,
+`Badge`). New primitives only if composition fails (skill: `terreno-ui`).
+
+Wire screens in `admin-frontend`, then expo-router in `admin-spa` and
+`example-frontend/app/admin/orgs/`. Skill: `building-terreno-apps`, `verify-ui-changes`.
+
+**Invite** button: visible, disabled, helper “Invites ship in invitations-and-seats.”
+**Billing** tab/card: visible placeholder, “Billing ships in billing-stripe.”
+
+## Claude Design brief
+
+Copy everything in this section into Claude Design. Do not implement invite or billing in
+this IP; those frames are visual only.
+
+```text
+Product: Terreno admin panel (React Native Web + native via @terreno/ui).
+Theme: TerrenoProvider, Nunito body / Titillium headings, existing admin-spa shell
+(sidebar + top bar + page canvas). Do not invent a new design system.
+
+Users:
+1) superadmin — platform * (includes operator).
+2) operator — manages every organization; never sees unscoped object lists.
+3) org-admin — manages only organizations they admin; switcher required when they
+   admin more than one.
+4) member — not in this admin.
+
+Hard rule: no screen lists users, members, or any tenant object across organizations.
+The only all-orgs view is the operator Organization directory (org records only).
+
+Screens to design (this slice — implement):
+
+A) Operator — Organization directory (/admin/orgs)
+   - Table: name, slug, disabled, created, member count.
+   - Primary: Create organization (name → generates slug).
+   - Row click: enter that org (sets current org, navigates to org home/settings).
+   - Row action: Disable / Enable.
+   - Empty, loading, error states.
+   - Org-admins must not see this information architecture at all.
+
+B) Org switcher (admin chrome, navGlobal)
+   - Current org name + slug.
+   - Dropdown/list of orgs the viewer may enter (org-admin: memberships they admin;
+     operator: all orgs, or “Switch org” after entering from the directory).
+   - If exactly one org for an org-admin, still show the name; selecting is optional.
+   - Switching updates URL for org entity pages and X-Organization-Id for other pages.
+
+C) Organization settings (/admin/orgs/:orgId)
+   - Name, slug (read-only or constrained), disabled badge, owner.
+   - Save. Operator-only disable control.
+
+D) Members (/admin/orgs/:orgId/members)
+   - DataTable: name, email, roleName (org-admin | member), status, joined.
+   - Add member: pick existing user (email/id), assign role. No email invite send.
+   - Change role / suspend / remove. Block demoting or removing the last org-admin
+     with an inline error.
+   - Invite button present but disabled; caption that invites are a later feature.
+
+E) Other admin model tables (Users, Projects, …) while an org is selected
+   - Same existing AdminModelTable chrome.
+   - Banner or chip: “Viewing {org name}”.
+   - If operator has no org selected: blocking empty state “Select an organization”
+     (no table data), not an all-orgs dump.
+
+Screens to design (later — do not build in this IP):
+
+F) Invite wizard
+   - Invite by email, role on accept, expiry, pending/accepted/expired list,
+     resend/revoke. Connects to invitations-and-seats.
+
+G) Billing settings (org-scoped)
+   - Current plan, seats, Stripe checkout/portal CTAs, invoices list.
+   - Connects to billing-stripe. Web-first.
+
+Platforms: web (admin-spa) first; layouts must also work on native widths (same
+components). Desktop ~1280px content column and a ~390px mobile width.
+
+Deliver: one file per screen (A–G), sidebar with switcher, and a flow:
+operator creates org → opens it → adds existing user as org-admin → that user
+logs in, sees switcher, members table for that org only.
+```
+
+## Phases
+
+1. **Models + context** — Organization, Membership, `orgScopedPlugin`, header inference, isolation tests.
+2. **RBAC** — `organization` statements, `operator` role, membership-scoped `org-admin` resolution, admin shell access without `User.admin`.
+3. **Routes** — `OrgsApp` create/list/mine/members/last-admin; OpenAPI.
+4. **Admin backend** — `/admin/orgs` (or aliases), AdminApp `OrgQueryFilter` + 400 without context for operators.
+5. **Admin frontend** — directory, switcher, settings, members; spa + example routes; SDK.
+6. **Example + docs** — drop `User.organizationIds`; seeds (operator, two orgs, two org-admins); how-to/reference/explanation.
+
+## Feature Flags & Migrations
+
+New collections; organizations are opt-in (`createAccess({ organizations: true })` plus
+`OrgsApp` / `TerrenoApp({ organizations: true })`). Existing single-tenant apps are unchanged.
+New apps from `terreno_bootstrap_app` enable organizations by default. Adopting apps backfill
+`organizationId` with a documented recipe (formal migrator is `mongo-migrations`).
+
+Example-backend **breaking for the example app only:** remove `User.organizationIds`;
+resolve tenants via Membership. Seed users: `operator@example.com` (`operator`), two
+org-admins in distinct orgs, `admin@example.com` remains `superadmin`.
+
+## Activity Log & User Updates
+
+`onOrgAudit` hook (mirrors `onAdminAudit`) on org create/disable/delete and membership
+role/status changes. Framework-wide audit log stays `framework-audit-log`.
+
+## Not Included / Future Work
+
+- `invitations-and-seats`, `billing-stripe`, SSO domain capture, per-org rate limits.
+- Teams (`teamIds` reserved, not shipped).
+- Product-app signup → create org (B2B path after a tenant UI exists).
+
+## Files to Create / Modify
+
+- `api/src/orgs/*` (new), `api/src/rbac/statements.ts`, `api/src/rbac/roleModel.ts`, `api/src/permissions.ts`, exports
+- `admin-backend` org routes + AdminApp queryFilter/context
+- `admin-frontend/src/orgs/*`
+- `admin-spa/app/orgs/*`, nav
+- `example-backend` seeds, User model, Project routes, `access.ts` / `rbacRoles.ts`
+- `example-frontend/app/admin/orgs/*`, SDK regen
+- `docs/how-to/add-organizations.md`, `docs/explanation/organizations.md`, `docs/reference/api.md`, `docs/reference/admin-frontend.md`, `docs/reference/admin-backend.md`
+- This IP + `docs/tasks/org-management-ui.md`; superseded `orgs-and-teams`; B2B program; roadmap seed
+
+## Task List
+
+See [docs/tasks/org-management-ui.md](../tasks/org-management-ui.md).
+
+## Acceptance Criteria
+
+| Criterion | Verification |
+| --- | --- |
+| Operator creates an org via API and `/admin/orgs`; creator is not required to be a member | bun test / supertest; UI exercise |
+| Org-admin cannot `GET` the all-orgs directory (403) | supertest + UI (org-admin session has no directory nav) |
+| Org-admin switcher lists only orgs they admin; members table is that org only | supertest isolation + UI |
+| Two orgs seeded: listing an org-scoped model with context A never returns B, including crafted `$or` / query params | tenant isolation suite |
+| Operator omitting `X-Organization-Id` on Users/Projects admin list gets 400, not a cross-org list | supertest |
+| Org-admin of exactly one org can omit the header and still scoped correctly | supertest |
+| Last `org-admin` cannot be demoted or removed | supertest |
+| Attach existing user as member; no invite email sent | supertest; no comms call |
+| Invite and billing controls are visible and disabled / placeholder | UI tests + verify-ui screenshots |
+| Soft-delete org suspends memberships and hides scoped rows | bun test |
+| OpenAPI includes org routes; `bun run sdk` compiles | compile + sdk |
+| Docs: how-to + explanation + admin/api reference match shipped behavior | pages exist; Roast reads them |
+| `User.organizationIds` gone from example-backend | grep + tests |
+
+## Human gates
+
+Approve this Draft before Pick. Roadmap issue #1024 retitle/body on **Approved**
+(`roadmap-item` handoff). No production data migration in the example app beyond seeds.

package/dist/docs/versioned/57.17.0/implementationPlans/orgs-and-teams.md

@@ -0,0 +1,163 @@
+# Implementation Plan: Organizations, teams, and multi-tenant scoping
+
+**Status:** Superseded — 2026-08-24
+**Superseded by:** [org-management-ui](org-management-ui.md) (backend primitive + RBAC + admin UI)
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1024
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** superseded; see [org-management-ui](org-management-ui.md)
+**RTK deprecation flag:** None — backend only; frontend surfaces are `org-management-ui`
+
+Do not implement from this file. Canonical design, tasks, and acceptance criteria live on
+[org-management-ui](org-management-ui.md). Kept for decision history (native models, header
+transport) absorbed into that IP.
+
+## 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/dist/docs/versioned/57.17.0/implementationPlans/oss-governance-baseline.md

@@ -0,0 +1,149 @@
+# Implementation Plan: OSS Governance Baseline
+
+**Status:** Complete
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1003
+**Priority:** High
+**Effort:** Small batch
+**Owner:** unassigned
+**Created:** 2026-07-27
+**Program:** [OSS launch](oss-launch-program.md)
+**Depends on:** none
+**RTK deprecation flag:** None — no framework surface touched. Safe to implement before PR #869.
+
+## Goal
+
+Make the repository legally and procedurally publishable: a license every consumer can rely on, a documented contribution path, a security disclosure process, a living changelog, and GitHub's community-health files. Today the repo has two stray `LICENSE` files (`api/`, `ui/`), one stale `CHANGELOG.md` (`api/`, last entry 0.20.0 against a current 0.26.0), no root license, and no contributing/security/conduct documents.
+
+This is the hard blocker: without it, nothing else in the program can ship publicly.
+
+## Non-Goals
+
+- Rewriting the README's content or positioning — that is [`positioning-django-rails-universal`](positioning-django-rails-universal.md). This IP only *adds* the License / Contributing / Security / Code of Conduct links.
+- Auditing dependency licenses for compatibility.
+- Setting up sponsorship, OpenCollective, or a CLA bot.
+- Changing CI beyond adding license/community-file checks.
+
+## Blocking questions
+
+**Recorded 2026-07-29** (see program [P1–P2](oss-launch-program.md#blocking-questions-program-level)).
+
+| # | Question | Decision |
+|---|----------|----------|
+| G1 | License (→ P1) | **MIT everywhere** — root `LICENSE`, per-package `LICENSE` files, and all `package.json` `license` fields |
+| G2 | Copyright line | **`Copyright 2026 Flourish Health, Inc.`** in `LICENSE`; `NOTICE` credits contributors |
+| G3 | Contributor provenance (→ P2) | **DCO** — `Signed-off-by` enforced by CI on external PRs |
+| G4 | Security contact | **`security@terreno.app`** + GitHub private vulnerability reporting (PVR as primary) |
+| G5 | Changelog strategy | **Root `CHANGELOG.md`** in Keep-a-Changelog format; `api/CHANGELOG.md` becomes a pointer |
+| G6 | Enforce Conventional Commits? | **Yes, CI-enforced** on new PRs |
+| G7 | Code of Conduct | **Contributor Covenant 2.1** with **`conduct@terreno.app`** |
+
+## Architecture
+
+No code architecture. Three groups of artifacts:
+
+1. **Legal** — root `LICENSE`, `NOTICE`, per-package `LICENSE` files, `license` fields in every `package.json`, `files` arrays updated so the license ships in every npm tarball.
+2. **Process** — `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CHANGELOG.md`, `.github/ISSUE_TEMPLATE/*`, `.github/PULL_REQUEST_TEMPLATE.md`, `CODEOWNERS`.
+3. **Enforcement** — a `repo-policies.yml` job (the workflow already exists) that fails when a published package lacks a `LICENSE` in its `files` array or its `license` field disagrees with the root license.
+
+### Published packages requiring license coverage
+
+From `publish-on-tag.yml`, eleven packages publish in lockstep. Current state:
+
+| Package | `LICENSE` file | In `files` array | `license` field |
+|---------|----------------|------------------|-----------------|
+| `api` | yes | implicit (no `files`) | Apache-2.0 → **MIT** |
+| `ui` | yes | **missing from `files`** | Apache-2.0 → **MIT** |
+| `rtk` | **no** | **missing from `files`** | Apache-2.0 → **MIT** |
+| `ai` | **no** | implicit | Apache-2.0 → **MIT** |
+| `admin-backend` | **no** | implicit | Apache-2.0 → **MIT** |
+| `admin-frontend` | **no** | **missing from `files`** | Apache-2.0 → **MIT** |
+| `admin-spa` | **no** | **missing from `files`** | Apache-2.0 → **MIT** |
+| `api-health` | **no** | implicit | Apache-2.0 → **MIT** |
+| `feature-flags` | **no** | implicit | Apache-2.0 → **MIT** |
+| `mcp-server` | **no** | **missing from `files`** | MIT (already) |
+| `test` | **no** | implicit | Apache-2.0 → **MIT** |
+
+Task 1.2 must re-derive this table from the repo at implementation time rather than trusting it.
+
+## Models
+
+None.
+
+## APIs
+
+None.
+
+## Notifications
+
+None.
+
+## UI
+
+None.
+
+## Phases
+
+1. **Legal baseline** — root license, per-package licenses, `package.json` alignment, CI guard.
+2. **Contribution process** — `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, DCO check.
+3. **Changelog** — root `CHANGELOG.md`, backfill 0.20.0–0.26.0 from GitHub releases, wire into the `release` skill.
+4. **GitHub templates** — issue forms, PR template, `CODEOWNERS`, repo settings checklist.
+
+## Feature Flags & Migrations
+
+None. Relicensing `api` and `ui` from Apache-2.0 to MIT is a one-way change; it requires sign-off from every contributor to those packages who is not a Flourish employee (verify with `git log --format='%an %ae' -- api/ ui/`). `mcp-server` is already MIT.
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- Dependency license compatibility audit (`bunx license-checker`-style report).
+- `FUNDING.yml` / sponsorship.
+- Automated changelog generation from Conventional Commits.
+- Trademark policy for the Terreno name.
+
+## Files to Create / Modify
+
+**Create**
+
+- `LICENSE`
+- `NOTICE`
+- `CONTRIBUTING.md`
+- `CODE_OF_CONDUCT.md`
+- `SECURITY.md`
+- `CHANGELOG.md`
+- `rtk/LICENSE`, `ai/LICENSE`, `admin-backend/LICENSE`, `admin-frontend/LICENSE`, `admin-spa/LICENSE`, `api-health/LICENSE`, `feature-flags/LICENSE`, `mcp-server/LICENSE`, `test/LICENSE`
+- `.github/ISSUE_TEMPLATE/bug_report.yml`
+- `.github/ISSUE_TEMPLATE/feature_request.yml`
+- `.github/ISSUE_TEMPLATE/docs_issue.yml`
+- `.github/ISSUE_TEMPLATE/config.yml`
+- `.github/PULL_REQUEST_TEMPLATE.md`
+- `.github/CODEOWNERS`
+- `scripts/check-license-coverage.ts`
+
+**Modify**
+
+- `package.json` (root: add `license`)
+- `ui/package.json`, `rtk/package.json`, `admin-frontend/package.json`, `admin-spa/package.json`, `mcp-server/package.json` (`files` + `license`)
+- `api/CHANGELOG.md` (reduce to a pointer at the root changelog)
+- `README.md` (append License / Contributing / Security / Code of Conduct section and badge — content-neutral)
+- `.github/workflows/repo-policies.yml` (add license-coverage job)
+- `.rulesync/skills/release/SKILL.md` (require a root `CHANGELOG.md` entry per release)
+
+## Task List
+
+See [`docs/tasks/oss-governance-baseline.md`](../tasks/oss-governance-baseline.md).
+
+## Acceptance Criteria
+
+- [ ] `LICENSE` exists at the repo root and matches the decision from G1.
+- [ ] Every package in `publish-on-tag.yml` has a `LICENSE` file, a matching `license` field, and ships the license in its npm tarball (verified via `bun pm pack --dry-run` per package).
+- [ ] `bun run scripts/check-license-coverage.ts` exits 0 and fails when a `LICENSE` is deleted from any published package.
+- [ ] `CONTRIBUTING.md` documents: `bun run bootstrap`, how to run tests/lint per package, the no-barrel-imports rule, the IP process, DCO sign-off, and how to propose a change.
+- [ ] `SECURITY.md` lists supported versions and both reporting channels; GitHub private vulnerability reporting is enabled in repo settings.
+- [ ] `CODE_OF_CONDUCT.md` is Contributor Covenant 2.1 with a working report address.
+- [ ] `CHANGELOG.md` has entries for 0.20.0 through the current release, newest first, in Keep-a-Changelog format.
+- [ ] Opening a new issue in the GitHub UI offers Bug / Feature / Docs forms plus a link to Discussions.
+- [ ] `README.md` links License, Contributing, Security, and Code of Conduct above the fold or in a clearly labeled section.
+- [ ] `bun run lint` and `bun run rules:check` pass.