@terreno/mcp 57.0.0 → 57.2.0

package/src/docs/versioned/next/implementationPlans/org-management-ui.md

@@ -0,0 +1,357 @@
+# Implementation Plan: Organizations as a first-class primitive (admin UI + RBAC)
+
+**Status:** Draft — awaiting approval
+**Roadmap issue:** https://github.com/FlourishHealth/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`. 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; `OrgsApp` opt-in. 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/src/docs/versioned/next/implementationPlans/orgs-and-teams.md

@@ -1,15 +1,20 @@
 # Implementation Plan: Organizations, teams, and multi-tenant scoping
 
-**Status:** Draft
+**Status:** Superseded — 2026-08-24
+**Superseded by:** [org-management-ui](org-management-ui.md) (backend primitive + RBAC + admin UI)
 **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)
+**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`,

package/src/docs/versioned/next/implementationPlans/oss-launch-program.md

@@ -1,6 +1,7 @@
 # Program: Open Source Launch
 
 **Status:** Draft — decisions recorded (defaults accepted 2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1094
 **Priority:** High
 **Effort:** Epic (multiple IPs)
 **Owner:** unassigned
@@ -24,7 +25,9 @@ Three pillars, in priority order:
 2. **Universal by default** (the differentiator vs Django/Rails) — one codebase, three platforms. Not a web framework with a mobile bolt-on.
 3. **AI-native** (the differentiator vs everything) — two layers, and the docs must present them as complementary:
    - the **tool layer**: an MCP server with codegen, docs search, and runtime introspection (logs, client state, navigation), plus per-package agent guidelines;
-   - the **process layer**: the `/terreno-*` agentic SDLC pipeline shipped as an installable plugin — plan, implement test-first, verify in a fresh context, submit with evidence, then own the review loop to mergeable.
+   - the **process layer**: the `/terreno-*` lifecycle shipped as an installable plugin —
+     shape, implement test-first, verify in a fresh context, submit with evidence, then
+     react once per current PR state while an outer loop owns waiting and reinvocation.
 
    Agents are a first-class client of the framework, not an afterthought. Django gives you `manage.py startapp`; Terreno gives you a reviewed path from a request to a mergeable PR.
 
@@ -78,7 +81,13 @@ Combined with the already-shipped hosted tools (`terreno_search_docs`, `terreno_
 
 ## The `/terreno-*` SDLC pipeline
 
-The repo already ships the process half of the AI story and **has never documented it**: `.cursor-plugin/marketplace.json` plus `plugins/terreno-planning/` define an installable five-stage pipeline — **`/terreno-1-grow`** (plan), **`/terreno-2-harvest`** (implement), **`/terreno-3-roast`** (verify), **`/terreno-4-brew`** (submit), **`/terreno-5-taste`** (review loop until mergeable). Legacy names (`blend`, `cupping`, `pour`, `dialin`) remain as aliases during the rename — see [`agentic-sdlc-plugin.md`](agentic-sdlc-plugin.md).
+The repo already ships the process half of the AI story: `.cursor-plugin/marketplace.json`
+plus `plugins/terreno-planning/` define five bounded transitions —
+**`/terreno-1-grow`** (shape), **`/terreno-2-pick`** (build),
+**`/terreno-3-roast`** (prove), **`/terreno-4-brew`** (submit), and
+**`/terreno-5-taste`** (react once). The outer loop owns persistence, waiting, retry, and
+escalation. Former command names are a documented hard-cut migration — see
+[`agentic-sdlc-plugin.md`](agentic-sdlc-plugin.md).
 
 It encodes real judgment rather than automation: a question-first planning gate that refuses to commit to decisions before they are answered, independent review and test-quality sub-agents spawned in **fresh contexts** after every commit, drift detection against the plan, anti-mocking rules, a hard frontend-evidence gate, and a refusal to push speculative fixes for flaky CI.
 

package/src/docs/versioned/next/implementationPlans/pluggable-database-sqlite-research.md

