@terreno/mcp 0.29.0 → 0.31.0

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

package/dist/docs/versioned/next/implementationPlans/password-reset-and-email-verification.md

@@ -0,0 +1,147 @@
+# Implementation Plan: Password reset and email verification
+
+**Status:** Draft
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1023
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** [comms-abstraction](comms-abstraction.md), [comms-adapter-sendgrid](comms-adapter-sendgrid.md)
+**RTK deprecation flag:** None — the RTK client's existing `resetPassword` endpoint gets a
+backend at last; new client work is a thin screen pair noted in UI
+
+## Goal
+
+The JWT auth path has no way to recover an account or verify an email address: the
+`@terreno/rtk` client ships a `resetPassword` mutation with **no backend route**, and
+nothing sets or checks email verification. This IP adds forgot/reset password and email
+verification flows to `@terreno/api`'s JWT auth, wires the Better Auth equivalents to the
+same mail templates, and sends everything through `@terreno/comms`.
+
+## Non-Goals
+
+- MFA / step-up auth (`mfa-step-up-auth` item).
+- Magic-link login.
+- SMS-based recovery (possible later via the Twilio Verify adapter).
+- Account lockout / brute-force throttling beyond token single-use + expiry
+  (`rate-limiting` item hardens the endpoints).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Token design | 32-byte crypto-random token, stored **hashed** (sha256) with expiry (`1h` reset / `24h` verify) and single-use consumption; separate `AuthToken` collection rather than fields on User |
+| Enumeration safety | `POST /auth/forgotPassword` always returns 202 regardless of whether the email exists |
+| Password set mechanism | `passport-local-mongoose`'s `setPassword` on the user document, then invalidate all refresh tokens |
+| RTK client compatibility | The existing RTK `resetPassword` endpoint's path/shape is the contract — verify at implementation time and alias if it differs from `/auth/resetPassword` |
+| Verification gating | Opt-in `requireEmailVerification` auth option: unverified users get 403 with code `email-not-verified` on login; default off (non-breaking) |
+| Better Auth path | Enable Better Auth's built-in reset/verification, providing `sendResetPassword` / `sendVerificationEmail` hooks that call the same comms templates so both auth paths send identical mail |
+| Link targets | Deep-link/URL base from a new `authOptions.publicAppUrl`; web route examples in example-frontend |
+
+## Architecture
+
+```
+api/src/authTokens.ts      # AuthToken model + issue/consume helpers
+api/src/authRecovery.ts    # forgot/reset/verify routes + options
+                           # registered by addAuthRoutes when comms is available
+comms templates            # resetPassword + verifyEmail templates (subject/text/html)
+```
+
+Flow (reset): `POST /auth/forgotPassword {email}` → 202 always; if user exists, issue
+token, send mail with `${publicAppUrl}/resetPassword?token=...` → `POST
+/auth/resetPassword {token, password}` → validate + consume token, `setPassword`,
+invalidate refresh tokens, 200.
+
+Flow (verify): token issued on signup (and via `POST /auth/sendVerification` for
+re-sends, authenticated); `POST /auth/verifyEmail {token}` sets `user.emailVerified =
+true`.
+
+## Models
+
+**AuthToken** — `userId` (ref User, required, indexed), `tokenHash` (string, unique),
+`type` ("passwordReset" | "emailVerification"), `expiresAt` (date, TTL-indexed),
+`consumedAt` (date, optional). Statics: `issueFor(user, type)`, `consume(token, type)`
+(atomic findOneAndUpdate guarding single-use).
+
+**User** — adds `emailVerified` (boolean, default false) via a small
+`emailVerificationPlugin` so existing user schemas opt in without breaking.
+
+## APIs
+
+| Method | Path | Permissions | Notes |
+|---|---|---|---|
+| POST | `/auth/forgotPassword` | anonymous | `{email}` → always 202 |
+| POST | `/auth/resetPassword` | anonymous | `{token, password}`; path/shape matched to the RTK client contract |
+| POST | `/auth/sendVerification` | IsAuthenticated | Re-send verification mail |
+| POST | `/auth/verifyEmail` | anonymous | `{token}` |
+
+All registered by `addAuthRoutes` when a mail-capable `CommsApp` is present; without one,
+routes 501 in production and console-send in development (inherited comms behavior).
+
+## Notifications
+
+Two mail templates (`resetPassword`, `verifyEmail`) shipped in `@terreno/comms` templates
+with app-override hooks.
+
+## UI
+
+example-frontend: `/resetPassword` (token from URL, new-password form using the existing
+RTK `resetPassword` mutation) and a "verify your email" banner + re-send button on the
+profile screen. `LoginScreen` gains an optional `onForgotPassword` link prop in
+`@terreno/ui`.
+
+## Phases
+
+1. **Token infrastructure:** AuthToken model, issue/consume, `emailVerificationPlugin`,
+   unit tests.
+2. **JWT routes + mail:** four routes, templates, refresh-token invalidation,
+   enumeration-safety + single-use/expiry test suite.
+3. **Better Auth parity:** wire `sendResetPassword`/`sendVerificationEmail` hooks to the
+   same templates; parity tests.
+4. **Client + docs:** example-frontend screens, `@terreno/ui` login link prop, SDK regen,
+   `docs/how-to/password-reset.md`, env/reference docs.
+
+## Feature Flags & Migrations
+
+`requireEmailVerification` defaults off; enabling it for an existing app is documented
+(backfill `emailVerified: true` for existing users or accept re-verification). No schema
+migration otherwise.
+
+## Activity Log & User Updates
+
+Token issue/consume and verification events logged via `logger` and `CommsMessage`
+rows; no user-facing activity feed.
+
+## Not Included / Future Work
+
+- Password strength policy hooks (exists via `PasswordRequirements` UI; server policy is
+  future work).
+- Admin-triggered forced resets (admin panel action — future).
+- Endpoint rate limiting (`rate-limiting` item).
+
+## Files to Create / Modify
+
+- `api/src/authTokens.ts`, `api/src/authRecovery.ts` (new), `api/src/auth.ts`,
+  `api/src/plugins.ts` (emailVerificationPlugin), `api/src/index.ts`
+- `comms/src/templates.ts` — two templates
+- `example-frontend/app/resetPassword.tsx`, profile banner, SDK regen
+- `ui/src/login/LoginScreen.tsx` — `onForgotPassword` prop
+- `docs/how-to/password-reset.md`, `docs/reference/environment-variables.md`
+
+## Task List
+
+See [docs/tasks/password-reset-and-email-verification.md](../tasks/password-reset-and-email-verification.md).
+
+## Acceptance Criteria
+
+- [ ] `POST /auth/forgotPassword` returns 202 for existing and non-existing emails alike,
+      sending mail only for existing ones.
+- [ ] A reset token works exactly once, fails after expiry, and a successful reset
+      invalidates outstanding refresh tokens.
+- [ ] The unmodified RTK client `resetPassword` mutation completes the flow end to end.
+- [ ] With `requireEmailVerification` on, an unverified user gets 403 code
+      `email-not-verified` on login and can complete verification to proceed.
+- [ ] Better Auth mode sends the same two templates through comms.
+- [ ] example-frontend can complete forgot → email link (console adapter output in dev) →
+      reset → login with the new password; UI verification evidence attached to the PR.

