@terreno/mcp 0.24.0 → 0.25.0

package/src/docs/versioned/0.24.0/implementationPlans/admin-script-runner.md

@@ -0,0 +1,107 @@
+# Admin Script Runner — Maintenance Scripts via `AdminApp`
+
+**Status:** Implemented (ships with Admin UI v2 work; documented here as its own IP)  
+**Related:** [`admin-ui-v2-django-parity.md`](./admin-ui-v2-django-parity.md) (home `scriptRunner` widget, background-task patterns)  
+**Primary packages:** `@terreno/api` (`BackgroundTask`, script types), `@terreno/admin-backend`, `@terreno/admin-frontend`, `admin-spa`, `example-backend`
+
+## Goal
+
+Let backends register **named, server-side maintenance scripts** on `AdminApp`. Admins discover them from **`GET /admin/config`** (`scripts[]`: `name` + `description` only — no code). Execution is **`POST {adminBase}/scripts/:name/run?wetRun=true|false`**, which creates a **`BackgroundTask`**, runs the `runner` async, and supports **poll** (`GET …/scripts/tasks/:id`) and **cancel** (`DELETE …/scripts/tasks/:id`). The admin UI exposes **`AdminScriptList`** + **`AdminScriptRunModal`** (dry/wet, logs, polling) and a **`scriptRunner`** home widget that deep-links to the scripts screen.
+
+## Non-Goals
+
+- Uploading or editing script source from the browser.
+- Running scripts without authentication or without **admin** (`user.admin`).
+- Replacing **`POST /admin/background-tasks`** for arbitrary job kinds — scripts are the **curated** list; background-tasks remain the generic enqueue API for config-driven actions.
+
+## Decisions
+
+| Topic | Decision |
+|-------|-----------|
+| Task storage | Reuse **`BackgroundTask`** from `@terreno/api` (`api/src/scriptRunner.ts`); `taskType` = script `name`. |
+| Dry run | Query **`wetRun=false`** → `isDryRun: true` on the task; runners interpret per app conventions (see example-backend scripts). |
+| Config surface | Only **`name`** and **`description`** in `/admin/config` — runners stay server-only. |
+| UI entry | **`AdminShell`**: nav item when `scripts.length > 0`**; **`AdminHome`**: widget id **`scriptRunner`** (often placed in **`home.slots.navGlobal`** per Django-parity layout). |
+| SPA routing | **`admin-spa`**: dedicated `app/scripts.tsx` and dynamic **`/__scripts`** under `app/[model]/index.tsx`. |
+
+## Architecture
+
+```
+Browser
+  │
+  ├─ GET /admin/config          ← includes scripts: [{ name, description }]
+  │
+  ├─ POST /admin/scripts/:name/run?wetRun=…
+  │     → 201 { taskId }        ← creates BackgroundTask, kicks async runner
+  │
+  ├─ GET  /admin/scripts/tasks/:id   ← poll status / logs / result
+  │
+  └─ DELETE /admin/scripts/tasks/:id ← cancel (running → cancelled)
+```
+
+Types: `ScriptRunner`, `ScriptContext`, `ScriptResult` in `api/src/scriptRunner.ts`.
+
+### Phase completion (all shipped)
+
+| Phase | Scope | Evidence |
+|-------|--------|----------|
+| A | Types + `BackgroundTask` | `api/src/scriptRunner.ts` |
+| B | HTTP routes + config metadata | `admin-backend/src/adminApp.ts`; `admin-backend/src/adminApp.test.ts` (run, poll, cancel, wetRun, 403/404); `adminApp.models.test.ts` (`/admin/config` includes `scripts`) |
+| C | Hooks + UI | `admin-frontend/src/useAdminScripts.ts`, `AdminScriptList.tsx`, `AdminScriptRunModal.tsx`, `AdminShell.tsx`, `AdminHome.tsx`; tests + isolated specs |
+| D | SPA + example | `admin-spa/app/scripts.tsx`, `app/[model]/index.tsx` (`__scripts`); `example-backend/src/server.ts` `scripts` |
+
+Script **run** paths are exercised in **`admin-backend` tests**; the aggregated **`openapi.json`** snapshot in **`example-backend`** documents `/admin/config` (including the `scripts` array shape) and may not list every dynamic `POST /admin/scripts/:name/run` path depending on OpenAPI aggregation — runtime behavior is still covered by admin-backend tests.
+
+## APIs (implemented)
+
+| Method | Path | Purpose |
+|--------|------|--------|
+| POST | `{basePath}/scripts/:name/run` | Start script; body empty; **`wetRun`** query boolean. |
+| GET | `{basePath}/scripts/tasks/:taskId` | Poll task document (status, progress, logs, result). |
+| DELETE | `{basePath}/scripts/tasks/:taskId` | Request cancellation. |
+
+All script routes sit behind **`authenticateMiddleware()`**; run/poll/delete require **`user.admin`** (403 otherwise). See `admin-backend/src/adminApp.ts` (`mountScriptRoutes`).
+
+## UI (implemented)
+
+| Piece | Role |
+|-------|------|
+| `useAdminScripts` | RTK-injected endpoints for run / get task / cancel. |
+| `AdminScriptRunModal` | Dry vs wet run, start, poll, show logs/results, cancel. |
+| `AdminScriptList` | Lists scripts from config; opens modal. |
+| `AdminHome` widget `scriptRunner` | Card + “Open scripts” → `__scripts` route. |
+| `AdminShell` | Sidebar “Scripts” when `config.scripts.length > 0`. |
+
+## Consumer wiring (example)
+
+`example-backend/src/server.ts` — `new AdminApp({ … scripts: [{ name, description, runner }, …] })`. Runners may use only `wetRun` or also **`ScriptContext`** (`addLog`, `updateProgress`, `checkCancellation`) for long jobs.
+
+## Files (reference)
+
+| Area | Files |
+|------|--------|
+| Types + model | `api/src/scriptRunner.ts` (`ScriptRunner`, `BackgroundTask`, …) |
+| HTTP + OpenAPI | `admin-backend/src/adminApp.ts` |
+| Tests | `admin-backend/src/adminApp.test.ts`, `admin-backend/src/adminApp.models.test.ts` (ctx script) |
+| Hooks + UI | `admin-frontend/src/useAdminScripts.ts`, `AdminScriptList.tsx`, `AdminScriptRunModal.tsx`, `AdminHome.tsx`, `AdminShell.tsx` |
+| SPA | `admin-spa/app/scripts.tsx`, `admin-spa/app/[model]/index.tsx` (`__scripts`) |
+| Example | `example-backend/src/server.ts` (`scripts` array) |
+
+## Task list
+
+Executable checklist: **`docs/tasks/admin-script-runner.md`**.
+
+## Acceptance Criteria (summary)
+
+- [x] `GET /admin/config` includes `scripts` metadata when scripts are registered; empty array when none.  
+- [x] `POST …/scripts/:name/run` returns **201** + **`taskId`** for admins; **403** non-admin; **404** unknown name.  
+- [x] `GET …/scripts/tasks/:id` exposes task state for polling; `DELETE` cancels where allowed.  
+- [x] Runners receive **`wetRun`** and optional **`ScriptContext`**; failures mark task **failed**; **`TaskCancelledError`** respected.  
+- [x] Frontend: list + modal + polling; dry vs wet surfaced to query string.  
+- [x] `scriptRunner` home widget + shell nav reach the scripts screen without embedding the list inside the wrong slot (covered with Admin Home tests + layout rules in Admin UI v2 IP).
+
+## Future / not in scope
+
+- Per-script RBAC beyond “is admin”.  
+- Streaming log output over WebSockets (polling only today).  
+- Shared quota / concurrency limits across script and background-task queues.