@@ -0,0 +1,150 @@
+# Research: Pluggable database layer and SQLite support
+
+**Status:** Complete — decisions made, IP written: [pluggable-database-sqlite.md](pluggable-database-sqlite.md)
+**Created:** 2026-08-20
+
+## Scope statement
+
+Evaluate how to make the persistence layer of `@terreno/api` (and the packages that build on it) pluggable so that SQLite can be used as an alternative to MongoDB/Mongoose, with special attention to:
+
+- Making the current Mongoose handler one implementation behind a database-agnostic seam.
+- Options for **schema definition** that minimize disruption to existing Terreno codebases (which all author `new mongoose.Schema(...)` today).
+- Which framework capabilities can realistically be ported to SQLite in a first release versus which stay Mongo-only behind capability flags.
+
+## PRD summary
+
+From the request:
+
+- **Problem:** Terreno is MongoDB-only. Every consumer must run a Mongo replica set (even for small apps and local dev), and the positioning docs explicitly rule out relational databases. This limits adoption (SQLite/libSQL is the default for many small deployments, edge platforms, and quick starts).
+- **Goal:** Support SQLite in `@terreno/api` and any other package that needs it; make the Mongoose handler pluggable rather than hard-wired.
+- **Explicit ask:** Present a few options for how to handle schemas with the minimal amount of disruption to existing codebases.
+
+## Codebase findings
+
+### Coupling depth (where Mongoose lives today)
+
+There is **no storage abstraction seam** in the framework today — no repository, `DatabaseAdapter`, or dialect-neutral query builder. Mongoose is the schema source of truth and the runtime data API.
+
+| Layer | Depth | Key touchpoints |
+|---|---|---|
+| CRUD (`modelRouter` + executors) | Very high | `api/src/api.ts`, `api/src/sync/executors.ts`, `api/src/docLoader.ts` — `find/findById/create/doc.save()/deleteOne/countDocuments/populate`, hydrated `Document`s, soft-delete via query middleware, native `model.collection.findOne` probe |
+| Schema plugins | Very high | `api/src/plugins.ts` — `createdUpdatedPlugin`, `isDeletedPlugin`, `findExactlyOne`/`findOneOrNone`, `upsertPlugin`, custom `DateOnly` `SchemaType`; plus `configurationPlugin`, `syncPlugin`, `errorsPlugin`, `githubUserPlugin` |
+| OpenAPI generation | High | `api/src/populate.ts` `getOpenApiSpecForModel` via `mongoose-to-swagger`; reads `schema.paths`, `options.ref`, virtuals, child schemas, `instance === "Mixed"`; feeds `openApi.ts`, AJV validation (`openApiValidator.ts`), and admin metadata |
+| Auth | High | `api/src/auth.ts` `UserModel extends Model<User>` requiring passport-local-mongoose statics; `betterAuthSetup.ts` hard-wires `mongodbAdapter` off the global `mongoose.connection` |
+| Realtime / sync | Extreme (Mongo-only) | `api/src/realtime/changeStreamWatcher.ts` (`db.watch()`, resume tokens, replica set required), `api/src/sync/models.ts` (`$inc` seq counters, optional `ClientSession`), `feature-flags` `.watch()` |
+| Query language | Public API | modelRouter passes Mongo filter objects through (`$and`/`$or`, `_gte`/`_lte` → `$gte`/`$lte`, `OwnerQueryFilter` returns Mongo filters); `realtime/queryMatcher.ts` re-implements Mongo matching in memory |
+
+`mongoose` is a **peerDependency** of `@terreno/api` (`^8 || ^9`); the catalog pins `9.7.4`. Connection lifecycle is the consumer's job (`example-backend/src/utils/database.ts`); the framework assumes the global `mongoose.connection` for change streams and Better Auth.
+
+### Schema definition surface (what "schemas" means downstream)
+
+Mongoose schemas are consumed by four downstream systems, all of which would need a story under any schema-handling option:
+
+1. **OpenAPI**: `mongoose-to-swagger` reads `required`, `enum`, `default`, `readOnly`, `description`; populate/ref metadata comes from raw `schema.path(key).options.ref`.
+2. **Admin** (`admin-backend/src/adminApp.ts`): builds `/admin/config` field metadata from `getOpenApiSpecForModel` + raw `schema.paths` for refs and allowlists.
+3. **syncdb codegen** ([syncdb-codegen.md](syncdb-codegen.md), approved): generates TypeScript **from the OpenAPI spec**, not from schemas directly — so anything that produces equivalent OpenAPI keeps codegen working unchanged.
+4. **MCP** (`mcp-server/src/tools.ts` `terreno_generate_model`): scaffolds Mongoose schema source code.
+
+### Package-by-package Mongoose exposure
+
+| Package | Exposure |
+|---|---|
+| `api` | Structural (see above) |
+| `admin-backend` | Deep — `Model<any>` config, `schema.paths`, ObjectId search, modelRouter CRUD |
+| `comms` | Deep — own Mongoose models (`PushToken`, `CommsMessage`) + modelRouter + direct queries |
+| `ai` | Deep — own Mongoose models (`AIRequest`, `GptHistory`) + modelRouter + aggregation |
+| `feature-flags` | Deep + Mongo-only `.watch()` |
+| `example-backend` | Canonical consumer (connect lifecycle, models, change streams) |
+| `syncdb` (client) | **None** — transport/protocol only, but the server side of the protocol is Mongo-only today |
+| `rtk`, `ui`, `admin-frontend`, `admin-spa` | None |
+| `mcp-server` | Codegen templates emit Mongoose; local tools connect via mongoose |
+| `test` | mongodb-memory-server harness (`TERRENO_TEST_MONGODB_URI`, replica set option, transaction patches) |
+
+### Useful precedents already in-repo
+
+- **String `_id`**: synced models already use String `_id` (hex string default) — precedent for non-ObjectId primary keys.
+- **In-memory Mongo query matcher** (`realtime/queryMatcher.ts`): the framework already treats "a Mongo filter object" as an evaluable spec independent of the database.
+- **Executor seam** (`executeCreate/Update/Delete`): HTTP and sync share one write path — the natural place to insert an adapter.
+- **`TerrenoPlugin` / comms adapter pattern**: the repo already ships pluggable-provider IPs ([comms-abstraction.md](comms-abstraction.md)) — an established shape for "core interface + adapter packages".
+- **zod** (`^4.4.3`) is already a peer of `@terreno/api` and used for action bodies via `zodOpenApi.ts`.
+
+## External findings
+
+- **Better Auth** supports SQLite first-class: built-in Kysely adapter accepts `better-sqlite3`, `node:sqlite` (Node ≥ 22.5), and `bun:sqlite` instances, plus a Drizzle adapter with `provider: "sqlite"`. The Mongo-only hard-wiring in `betterAuthSetup.ts` is a Terreno choice, not a Better Auth limitation.
+- **SQLite as a document store** is a well-trodden pattern: one table per collection with a JSON column (`TEXT` + `json_valid` check), queried via the JSON1 functions (`json_extract`), with **generated columns + indexes** for hot query fields. This preserves Mongo-style nested/Mixed/array data without a relational schema migration story.
+- **Mongo-filter → SQL translation** for the subset modelRouter actually emits (equality, `$in`, `$ne`, `$gte`/`$lte`, `$and`/`$or`, `$exists`) is small and testable; the existing `queryMatcher.ts` documents the exact operator surface needed.
+- **Change streams have no SQLite equivalent.** SQLite alternatives are `data_version` pragma polling, update hooks (better-sqlite3 exposes none; libSQL/Turso has limited CDC), or an app-level outbox table. Realtime/sync on SQLite therefore needs a different backend (likely outbox-table + in-process emit) or stays Mongo-only initially.
+- **Driver options**: `bun:sqlite` (zero-dep under Bun, not Node), `better-sqlite3` (Node, native build), `node:sqlite` (release candidate, Node ≥ 22.5), `libsql` (Turso-compatible, adds remote/replica options). Drizzle supports all of them if an ORM layer is wanted.
+
+## Candidate options
+
+### Decision 1 — Schema definition (the user's headline question)
+
+**Option A — Mongoose schema stays the authoring format; adapters interpret it.**
+Consumers keep writing `new mongoose.Schema({...})` exactly as today. A `DatabaseAdapter` receives the compiled model; the SQLite adapter reads `schema.paths` (types, refs, required, enum, defaults, descriptions) to derive its storage and to feed OpenAPI/admin unchanged. Mongoose remains a dependency even for SQLite users, but only as a schema DSL + document hydrator (it can define schemas without a connection).
+
+- Disruption: **zero** for existing codebases; plugins, `strict: "throw"`, virtuals, and the model-type pattern all keep working.
+- Risk: Mongoose document semantics (hooks, `doc.save()`, query middleware) must be emulated or bypassed on SQLite; hidden Mongo-isms can leak. Mongoose stays a hard dependency of the "database-agnostic" framework, which is philosophically odd but pragmatic.
+
+**Option B — New Terreno schema DSL (framework-owned AST).**
+`defineModel({fields: {...}})` produces a framework-native schema AST that compiles to a Mongoose schema on Mongo and to SQLite DDL/JSON layout on SQLite, and directly emits OpenAPI (dropping `mongoose-to-swagger`). Existing codebases migrate via codemod; a compatibility shim could wrap existing Mongoose schemas during transition.
+
+- Disruption: **high** (every model file in every consumer changes), but one-time and mostly mechanical.
+- Payoff: the framework owns its schema story end-to-end (OpenAPI, admin, MCP codegen, future Postgres); no per-adapter schema interpretation.
+
+**Option C — zod as the schema source.**
+Models defined as zod objects (already in the tree, already OpenAPI-bridged via `zodOpenApi.ts`) plus a metadata layer for refs/indexes/defaults. Adapters derive Mongoose schemas or SQLite DDL from the zod definition.
+
+- Disruption: **high** (same migration burden as B) and zod lacks natural homes for DB concerns (indexes, refs, hooks), so a wrapper DSL emerges anyway — effectively Option B with zod as the type layer.
+
+**Option D — Adopt a multi-dialect ORM (Drizzle/Prisma) as the schema layer.**
+- Disruption: **highest**; abandons the Mongoose ecosystem (plugins, populate, discriminators) and Mongo support in Drizzle is immature. Likely reject, but listed for completeness.
+
+A staged path is possible: **A now, B later** — ship the adapter seam with Mongoose-as-DSL (A), and treat a framework-owned schema AST (B) as the eventual next-major direction once the adapter surface is proven.
+
+### Decision 2 — SQLite storage model (if A is chosen)
+
+- **A1 — Document store**: one table per model: `_id TEXT PRIMARY KEY, doc JSON`, generated columns + indexes for `queryFields` and sort keys. Arrays, nested docs, and Mixed work unchanged; Mongo-filter translation targets `json_extract`. Closest semantics to today.
+- **A2 — Relational mapping**: schema paths → real columns; arrays/Mixed still fall back to JSON columns. More natural SQL, but introduces a migration story (ALTER TABLE on schema change) and diverges from Mongo semantics.
+
+### Decision 3 — Adapter seam shape
+
+Insert a `DatabaseAdapter` (working name) behind the executor/docLoader surface: `create / findById / list(query, sort, skip, limit) / count / save(diff) / delete / populate?`, plus a `translateQuery` boundary where the Mongo-filter subset is either executed natively (Mongo) or compiled to SQL (SQLite). Capabilities beyond CRUD are declared, not assumed:
+
+```
+interface DatabaseAdapter {
+  capabilities: {changeStreams: boolean; transactions: boolean; textSearch: boolean; ...};
+}
+```
+
+Mongo-only features (change-stream realtime, syncdb server protocol, feature-flag watchers, Atlas `$search`) check capabilities and either degrade (polling/outbox) or refuse with a clear error.
+
+### Decision 4 — Auth on SQLite
+
+- Better Auth: swap the hard-wired `mongodbAdapter` for adapter-provided database handles (Kysely/Drizzle SQLite are first-class upstream).
+- Legacy JWT/passport path: `passport-local-mongoose` is Mongo-only; either implement a portable credential store on the adapter surface, or make Better Auth the required auth provider on SQLite.
+
+### Decision 5 — Packaging
+
+- `@terreno/api` keeps the interface + Mongoose adapter (default, zero breaking change); SQLite ships as `@terreno/db-sqlite` (mirrors the comms adapter-package pattern), or everything lives in `api` behind optional peer deps.
+
+## Open questions (blocking)
+
+Recorded in the planning thread; the IP will not be written until these are answered:
+
+1. Schema authoring: A (Mongoose-as-DSL, zero disruption), B (new DSL, high one-time disruption), C (zod), or staged A→B?
+2. SQLite storage model: A1 document-style vs A2 relational?
+3. v1 capability line: which of realtime/syncdb-server/feature-flag-watch/Atlas-search are Mongo-only at launch?
+4. Auth on SQLite: Better Auth required, or portable credential store for the JWT path too?
+5. Query language: keep the Mongo filter subset as the public/adapter contract, or introduce a neutral filter DSL?
+6. Package scope: `api` + example-backend only for v1, or also `admin-backend`/`comms`/`ai`/`feature-flags`?
+7. SQLite driver: `bun:sqlite` vs `better-sqlite3` vs `node:sqlite` vs `libsql` (and does Node support matter for v1)?
+8. Packaging: separate `@terreno/db-sqlite` package vs in-`api` optional dependency?
+
+## References
+
+- `api/src/api.ts`, `api/src/sync/executors.ts`, `api/src/docLoader.ts`, `api/src/plugins.ts`, `api/src/populate.ts`, `api/src/openApi.ts`, `api/src/auth.ts`, `api/src/betterAuthSetup.ts`, `api/src/realtime/changeStreamWatcher.ts`, `api/src/realtime/queryMatcher.ts`, `api/src/sync/models.ts`
+- `admin-backend/src/adminApp.ts`, `mcp-server/src/tools.ts`, `test/src/mongo/mongoServer.ts`
+- [syncdb-codegen.md](syncdb-codegen.md), [comms-abstraction.md](comms-abstraction.md), [positioning-django-rails-universal.md](positioning-django-rails-universal.md), [deploy-to-gcp.md](deploy-to-gcp.md) (GC2 future-Postgres note)
+- Better Auth SQLite adapters: https://better-auth.com/docs/adapters/sqlite ; Drizzle adapter: https://better-auth.com/docs/adapters/drizzle
+- Prior art: [PR #145](https://github.com/FlourishHealth/terreno/pull/145) (closed) — an earlier SQL-adapter plan proposing Bun.SQL multi-dialect support and JOIN-based population; superseded by this IP's adapter seam + batched population design