package/dist/docs/versioned/next/implementationPlans/positioning-django-rails-universal.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Positioning — "Django/Rails for TypeScript, with Universal Apps"
 
 **Status:** Draft — blocking questions open
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1008
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned

package/dist/docs/versioned/next/implementationPlans/public-roadmap-github.md

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

package/dist/docs/versioned/next/implementationPlans/rtk-to-syncdb-migration-docs.md

@@ -1,13 +1,14 @@
 # Implementation Plan: RTK Deprecation and SyncDB Migration Docs
 
-**Status:** Draft — blocked on PR #869
+**Status:** Draft — blocked; the syncdb source does not exist yet
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1007
 **Priority:** Critical (gates most of Wave 1)
 **Effort:** Big batch
 **Owner:** unassigned
 **Created:** 2026-07-27
 **Program:** [OSS launch](oss-launch-program.md)
-**Depends on:** PR [#869](https://github.com/flourishhealth/terreno/pull/869) merging
-**RTK deprecation flag:** **Blocked** — this IP *is* the RTK deprecation. Nothing here can be written until #869 lands, because the public surface of `@terreno/syncdb` is not final until then.
+**Depends on:** a merged `@terreno/syncdb` package. PR [#869](https://github.com/flourishhealth/terreno/pull/869) was the delivery vehicle but is **closed, not merged** (checked 2026-08-09); no `syncdb/` package exists on `master`. This IP stays blocked until a syncdb PR lands and `git log --oneline master | rg -i syncdb` shows the merged package.
+**RTK deprecation flag:** **Blocked** — this IP *is* the RTK deprecation. Nothing here can be written until syncdb lands, because the public surface of `@terreno/syncdb` is not final until then.
 
 ## Goal
 
@@ -33,7 +34,7 @@ Scope is documentation, deprecation signalling, and migration tooling — not sy
 | M3 | Auth vs data migration | **C** — Better Auth first, then syncdb |
 | M4 | `docs/reference/rtk.md` (→ P7 **A**) | **Remove from the public reference index** — no legacy reference page. Existing RTK consumers use **`docs/how-to/migrate-rtk-to-syncdb.md`** only; do not maintain a parallel RTK reference path in launch docs |
 | M5 | SDK codegen command | **A** — `bun run sdk` keeps working |
-| M6 | Codemod | **B** — agent-assisted via `upgrading-terreno` skill |
+| M6 | Codemod | **B (reaffirmed 2026-08-09)** — no migration script or codemod. The migration is agent-assisted: ship the *context* an AI coding agent needs to perform the migration in a specific app (the syncdb reference, verified before/after pairs, and the `upgrading-terreno` skill), not a mechanical transform. See "Migration strategy" below |
 | M7 | Local-first default | **A** if #869 ships local-first only (verify against merged code) |
 
 ## Architecture
@@ -57,6 +58,50 @@ Every document below currently describes an RTK-shaped world and must be reconci
 | `README.md` architecture diagram | `@terreno/rtk` box | `@terreno/syncdb` box |
 | `mcp-server` resources + bootstrap templates | RTK store wiring | syncdb client wiring |
 
+### Migration strategy: AI-context-first (not codemods)
+
+The migration is delivered as **context for an AI coding agent to perform the
+migration in a specific app**, not as a script that mechanically transforms code.
+A one-size codemod is the wrong tool here: the RTK → syncdb move is not a
+find-and-replace. Writes change semantics (local-first, optimistic code gets
+*deleted*), conflicts and sync status are net-new concepts with app-specific UI,
+and auth migrates on its own schedule. Those are judgment calls an agent makes
+per screen with the right context — not transforms a codemod can apply blindly.
+
+Concretely, this IP ships three context artifacts and no migration script:
+
+1. **The syncdb reference** (`docs/reference/syncdb.md`) — the ground-truth API
+   surface the agent maps RTK calls onto.
+2. **The migration guide** (`docs/how-to/migrate-rtk-to-syncdb.md`) — organized by
+   *what the developer changes*, with **verified before/after pairs** taken from
+   the real `example-frontend` migration. These pairs are the highest-value
+   context: an agent generalizes from a correct concrete example far better than
+   from prose rules.
+3. **The `upgrading-terreno` skill** (owned by
+   [`upgrade-guides-and-skill`](upgrade-guides-and-skill.md)) — the procedure that
+   points an agent at the reference and guide, tells it to migrate one screen at
+   a time behind `USE_SYNCDB`, verify, and repeat. The skill encodes *how to
+   drive the migration*; it does not encode the edits themselves.
+
+Design rules that follow from this strategy:
+
+- **Every code sample must be real and compile against the merged syncdb** — an
+  agent will copy them, so an invented sample produces broken migrations at scale.
+- **Name what to delete, not just what to add.** The parts consumers get wrong
+  are the RTK patterns that become dead code (manual optimistic updates, write
+  spinners, refetch-after-mutate); the guide must call these out explicitly so an
+  agent removes them.
+- **Prefer decision tables and per-step checklists** (agent-followable) over long
+  narrative. The copy-pasteable checklist in step 11 doubles as an agent to-do
+  list.
+- **Keep the rollout unit small** — per screen via `USE_SYNCDB` — so an agent can
+  migrate, verify, and stop at any point.
+
+If a mechanical helper turns out to be genuinely safe for a narrow sub-step (for
+example a pure import rename during the support window), it may be added later as
+an *optional* convenience, but it is never the primary path and never a
+precondition for migrating.
+
 ### The migration guide's shape
 
 The migration guide is the highest-value artifact. It must be organized by *what the developer has to change*, not by package internals:

package/dist/docs/versioned/next/implementationPlans/upgrade-guides-and-skill.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Upgrade Guides and the `upgrading-terreno` Skill
 
 **Status:** Draft — blocked on PR #869
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1013
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/dist/docs/versioned/next/implementationPlans/web-ssr-and-admin-spa.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Server-Side Rendering for Universal Web (and Admin SPA)
 
 **Status:** Draft — blocking questions open
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1017
 **Priority:** Medium
 **Effort:** Epic
 **Owner:** unassigned

package/dist/docs/versioned/next/reference/README.md

@@ -7,10 +7,14 @@ Technical reference for Terreno packages and APIs. Information-oriented, precise
 - [@terreno/api](api.md) — modelRouter, auth, permissions, setupServer
 - [@terreno/ui](ui.md) — Components, theming, layout
 - [@terreno/rtk](rtk.md) — Auth slice, SDK codegen, token handling
+- [@terreno/ai](ai.md) — AI service, GPT routes, Langfuse integration
 - [@terreno/admin-backend](admin-backend.md) — Auto-generated admin CRUD endpoints
 - [@terreno/admin-frontend](admin-frontend.md) — Admin panel UI components
+- [@terreno/admin-spa](admin-spa.md) — Standalone admin SPA + Express serve plugin
+- [@terreno/api-health](api-health.md) — Health check TerrenoPlugin
 - [@terreno/feature-flags](feature-flags.md) — Feature flags and A/B testing plugin
 - [@terreno/mcp](mcp-server.md) — AI coding assistant integration (MCP)
+- [@terreno/test](test.md) — Bun test helpers and in-memory MongoDB
 
 ## Configuration
 

package/dist/docs/versioned/next/reference/admin-spa.md

@@ -0,0 +1,130 @@
+# @terreno/admin-spa
+
+Standalone Expo Router admin web SPA plus an Express plugin (`AdminSpaServeApp`) that serves the pre-built static export from a Terreno backend on the same origin.
+
+## Table of Contents
+
+- [Install](#install)
+- [Commands](#commands)
+- [Architecture](#architecture)
+- [AdminSpaServeApp](#adminspaserveapp)
+- [App config](#app-config)
+- [Serving and caching](#serving-and-caching)
+- [Mount path constraint](#mount-path-constraint)
+- [Standalone SPA vs embedded admin-frontend](#standalone-spa-vs-embedded-admin-frontend)
+
+## Install
+
+```bash
+bun add @terreno/admin-spa @terreno/api
+```
+
+`@terreno/api` is a peer dependency (TerrenoPlugin registration).
+
+## Commands
+
+From the `@terreno/admin-spa` package directory:
+
+```bash
+bun run compile      # Compile the server plugin (src/ -> src/dist)
+bun run build:web    # Expo static export into dist/
+bun run dev          # expo start --web --port 8083
+bun run test:ci      # Serve-plugin unit tests
+bun run smoke        # Smoke test over built dist/
+bun run test:e2e     # Playwright e2e over built dist/
+```
+
+## Architecture
+
+```
+admin-spa/
+  src/
+    serve.ts           # AdminSpaServeApp TerrenoPlugin
+    appConfig.ts       # AdminSpaAppConfig defaults + merge helper
+    index.ts           # Public exports
+  app/                 # Expo Router SPA (Better Auth + admin screens)
+  store/               # Redux + Better Auth client
+  dist/                # Pre-built static export (produced by build:web)
+```
+
+Boot flow in the SPA: `AppConfigGate` fetches `${basePath}/app-config.json` → `StoreProvider` builds Better Auth + Redux → `AdminGate` redirects anonymous users to `/login` and non-admins to `/forbidden`.
+
+## AdminSpaServeApp
+
+`AdminSpaServeApp` implements `TerrenoPlugin`. Register it on `TerrenoApp` alongside `AdminApp` and auth plugins:
+
+```typescript
+import {AdminSpaServeApp} from "@terreno/admin-spa";
+import {AdminApp} from "@terreno/admin-backend";
+import {BetterAuthApp, TerrenoApp} from "@terreno/api";
+
+new TerrenoApp({userModel: User})
+  .register(new BetterAuthApp({config: betterAuthConfig, userModel: User}))
+  .register(new AdminApp({models: [...]}))
+  .register(
+    new AdminSpaServeApp({
+      basePath: "/console",
+      appConfig: {brandName: "Acme Admin", providers: ["email", "google"]},
+      devProxyTarget: process.env.ADMIN_SPA_DEV_PROXY,
+    })
+  )
+  .start();
+```
+
+`example-backend` registers the plugin when `ADMIN_SPA_ENABLED=true`, with optional `ADMIN_SPA_DEV_PROXY` and `ADMIN_SPA_DIST_DIR` overrides.
+
+### AdminSpaServeOptions
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `basePath` | `"/console"` | URL prefix where the SPA is mounted. Admin API stays at `/admin`. |
+| `appConfig` | see [App config](#app-config) | Partial config merged over defaults; served at `${basePath}/app-config.json`. |
+| `distDir` | `<package>/dist` | Directory containing the pre-built static export (tests/custom builds). |
+| `devProxyTarget` | — | When set, proxy all SPA paths to a running `expo start --web` server (e.g. `http://localhost:8083`). `app-config.json` is still served by the plugin. |
+
+### Utility exports
+
+- `rewriteIndexHtml(html, basePath)` — Rewrites absolute `/_expo/` and `/assets/` refs for sub-path mounts.
+- `injectBaseGlobal(html, basePath)` — Injects `window.__ADMIN_SPA_BASE__` before `</head>`.
+- `resolveAppConfig(overrides?)` — Merge partial config with `DEFAULT_APP_CONFIG`.
+- `DEFAULT_APP_CONFIG` — Default `app-config.json` values.
+
+## App config
+
+`AdminSpaAppConfig` fields (from `appConfig.ts`):
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `brandName` | `"Terreno Admin"` | Header brand name |
+| `logoUrl` | — | Optional logo URL (absolute or relative) |
+| `primaryColor` | `"#2563EB"` | Primary brand color (hex) |
+| `providers` | `["email"]` | Login providers: `"email"`, `"google"`, `"github"`, `"apple"` |
+| `authBasePath` | `"/api/auth"` | Better Auth routes on this origin |
+| `adminApiBasePath` | `"/admin"` | Admin API base path on this origin |
+
+## Serving and caching
+
+**Production (no `devProxyTarget`):**
+
+1. `${basePath}/_expo` and `${basePath}/assets` — `express.static` with `maxAge: 365d`, `immutable: true`.
+2. `${basePath}/app-config.json` — `Cache-Control: no-store`.
+3. `${basePath}` and `${basePath}/*splat` — SPA fallback returns rewritten `index.html` with `Cache-Control: no-store`.
+
+`index.html` is read once at startup; asset paths are rewritten to `${basePath}/...` and `window.__ADMIN_SPA_BASE__` is injected for deep-link config fetches.
+
+**Development (`devProxyTarget` set):**
+
+- `${basePath}/app-config.json` served locally (no cache).
+- All other `${basePath}/*` requests proxied to the Expo dev server (WebSocket enabled).
+
+If no bundle exists at `distDir/index.html`, the plugin logs a warning suggesting `bun run --filter '@terreno/admin-spa' build:web` or `devProxyTarget`.
+
+## Mount path constraint
+
+The default web export is built with `experiments.baseUrl: "/console"`, so `basePath` must match. To mount elsewhere, rebuild with a matching base (e.g. `EXPO_BASE_URL=/admin-ui bun run build:web`) and set `basePath` accordingly. Mounting at `/` requires a root-base build and `basePath: "/"`.
+
+## Standalone SPA vs embedded admin-frontend
+
+Use **`@terreno/admin-spa`** when you want a complete admin UI served from the API process (same-origin Better Auth cookies, no separate static deploy). The backend image stays lean until you opt in by registering `AdminSpaServeApp`.
+
+Use **`@terreno/admin-frontend`** when admin screens live inside your main Expo app (e.g. `example-frontend/app/admin/*`). You bring your own routing, auth, and deploy; the package supplies reusable list/table/form components and hooks against `/admin` CRUD routes from `@terreno/admin-backend`.