package/src/docs/versioned/0.24.0/implementationPlans/admin-ui-v2-django-parity.md

@@ -0,0 +1,204 @@
+# Admin UI v2 — Django-Parity Admin (Config-Driven Shell)
+
+**Status:** Implemented (phased tasks complete; acceptance criteria verified in-repo)  
+**Branch:** Landed via `cursor/admin-ui-v2-backend-a736` (PR #782)  
+**Owner:** Josh Gachnang  
+**Created:** 2026-06-15  
+**Source:** Claude Design handoff (`Admin UI v2.html`, `admin/v2/schema.jsx`, design transcripts). Design blend plan approved in-session.
+
+**Companion IP — Admin script runner:** Maintenance scripts (`AdminApp` `scripts[]`, `/admin/scripts/*`, `AdminScriptList` / `scriptRunner` widget) are specified in **`docs/implementationPlans/admin-script-runner.md`** with tasks in **`docs/tasks/admin-script-runner.md`**.
+
+## Goal
+
+Evolve Terreno’s admin stack (`@terreno/admin-backend`, `@terreno/admin-frontend`, `@terreno/admin-spa`) so a **single `/admin/config` payload** can drive a **Django-style admin**: grouped sidebar, declarative **home `slots`** (header strip, above-the-fold band, main column, sidebar — analogous to Django admin template blocks), changelist with typed filters / search / sort allowlists / pagination / bulk actions (sync + background), schema-driven forms with fieldsets and readonly enforcement, permission-gated UI (e.g. delete off), and deep links to plugin screens (document storage, AI explorer). **REST-first:** every persisted entity uses `modelRouter` CRUD; only gated custom routes for bulk jobs and config aggregation.
+
+## Non-Goals
+
+- **Pixel-perfect clone** of the HTML prototype’s inline styles — match **behavior and information architecture**, using `@terreno/ui` theming.
+- **Replacing Font Awesome in the prototype** — Terreno UI uses FA6 names via `iconName`; map icons at integration boundary.
+- **Product-specific Flourish models in core packages** — example models may live in `example-backend`; framework ships **capabilities** and **reference wiring**.
+- **SSR / SEO** for admin.
+- **Cross-tenant URL structure** — tenant scoping remains consumer-owned via permissions and query filters.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Config contract | Extend `GET /admin/config` with a **versioned** `schemaVersion` (e.g. `2`) and additive fields; preserve v1 consumers until admin-frontend major. |
+| List filters | Encode as **queryFields-compatible** filters (booleans, enums, text contains, date ranges, ref id); rail vs chips is **UI mode** only. |
+| Bulk sync actions | **`POST {basePath}{routePath}/bulk-patch`** with allowlisted patch keys, **≤ 1000** ids, OpenAPI documented. |
+| Background actions | Reuse **`BackgroundTask`** (`@terreno/api`) via **`POST /admin/background-tasks`** (or equivalent under `adminApp`) returning `taskId`; UI uses existing modal patterns (`AdminScriptRunModal` / `Modal` + progress). |
+| Autocomplete refs | **No custom search RPC** — `GET` list on referenced model with search query + small limit. |
+| Recent actions + audit | **Last phase**: optional **`AdminAuditLog`** model + list endpoint + home widget; **`recentActivity` last within the `sidebar` slot** (see home slots below). |
+| Realtime badge | **UI-only** flag from config (`realtime: true`); transport is app-level (polling/socket) out of scope for v1 framework. |
+| Home layout | **Slot-based `home.slots` (Solution A)** — mirrors Django admin template regions so tools/scripts can sit **above** the model grid without being “just another card”. See **Django layout mapping** below. |
+
+### Django layout mapping (reference)
+
+Stock Django `admin/index.html` splits the page into template **blocks**, not a flat widget list: main **`content`** is the app/model list (`app_list`); **`sidebar`** is “Recent actions” only; **`nav-global`** in `base.html` is an empty hook used for global shortcuts (e.g. scripts, reports) in the header row. Custom index pages inject markup **before** `app_list` by overriding `index_template` / `{% block content %}`. Terreno encodes the same idea in **`GET /admin/config`** as named **slots**, each an ordered list of **widget ids** resolved by a built-in + plugin registry.
+
+### `home.slots` contract (canonical)
+
+```typescript
+// Conceptual shape — exact TypeScript lives in admin-backend / shared types.
+home: {
+  title: string;
+  slots: {
+    navGlobal?: string[];   // Django nav-global analogue: compact header strip (e.g. scriptRunner shortcuts)
+    contentTop?: string[];  // Django “inject before app_list”: full-width row above model cards
+    main?: string[];        // Primary column: modelStats, modelsGrid, plugin widgets, etc.
+    sidebar?: string[];     // Django index sidebar: versionConfig, scriptRunner panel, recentActivity, …
+  };
+};
+```
+
+- **`scriptRunner`** (or any custom widget id) in **`navGlobal`** → horizontal tools, never mixed into the model card grid.
+- Same id in **`contentTop`** → prominent band **above** `main`.
+- **`recentActivity`** belongs in **`sidebar`** when used; it must be **last in `sidebar`** if present (Django keeps recent actions in the sidebar column, below other sidebar content you add).
+- Omitted slots render nothing. **`main`** default for backward compat: treat as `["modelsGrid"]` when `schemaVersion >= 2` and `slots` missing but legacy `widgets[]` exists — implementation detail for migration.
+
+## Architecture
+
+```
+Browser (admin-spa / embedded admin-frontend)
+    │
+    ├─ GET /admin/config          ← aggregated model meta + home + screens + scripts
+    │
+    ├─ CRUD  /admin/{resource}/*  ← modelRouter per registered model (IsAdmin)
+    │
+    ├─ POST /admin/{resource}/bulk-patch
+    │
+    └─ POST /admin/background-tasks  → BackgroundTask queue → progress poll/subscribe (app-defined)
+```
+
+Plugin screens (**Documents**, **AI requests**) remain **routes owned by** `@terreno/document-storage` / `@terreno/ai`; config only exposes **navigation entries** (`customScreens[]`).
+
+## Models
+
+Domain models in the prototype are **illustrative** (FeatureFlag, CompanyOrganization, DotPhrase, ExternalClinician, HealthEvent, InsurancePlan, ReferralMethod, ReferralSource, UserStatus). Implementations in consumer apps register Mongoose models with `AdminApp`. Framework work ensures **metadata** and **routers** support their shapes:
+
+| Model | Key relations | Indexes / notes |
+|-------|----------------|-----------------|
+| FeatureFlag | — | Unique `key`; query fields for list/search; hidden `evaluationCache` optional |
+| CompanyOrganization | — | Name search |
+| ExternalClinician | `organization` → CompanyOrganization | Index `organization` |
+| DotPhrase | — | `delete` permission optional **off** |
+| Others | — | Standard list/query/sort fields per config |
+
+**AdminAuditLog** (Phase last): `verb`, `modelName`, `recordLabel`, `recordId?`, `actorId`, `created`; list for home widget; optional TTL index for retention.
+
+**BackgroundTask**: use existing `@terreno/api` type used by `AdminApp` / scripts — no new model if already sufficient; document enqueue contract in OpenAPI.
+
+## APIs
+
+### CRUD (per registered model)
+
+- `POST /admin/{resource}` — create  
+- `GET /admin/{resource}` — list (pagination, sort, queryFields filters)  
+- `GET /admin/{resource}/:id` — read  
+- `PATCH /admin/{resource}/:id` — update (strip readonly server-side)  
+- `DELETE /admin/{resource}/:id` — delete or **disabled** when permissions say so  
+
+All **`Permissions.IsAdmin`** (or stricter consumer override).
+
+### Custom (Action Decision Gate — approved)
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /admin/config` | **Aggregation** of models, fields, UI hints, scripts, screens, **`home.slots`** (widget ids per region) |
+| `POST /admin/{resource}/bulk-patch` | **Command + performance**: multi-row patch, cap ids, single audit hook |
+| `POST /admin/background-tasks` | **Command**: enqueue long-running admin job tied to selection |
+
+### Rejected custom routes
+
+| Idea | Fallback |
+|------|----------|
+| Dedicated ref `/search` RPC | `GET` list + query |
+| WebSocket as “admin action” | App transport; REST remains SoT |
+
+## Notifications
+
+- **In-app only:** `@terreno/ui` **Toast** after save, bulk action, enqueue background task, script completion.  
+- **No email/push** for admin events in this IP.
+
+## UI
+
+- **Shell:** `Box` / `Page`, grouped sidebar (`Text` section headers, `Button` / `IconButton`, `Avatar`), sticky top bar with breadcrumbs (`Heading`, `Link`).  
+- **Home:** Render in order: **`navGlobal` + `contentTop` merged into one horizontal top band** (same flex row, wrapping) → two-column **`main`** + **`sidebar`** (Terreno `Box` / `SplitPage`-style layout). Each slot iterates widget ids from `home.slots`; **`recentActivity` last inside `sidebar`** when present.  
+- **List:** `DataTable`, `Pagination`, `TextField` (debounced search), filter rail (`Card` + fields) or chip mode (`SelectField` / date inputs), row selection, bulk `SelectField` + `Modal` confirms, inline boolean via PATCH.  
+- **Form:** `Accordion` or stacked `Card` for fieldsets; `TextField`, `NumberField`, `BooleanField`, `SelectField`, `DateTimeField`; readonly fields disabled + helper copy; ref picker = debounced list fetch.  
+- **Danger zone:** `Button` destructive + `Modal`; **hidden** when delete permission false.  
+- **Background run:** `Modal` + `Spinner` + log `Text` (reuse `AdminScriptRunModal` patterns).  
+- **testIDs:** `admin-home`, `admin-home-slot-top` (combined `navGlobal` + `contentTop` widgets), `admin-home-slot-main`, `admin-home-slot-sidebar`, `admin-list-{model}`, `admin-form-{model}`, `filter-{field}`, `bulk-action`, `widget-recent-activity` (last in **sidebar** slot).
+
+## Phases
+
+1. **Backend contracts** — extend config response; bulk-patch; background enqueue; OpenAPI + tests.  
+2. **CRUD parity** — ensure each registered model’s `queryFields`, sort, response stripping align with config lists.  
+3. **Frontend shell + list + form** — consume v2 config; `DataTable` list; form fieldsets/readonly/autocomplete.  
+4. **Home widgets** — registry + **`home.slots`** layout + plugin widget IDs + placement (`navGlobal` and `contentTop` render in one top row; `main` vs `sidebar`).  
+5. **admin-spa + example** — runnable demo; link plugin screens.  
+6. **Audit log & recent actions (last)** — `AdminAuditLog` model (if approved for deployment), logging hooks, `GET` list, wire **`recentActivity` as the final id in `home.slots.sidebar`**.
+
+### Phase completion (all shipped)
+
+| # | Scope | Evidence |
+|---|--------|----------|
+| 1 | Config + OpenAPI for `/admin/config` | `admin-backend/src/adminApp.models.test.ts` (`schemaVersion`, `home.slots`, scripts metadata) |
+| 2 | Bulk-patch + background-tasks | Same file + `adminApp.test.ts` |
+| 3 | Example modelRouter alignment | `example-backend/src/server.ts` registrations |
+| 4–6 | Shell, list, form | `admin-frontend` compile + `AdminModelTable.test.tsx`, `AdminModelForm.test.tsx`, `AdminBreadcrumbs.test.tsx` |
+| 7 | Home widgets + slots | `admin-frontend/src/AdminHome.test.tsx` |
+| 8 | admin-spa + example | `admin-spa/app/**`, Playwright `admin-spa/e2e/**` |
+| 9 | Audit + recent activity | `example-backend` `AdminAuditLog` + `onAdminAudit`; `admin-backend` **`AdminApp onAdminAudit`** tests (POST/PATCH/DELETE); `AdminHome.test.tsx` sidebar order |
+
+
+## Feature Flags & Migrations
+
+- **Config `schemaVersion`:** clients switch parsers/layout when `>= 2`.  
+- **No DB migration in framework packages** — consumer apps migrate their own collections.  
+- Optional **feature flag** in consumer: `ADMIN_UI_V2` to toggle layout component root (defer if unnecessary).
+
+## Activity Log & User Updates
+
+- **Deferred to final phase** so list/form/config stabilize first.  
+- On completion: admin mutations optionally write **AdminAuditLog** rows; home **Recent actions** reads latest N.  
+- User-visible copy: past tense verbs (“changed”, “added”, “deleted”) matching prototype semantics.
+
+## Not Included / Future Work
+
+- Full **realtime push** of flag changes to all clients (server fan-out).  
+- **Per-field row inline edit** beyond booleans (e.g. numeric inline).  
+- **Cross-model global search**.  
+- **Export CSV** from changelist.  
+- **Granular admin roles** beyond `IsAdmin`.
+
+## Files to Create / Modify (high level)
+
+| Area | Files (expected) |
+|------|------------------|
+| admin-backend | `src/adminApp.ts` (config shape, bulk route, background enqueue), tests |
+| admin-frontend | `AdminModelTable.tsx`, `AdminModelForm.tsx`, new layout/sidebar modules, `useAdminConfig.tsx`, types |
+| admin-spa | Router screens for home v2, list v2, form v2; SDK regen |
+| api | Only if `BackgroundTask` / OpenAPI helpers need small extensions |
+| docs | This IP + `docs/tasks/admin-ui-v2-django-parity.md` |
+
+## Task List
+
+See **`docs/tasks/admin-ui-v2-django-parity.md`** for the executable, phased checklist (audit log / recent actions **last**).
+
+**Script runner tasks** (same release train): **`docs/tasks/admin-script-runner.md`**.
+
+## Acceptance Criteria (summary)
+
+- [x] `GET /admin/config` returns v2 fields without breaking v1 layout (additive + `schemaVersion`).  
+- [x] `POST .../bulk-patch` rejects >1000 ids and unknown patch keys.  
+- [x] Background enqueue returns task id; admin UI shows progress path consistent with scripts.  
+- [x] List: search debounced; filters typed; sort allowlist enforced server-side.  
+- [x] Form: readonly fields cannot be persisted via PATCH.  
+- [x] Delete UI absent when model `delete` permission disabled.  
+- [x] Home: `home.slots` drives layout; `scriptRunner` (or custom tools) in `navGlobal` or `contentTop` never appears inside the **`main`** model grid unless also listed under `main`.  
+- [x] Home: when `recentActivity` is configured, it is **last in `slots.sidebar`**.  
+- [x] Phase last: audit entries created for configured mutations; recent widget shows data from API.
+
+Verification pointers: `admin-backend/src/adminApp.models.test.ts` (config `schemaVersion`, bulk-patch caps/allowlist, background-tasks, **`AdminApp onAdminAudit`** hooks after POST/PATCH/DELETE), `admin-frontend/src/AdminModelForm.test.tsx` (readonly PATCH body), `admin-frontend/src/AdminHome.test.tsx` (slot/widget placement + sidebar order), `example-backend` admin registration + audit model + OpenAPI snapshot.

package/src/docs/versioned/0.24.0/implementationPlans/feature-flags.md

@@ -0,0 +1,310 @@
+# Implementation Plan: Feature Flags & A/B Testing
+
+> **OpenFeature migration:** For the OpenFeature-based provider, `/flagConfiguration`, live updates, and RTK hook details, see [feature-flags-openfeature.md](./feature-flags-openfeature.md) and the task list [feature-flags-openfeature.md](../tasks/feature-flags-openfeature.md).
+
+*When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
+
+## **Models**
+
+### FeatureFlag
+
+Admin-managed feature flag definitions with targeting rules and A/B test variant configuration.
+
+```typescript
+const featureFlagSchema = new mongoose.Schema({
+  key: {
+    type: String,
+    required: true,
+    unique: true,
+    trim: true,
+    description: "Unique identifier for the flag, e.g., 'new-checkout-flow'",
+  },
+  name: {
+    type: String,
+    required: true,
+    description: "Human-readable display name",
+  },
+  description: {
+    type: String,
+    default: "",
+    description: "Explanation of what this flag controls",
+  },
+  enabled: {
+    type: Boolean,
+    default: false,
+    description: "Global kill switch — if false, flag is off for everyone",
+  },
+  type: {
+    type: String,
+    enum: ["boolean", "variant"],
+    default: "boolean",
+    description: "Boolean toggle or multi-variant A/B test",
+  },
+  variants: [{
+    key: {
+      type: String,
+      required: true,
+      description: "Variant identifier, e.g., 'control', 'variant-a'",
+    },
+    weight: {
+      type: Number,
+      required: true,
+      min: 0,
+      max: 100,
+      description: "Percentage weight for assignment (0-100, all must sum to 100)",
+    },
+  }],
+  rules: [{
+    field: {
+      type: String,
+      description: "User field to match against. Supports dot notation for nested fields, e.g., 'email', 'admin', 'address.zip'",
+    },
+    operator: {
+      type: String,
+      enum: ["eq", "neq", "in", "nin", "gt", "lt", "contains"],
+      description: "Comparison operator for field-based rules",
+    },
+    value: {
+      type: mongoose.Schema.Types.Mixed,
+      description: "Value to compare against (string, number, boolean, or array for in/nin)",
+    },
+    segment: {
+      type: String,
+      description: "Name of a registered segment function, e.g., 'pro-users'",
+    },
+    enabled: {
+      type: Boolean,
+      description: "For boolean flags: override value when rule matches",
+    },
+    variant: {
+      type: String,
+      description: "For variant flags: forced variant key when rule matches",
+    },
+  }],
+  rolloutPercentage: {
+    type: Number,
+    default: 100,
+    min: 0,
+    max: 100,
+    description: "For boolean flags with no matching rules: percentage of users who get true",
+  },
+  archived: {
+    type: Boolean,
+    default: false,
+    description: "Archived flags are excluded from evaluation. Use this instead of deleting flags to prevent bloat as new features are added.",
+  },
+}, {strict: true, toJSON: {virtuals: true}, toObject: {virtuals: true}});
+
+featureFlagSchema.plugin(createdUpdatedPlugin);
+featureFlagSchema.plugin(isDeletedPlugin);
+featureFlagSchema.plugin(findExactlyOne);
+featureFlagSchema.plugin(findOneOrNone);
+
+featureFlagSchema.index({key: 1}, {unique: true});
+featureFlagSchema.index({enabled: 1, archived: 1});
+```
+
+**Pre-save validation:** For variant-type flags, validate that `variants` is non-empty and weights sum to 100. Throw APIError if invalid.
+
+### How the Two Flag Types Work
+
+#### Boolean Flags (`type: "boolean"`)
+
+Boolean flags return `true` or `false`. They use `rolloutPercentage` to control gradual rollouts and ignore the `variants` array entirely.
+
+- **`enabled: false`** → always returns `false` for all users
+- **`enabled: true`, no matching rules** → deterministic hash of `userId + flagKey` compared against `rolloutPercentage`. At 100% (default), all users get `true`. At 50%, roughly half get `true`.
+- **Matching rule** → returns the rule's `enabled` value (`true` or `false`)
+
+Examples:
+- Feature toggle: `rolloutPercentage: 100` — on for everyone
+- Gradual rollout: `rolloutPercentage: 10` — on for ~10% of users, increase over time
+- Targeted: rule matching `admin: true` → `enabled: true`, everyone else gets the rollout percentage
+
+#### Variant Flags (`type: "variant"`)
+
+Variant flags return a string key identifying which variant the user is assigned to. They use the `variants` array with weighted distribution and ignore `rolloutPercentage`.
+
+- **`enabled: false`** → returns `null` for all users (consumers should handle this as "no experiment running")
+- **`enabled: true`, no matching rules** → deterministic hash of `userId + flagKey` mapped to variant based on cumulative weights. With `[{key: "control", weight: 50}, {key: "variant-a", weight: 50}]`, hash 0–49 = "control", 50–99 = "variant-a"
+- **Matching rule** → returns the rule's `variant` value (forced into a specific variant, bypassing the hash)
+
+The variant key is just an identifier — the consumer maps it to actual behavior in code:
+```typescript
+const variant = useVariant("checkout-experiment");
+if (variant === "control") {
+  return <OldCheckout />;
+} else if (variant === "variant-a") {
+  return <NewCheckout />;
+}
+```
+
+Deterministic hashing guarantees the same user always gets the same variant for the same flag, without storing assignments in the database.
+
+## **APIs**
+
+### FeatureFlagsApp Plugin Routes
+
+All routes mounted under configurable `basePath` (default: `/feature-flags`).
+
+#### Admin Routes (IsAdmin)
+
+| Method | Path | Type | Description |
+|--------|------|------|-------------|
+| POST | `/flags` | modelRouter | Create feature flag |
+| GET | `/flags` | modelRouter | List flags (paginated, sortable) |
+| GET | `/flags/:id` | modelRouter | Get single flag |
+| PATCH | `/flags/:id` | modelRouter | Update flag |
+| DELETE | `/flags/:id` | modelRouter | Soft-delete flag |
+| GET | `/segments` | custom | List registered segment function names |
+
+#### User Routes (IsAuthenticated)
+
+| Method | Path | Type | Description |
+|--------|------|------|-------------|
+| GET | `/evaluate` | custom | Evaluate all enabled flags for current user |
+
+**`GET /evaluate` response:**
+```json
+{
+  "data": {
+    "new-checkout-flow": true,
+    "checkout-experiment": "variant-a",
+    "dark-mode": false
+  }
+}
+```
+
+**`GET /segments` response:**
+```json
+{
+  "data": ["pro-users", "beta-testers", "high-usage", "internal-team"]
+}
+```
+
+### Plugin Constructor
+
+```typescript
+interface FeatureFlagsOptions {
+  basePath?: string;                              // Default: "/feature-flags"
+  segments?: Record<string, (user: any) => boolean>;  // Named segment functions
+}
+
+class FeatureFlagsApp implements TerrenoPlugin {
+  constructor(options?: FeatureFlagsOptions);
+  register(app: express.Application): void;
+}
+```
+
+### Evaluation Logic
+
+Evaluation is a **pure read** — no database writes occur during flag evaluation.
+
+1. Fetch all enabled, non-archived FeatureFlags (`{enabled: true, archived: false}`)
+2. For each flag, evaluate `rules` in order:
+   - **Field rule:** Access `user[rule.field]` using dot notation (e.g., `lodash.get(user, rule.field)`) and compare against `rule.value` using `rule.operator`
+   - **Segment rule:** Call `segments[rule.segment](user)` — match if returns true; log warning if segment not found
+   - First matching rule → return `rule.enabled` (boolean) or `rule.variant` (variant)
+3. If no rules match, use **deterministic hashing** (`hash(userId + flagKey) % 100`):
+   - **Boolean flags:** Compare hash against `rolloutPercentage` — if hash < rolloutPercentage, return `true`
+   - **Variant flags:** Map hash to variant based on cumulative weights. E.g., variants `[{key: "control", weight: 50}, {key: "variant-a", weight: 30}, {key: "variant-b", weight: 20}]` → hash 0–49 = "control", 50–79 = "variant-a", 80–99 = "variant-b"
+4. If flag is disabled: return `false` for boolean, `null` for variant
+
+### Consumer Registration
+
+```typescript
+// In consumer's server.ts
+const segments = {
+  "pro-users": (user) => user.plan === "pro",
+  "beta-testers": (user) => user.betaTester === true,
+  "high-usage": (user) => user.totalActions > 1000,
+  "internal-team": (user) => user.email?.endsWith("@mycompany.com"),
+};
+
+new TerrenoApp({userModel: User})
+  .register(new FeatureFlagsApp({ segments }))
+  .register(new AdminApp({
+    models: [
+      {
+        model: FeatureFlag,
+        routePath: "/feature-flags",
+        displayName: "Feature Flags",
+        listFields: ["key", "name", "type", "enabled", "archived", "created"],
+      },
+    ],
+  }))
+  .start();
+```
+
+## **Notifications**
+
+None needed.
+
+## **UI**
+
+No new dedicated screens. Feature flags are managed through the existing AdminApp generic form by registering the FeatureFlag model.
+
+For rule targeting values that reference users, the AdminApp form treats `_id`,
+`id`, `userId`, `ownerId`, and related user fields as User refs. Single-user
+operators (`eq`, `neq`, `$eq`, `$ne`) render a User picker, and multi-user
+operators (`in`, `nin`, `$in`, `$nin`) render an array of User pickers.
+Selected users should display through the configured User ref renderer or
+picker label, so admins see user names or emails rather than raw IDs when
+editing rules.
+
+### Frontend Hook (`@terreno/rtk`)
+
+```typescript
+// useFeatureFlags.ts — new file in @terreno/rtk
+export const useFeatureFlags = (api: Api<any, any, any, any>, basePath = "/feature-flags") => {
+  // Injects GET /feature-flags/evaluate endpoint
+  // Returns { useFlag, useVariant, isLoading, error, refetch }
+};
+
+// Consumer usage
+const { useFlag, useVariant } = useFeatureFlags(terrenoApi);
+
+const showNewCheckout = useFlag("new-checkout-flow");       // true | false
+const variant = useVariant("checkout-experiment");           // "control" | "variant-a" | null
+```
+
+Fetches once on mount, caches via RTK Query, refetches on window focus.
+
+## Phases
+
+### Phase 1: Backend package + evaluation engine
+- Create `feature-flags/` package directory with package.json, tsconfig
+- Implement FeatureFlag model (with archived field)
+- Implement FeatureFlagsApp plugin with modelRouter CRUD
+- Implement evaluation engine (field rules with dot notation, segment rules, deterministic hashing for both boolean rollout and variant assignment)
+- Implement `/evaluate`, `/segments` custom endpoints
+- Unit tests for evaluation logic
+
+### Phase 2: Frontend hook
+- Add `useFeatureFlags()` hook to `@terreno/rtk`
+- Export from rtk index
+
+### Phase 3: Example app integration
+- Wire up FeatureFlagsApp in example-backend
+- Register models in AdminApp
+- Add sample flags and use `useFeatureFlags()` in example-frontend
+- Regenerate SDK
+
+## Feature Flags & Migrations
+
+No feature flag needed for this feature itself — it's a new package with no existing behavior to gate. No data migrations required.
+
+## Activity Log & User Updates
+
+None needed.
+
+## **Not included/Future work**
+
+- Real-time flag updates via WebSocket (polling/refetch-on-focus only for v1)
+- A/B test analytics or conversion tracking (consumers use their own analytics system)
+- Custom admin UI for targeting rule editing (generic form only; consumers can extend)
+- Async segment functions (sync only for v1; can be added if DB-lookup segments are needed)
+- Flag scheduling (enable/disable at a future date)
+- Mutual exclusion groups for experiments
+- Flag audit log (who changed what, when)
+- Flag environments (dev/staging/prod)