@terreno/mcp 57.3.0 → 57.6.0

package/src/docs/versioned/next/implementationPlans/datatable-server-side-filtering.md

@@ -0,0 +1,219 @@
+# Implementation Plan: DataTable server-side filtering and search
+
+**Status:** Approved  
+**Branch:** `cursor/datatable-server-side-filtering-191d`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1177 (this feature **closes** that issue; implementation PRs use `Fixes #1177`)  
+**Task list:** [datatable-server-side-filtering.md](../tasks/datatable-server-side-filtering.md)  
+**Depends on:** —  
+**RTK deprecation flag:** Partial — `@terreno/ui` stays data-layer agnostic; AdminModelTable keeps RTK `useListQuery`; syncdb is out of scope  
+
+## Goal
+
+`DataTable` grows optional, controlled filter and search chrome that emits a JavaScript object of [modelRouter](../how-to/create-a-model.md) list params (`queryFields` equality, nested `$in` / `$regex` / `$gte`/`$lte`, date `field_gte`/`field_lte`, search `$or`). Parents pass that object to RTK, `fetch`, or any client. `AdminModelTable` uses the same UI and drops `AdminFilterDrawer`.
+
+## Non-Goals
+
+- Changing modelRouter list semantics or adding a new list query language.
+- Changing admin `q` / `buildAdminPartialSearchFilter` (ObjectId match stays on the backend).
+- Client-side filtering of the `data` prop.
+- Nested `$and`/`$or` query-builder UI.
+- Multi-select `$in` on admin `ref` (single ObjectId only).
+- Syncdb `useQuery` list wiring.
+- Making `Filter` itself universal (native uses a `Modal` sheet).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Emission | Presentational `onQueryChange(params)` JS object. Page/sort stay the existing callbacks. Parent merges. |
+| Operators | Text contains (`$regex` + `$options: "i"`, escaped); boolean equality; date `field_gte`/`field_lte`; number `{field: {$gte,$lte}}`; choice multi-select `{field: {$in: values}}`. |
+| Search | Generic: `$or` of escaped `$regex` on caller `searchFields`. Admin: toolbar string → `q` only (do not send `$or`; parser rejects top-level operators). |
+| Admin chrome | One surface: DataTable search + column filters. Remove `AdminFilterDrawer`. `ref` uses column `renderFilter`. |
+| Native | One “Filters” `Modal`/`ActionSheet` with every column filter + search. Web: per-column `Filter` popovers. |
+| Control | Filter/search state is controlled like `page` / `sortColumn`. Search debounce matches admin (existing delay). |
+| Admin parser | Extend `parseAdminListFilters` for choice `$in` (allowed values only) and text `{ $regex, $options: "i" }`. Keep rejecting undeclared `$or`. |
+
+## Architecture
+
+```
+DataTable (optional filter/search props)
+  web: header Filter popover per filterable column
+  native: one Filters sheet
+  → buildDataTableListQuery(state) → onQueryChange(params)
+
+Parent
+  generic modelRouter: pass params to list GET (qs.stringify nested ops)
+  AdminModelTable: strip $or; set q from search; keep $in / ranges / equality; RTK useListQuery
+```
+
+`@terreno/ui` must not import RTK, admin, or axios. Export `buildDataTableListQuery` and filter types next to DataTable.
+
+### Public types (sketch)
+
+```typescript
+interface DataTableColumnFilterChoiceOption {
+  label: string;
+  value: string;
+}
+
+interface DataTableColumnFilter {
+  field: string;
+  kind: "text" | "boolean" | "numberRange" | "dateRange" | "choice";
+  options?: DataTableColumnFilterChoiceOption[]; // choice
+  renderFilter?: (args: {
+    field: string;
+    value: unknown;
+    onChange: (value: unknown) => void;
+  }) => React.ReactNode;
+}
+
+interface DataTableQueryParams {
+  [field: string]: unknown;
+  $or?: Array<Record<string, unknown>>;
+}
+
+interface DataTableProps {
+  // existing page / sort / data ...
+  search?: string;
+  searchFields?: string[];
+  onSearchChange?: (search: string) => void;
+  filterValues?: Record<string, unknown>;
+  onFilterValuesChange?: (next: Record<string, unknown>) => void;
+  onQueryChange?: (params: DataTableQueryParams) => void;
+}
+```
+
+`DataTableColumn` gains optional `filter?: DataTableColumnFilter`. Omit `filter` → no column control (today’s table). Omit search props → no search box.
+
+`onQueryChange` fires when search (debounced) or filters change. It does **not** include `page`, `limit`, or `sort`.
+
+### Query object contract
+
+| UI | Wire |
+|----|------|
+| Search (generic) | `$or: [{field: {$regex: escaped, $options: "i"}}, ...]` for `searchFields` |
+| Text column | `{field: {$regex: escaped, $options: "i"}}` |
+| Boolean | `{field: true \| false}`; unset omits the key |
+| Date range | `field_gte` / `field_lte` ISO strings (modelRouter Date merge) |
+| Number range | `{field: {$gte?: number, $lte?: number}}` |
+| Choice (one or many) | `{field: {$in: string[]}}` even for a single value |
+| Empty filter | key omitted |
+
+Escape every user regex with the same rules as `escapeRegexLiteral` in `admin-backend/src/adminTextSearch.ts` (copy into ui; do not import admin-backend).
+
+### Native vs web
+
+| Platform | Chrome |
+|----------|--------|
+| Web | Toolbar `TextField` search; per-column header icon opens existing `Filter` (Apply/Clear). Choice uses `MultiselectField`. |
+| Native | Toolbar search + one “Filters” control opening `Modal` (or existing mobile sheet pattern from admin: `ADMIN_FILTER_MOBILE_BREAKPOINT`). Same `filterValues` / `onQueryChange`. |
+
+### Admin adoption
+
+`AdminModelTable` maps `modelConfig.filters` onto `DataTableColumn.filter`:
+
+| Admin kind | DataTable kind |
+|------------|----------------|
+| `text` | `text` (contains; documented behavior change from exact match) |
+| `boolean` | `boolean` |
+| `dateRange` | `dateRange` |
+| `choice` | `choice` + `options` from `choices` |
+| `ref` | `choice`-shaped slot with `renderFilter` wrapping `AdminRefField` (single id) |
+
+`buildAdminListQueryParams` consumes DataTable state:
+
+1. Copy filter params except `$or`.
+2. If `searchFields.length && search.trim()`, set `q`.
+3. Keep `limit`, `page`, `sort`.
+
+Delete `AdminFilterDrawer` usage from the table. Keep the module only if another screen still imports it; otherwise remove export after table tests prove the new path.
+
+`parseAdminListFilters` today rejects objects on choice/text and any top-level `$` key. This slice:
+
+- Parses `role: { $in: ["staff", "admin"] }` when every value is in `choices`.
+- Parses text `{ $regex: string, $options: "i" }` (regex already escaped by the client).
+- Still errors on top-level `$or` / `$and`.
+
+### Compatibility
+
+Existing `DataTable` callers with no filter/search props are unchanged (no chrome, no callbacks).
+
+## Models
+
+None.
+
+## APIs
+
+No new HTTP routes. Consumers keep `GET` list with existing `queryFields`. Admin list still uses `q` for search.
+
+## Notifications
+
+None.
+
+## UI
+
+Demo story: filterable columns + search, mock `onQueryChange` log / JSON. Admin SPA / example admin: Todos or Users list — search, boolean, choice `$in`, date range, ref via custom renderer.
+
+## Phases
+
+1. **Tracer:** query helper + DataTable tests (no fetch).
+2. **Chrome:** web popovers + native sheet + demo story.
+3. **Admin parser + table:** `$in` / text regex; drop drawer.
+4. **Docs:** reference, how-to, seed links, generated component props.
+
+## Feature Flags & Migrations
+
+No flag. Admin text filters become contains. Call out in CHANGELOG and admin how-to.
+
+## Activity Log & User Updates
+
+- 2026-09-10: Grow approved; next Pick Task 1.1.
+
+## Not Included / Future Work
+
+- Multi-select `$in` on `ref`.
+- Client-side filter of `data`.
+- Nested boolean query builder.
+- Universal `Filter` popover on native.
+- Syncdb collection queries.
+
+## Files to Create / Modify
+
+| Path | Change |
+|------|--------|
+| `ui/src/Common.ts` | Filter types on `DataTableColumn` / `DataTableProps` |
+| `ui/src/dataTableListQuery.ts` (new) | `buildDataTableListQuery`, regex escape |
+| `ui/src/DataTable.tsx` | Search + column filters + native sheet |
+| `ui/src/DataTable.test.tsx` | Query emission tests |
+| `demo/stories/DataTable.stories.tsx` | Filter/search demo |
+| `admin-backend/src/filterParser.ts` | Choice `$in`, text `$regex` |
+| `admin-backend/src/filterParser.test.ts` | New cases |
+| `admin-frontend/src/AdminModelTable.tsx` | Wire DataTable; remove drawer |
+| `admin-frontend/src/adminModelListQueryParams.ts` | Map search → `q`; pass `$in` |
+| `admin-frontend/src/AdminFilterDrawer.tsx` | Remove if unused |
+| `docs/reference/ui.md` | DataTable filter contract |
+| `docs/how-to/admin-add-model.md` | Filters live on the table; text is contains |
+| `docs/reference/admin-frontend.md` | AdminModelTable |
+| `docs/explanation/admin-interface.md` | Drop drawer as the list filter UI |
+| `docs/explanation/roadmap-seed-issues.md` | IP/task links |
+| `CHANGELOG.md` | Added |
+
+Generated `docs/reference/components/` DataTable props via `ui` `bun run types` / `website:generate` in the docs task.
+
+## Task List
+
+[datatable-server-side-filtering.md](../tasks/datatable-server-side-filtering.md)
+
+## Acceptance Criteria
+
+- [ ] DataTable with no filter/search props matches current sort/page-only UI (unit test).
+- [ ] `buildDataTableListQuery` emits escaped `$regex` `$or` for search and `{field: {$in}}` for multi choice (`bun test ui/src/dataTableListQuery.test.ts` or colocated).
+- [ ] Interacting with web column Filter Apply calls `onQueryChange` with the contract table (`DataTable.test.tsx`).
+- [ ] Native “Filters” sheet applies the same object (`DataTable.test.tsx` with platform mock or sheet testIDs).
+- [ ] Admin list: search still hits `q`; choice multi-select reaches Mongo `$in`; `parseAdminListFilters` rejects top-level `$or` (`filterParser.test.ts` + `AdminModelTable.test.tsx`).
+- [ ] `AdminFilterDrawer` is not rendered on `AdminModelTable`.
+- [ ] Demo story shows search + at least text, boolean, date, and choice filters.
+- [ ] Docs: `docs/reference/ui.md`, admin how-to/reference, generated component props, CHANGELOG.
+- [ ] `bun run analyze:full` clean; frontend verification per `verify-ui-changes` (demo + admin list).

package/src/docs/versioned/next/implementationPlans/deploy-to-gcp.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Deploy to GCP (Generalized) + `deploy-gcp` Skill
 
 **Status:** Approved — decisions recorded (2026-07-29)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1005
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1005
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/deploy-to-vercel.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Deploy to Vercel + `deploy-vercel` Skill
 
 **Status:** Approved — open Vercel spike TODOs; other decisions recorded (2026-07-29)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1012
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1012
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/deployment-foundation.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Deployment Foundation
 
 **Status:** Complete — blocking questions resolved 2026-07-29; all tasks executed
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1011
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1011
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned
@@ -62,7 +62,7 @@ Expo Router offers three, and the choice determines what hosting works:
 | `static` | per-route HTML | no | no | any static host | usable now; better SEO |
 | `server` | `dist/client` + `dist/server` | yes | yes (alpha, SDK ≥ 55) | needs a Node/Bun/edge runtime | not yet — see the SSR IP |
 
-The repo is currently on Expo `~54.0.29` (root `package.json` catalog), so `server` output with SSR requires the SDK upgrade tracked in PR [#779](https://github.com/flourishhealth/terreno/pull/779). The foundation doc must state this rather than implying SSR is available.
+The repo is currently on Expo `~54.0.29` (root `package.json` catalog), so `server` output with SSR requires the SDK upgrade tracked in PR [#779](https://github.com/TerrenoLabs/terreno/pull/779). The foundation doc must state this rather than implying SSR is available.
 
 ### Backend container
 

package/src/docs/versioned/next/implementationPlans/design-blend-skill.md

@@ -1,6 +1,6 @@
 # Implementation Plan: design-blend Skill
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1083  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1083  
 **Status:** Complete
 
 ## Goal

package/src/docs/versioned/next/implementationPlans/docs-reference-coverage.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Reference Documentation Coverage
 
 **Status:** In progress — remaining README, sanitization, and docs-audit work
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1009
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1009
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/docs-site-and-versioning.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Documentation Site, Versioned Docs, and Docs-Maintenance Skills
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1086  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1086  
 **Status:** Approved
 
 *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.*

package/src/docs/versioned/next/implementationPlans/docs-tutorials-ai-first.md

@@ -1,7 +1,7 @@
 # Implementation Plan: AI-First Tutorials
 
 **Status:** Approved
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1010
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1010
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/examples-demo-coverage.md

@@ -1,7 +1,7 @@
 # Implementation Plan: Examples, Demo, and Test Coverage
 
 **Status:** Approved — key decisions recorded (2026-07-29)
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1016
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1016
 **Priority:** Medium
 **Effort:** Big batch
 **Owner:** unassigned
@@ -86,15 +86,15 @@ The repo states that `example-frontend` and `example-backend` serve as documenta
 | Admin panel (embedded) | yes | yes | — |
 | Admin SPA | yes | n/a | — |
 | AI streaming chat | yes | yes | — |
-| AI structured output | ? | ? | verify |
+| AI structured output | no | no | **gap** — chat streaming only; see [example-coverage.md](../explanation/example-coverage.md) |
 | Feature flags + live updates | yes | yes | — |
 | Websockets / realtime | yes | yes | — |
 | Consent forms | yes | yes | — |
 | File upload / GCS | yes | yes | — |
-| Better Auth | ? | ? | verify |
-| syncdb local-first | (from #869) | (from #869) | verify after merge |
-| RBAC | no | no | not shipped |
-| Background jobs | no | no | not shipped |
+| Better Auth | yes | yes | — |
+| syncdb local-first | yes | yes | shipped in examples; #869 closed |
+| RBAC | yes | yes | shipped; see [rbac-permissions.md](rbac-permissions.md) |
+| Background jobs | no | no | **gap** — no generic queue example |
 
 Every `?` must be resolved by reading the example source, and every real gap either filled or recorded as a known gap.
 
@@ -149,15 +149,15 @@ See [`docs/tasks/examples-demo-coverage.md`](../tasks/examples-demo-coverage.md)
 
 ## Acceptance Criteria
 
-- [ ] Every component exported from `ui/src/index.tsx` has a demo story or an allowlist entry with a stated reason.
-- [ ] `bun run scripts/check-demo-coverage.ts` fails when a newly exported component has no story and no allowlist entry, and runs in `ui-demo-ci.yml`.
-- [ ] `demo/package.json`'s `test:ci` runs something real.
-- [ ] Stories exist for all P0 components, each showing multiple states (default, loading, error, disabled) where applicable.
-- [ ] Every published package's CI runs `scripts/check-coverage.ts` at the 95% threshold.
-- [ ] Packages currently below 95% have a tracked catch-up plan; no package is permanently exempt.
-- [ ] Every published package is covered by CI running its tests and coverage check, either through a dedicated workflow or the matrix job.
-- [ ] Codecov receives uploads from every package's CI and reports per-PR deltas.
-- [ ] `README.md` shows a coverage badge that reflects reality.
-- [ ] `docs/explanation/example-coverage.md` resolves every `?` in the capability matrix, and each real gap is either filled with an example or recorded as a known gap with an issue link.
-- [ ] `CONTRIBUTING.md` states the 95% coverage expectation and how to run coverage locally per package.
-- [ ] `bun run lint`, `bun run compile`, and the full test suite pass.
+- [x] Every component exported from `ui/src/index.tsx` has a demo story or an allowlist entry with a stated reason.
+- [x] `bun run scripts/check-demo-coverage.ts` fails when a newly exported component has no story and no allowlist entry, and runs in `ui-demo-ci.yml`.
+- [x] `demo/package.json`'s `test:ci` runs something real.
+- [x] Stories exist for all P0 components, each showing multiple states (default, loading, error, disabled) where applicable.
+- [x] Every published package's CI runs `scripts/check-coverage.ts` at the 95% threshold.
+- [x] Packages currently below 95% have a tracked catch-up plan; no package is permanently exempt.
+- [x] Every published package is covered by CI running its tests and coverage check, either through a dedicated workflow or the matrix job.
+- [x] Codecov receives uploads from every package's CI and reports per-PR deltas.
+- [x] `README.md` shows a coverage badge that reflects reality.
+- [x] `docs/explanation/example-coverage.md` resolves every `?` in the capability matrix, and each real gap is either filled with an example or recorded as a known gap with an issue link.
+- [x] `CONTRIBUTING.md` states the 95% coverage expectation and how to run coverage locally per package.
+- [x] `bun run lint`, `bun run compile`, and the full test suite pass.

package/src/docs/versioned/next/implementationPlans/feature-flags-openfeature.md

@@ -1,6 +1,6 @@
 # Implementation Plan: OpenFeature Adoption for `@terreno/feature-flags`
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1082  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1082  
 **Status:** Complete
 
 ## Goal

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

@@ -2,7 +2,7 @@
 
 **Status:** Deferred
 **Closed:** 2026-08-20 — Superseded by [feature-flags-openfeature.md](./feature-flags-openfeature.md) (OpenFeature provider, live updates). This document is retained for historical context only.
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1098
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1098
 
 > **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).
 

package/src/docs/versioned/next/implementationPlans/framework-audit-log.md

@@ -0,0 +1,247 @@
+# Implementation Plan: Framework-level audit log
+
+**Status:** Approved  
+**Branch:** `cursor/framework-audit-log-grow-0d6c`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1186 (implementation PRs use `Fixes #1186`)  
+**Task list:** [framework-audit-log.md](../tasks/framework-audit-log.md)  
+**Program:** [B2B platform](b2b-platform-program.md)  
+**Depends on:** — (soft: `organizationId` now; org-admin list filter waits on [org-management-ui](org-management-ui.md))  
+**RTK deprecation flag:** None — admin viewer uses generated OpenAPI / `useAdminApi`, not syncdb  
+
+## Goal
+
+Opt-in `AuditApp` in `@terreno/api` persists append-only `AuditEvent` rows for successful mutations: who changed which record, with changed-field before/after diffs. The existing admin Platform **Audit Log** lists them. Default retention is forever. This is the B2B compliance log; it generalizes example `AdminAuditLog` without replacing consent `ConsentResponse` rows.
+
+## Non-Goals
+
+- Waiting on `org-management-ui` to start (no `OrgsApp` in tree today).
+- Default-on `modelRouter` product CRUD.
+- Consent signing history (`ConsentResponse` + `GET /consents/audit/:userId` stay).
+- Login, failed auth, permission denials (except existing `RbacAudit` `denied: true` fanned through `auditSink`).
+- Sync mutate / outbox / socket writes (`@terreno/syncdb`). HTTP `modelRouter` only.
+- Admin hard-delete of events; SIEM export; legal hold.
+- Full-document snapshots.
+- Per-org-admin filtered lists (store `organizationId` now; filter when org context ships).
+
+## Decisions
+
+| ID | Question | Choice |
+| --- | --- | --- |
+| Q1 | Org dependency | Ship now. Optional `organizationId` from the mutated document or `req.organization` when present. |
+| Q2 | Default on | Off. `AuditApp` plugin + per-router `audit: true`. **AdminApp writes `AuditEvent` automatically when `AuditApp` is registered.** |
+| Q3 | Events | Successful create/update/delete and array mutations on audited routers; AdminApp → same collection; RBAC via existing `auditSink`; consent stays domain-specific. |
+| Q4 | Mutability / retention | HTTP list+read only. Create only via framework writers. No PATCH/DELETE. **Default retain forever.** Optional `retentionDays > 0` Mongo TTL. |
+| Q5 | Diffs | Changed fields only. Auto-redact `password`, `hash`, `salt`, `token`, `secret`, `refreshToken` (case-insensitive last path segment) plus per-router `redact`. Never log full request bodies. |
+
+**Recorded assumptions (not grilled):** No default-connection singleton (same as `RbacAudit`: `createAuditEventModel(connection)`). Example-backend **replaces** `AdminAuditLog` with `AuditEvent`. `onAdminAudit` remains an extra sink. Writes are best-effort (`logger.error`, mutation still succeeds). Persist is fire-and-forget on the request path. Optional Cloud Tasks enqueue (`GCP_TASKS_AUDIT_QUEUE` + `AUDIT_TASKS_URL`) writes Mongo on a worker via `POST /internal/audit-events`. `AuditEvent` is never audited. `audit: true` without `AuditApp` skips the write and logs an error once per process. Array mutations use `verb: "updated"` and `operation` `arrayPush` / `arrayUpdate` / `arrayRemove`. `organizationId` is stored as string. Admin list uses `Permissions.IsAdmin` until org RBAC lands.
+
+## Architecture
+
+```
+AuditApp({retentionDays?})
+  → createAuditEventModel(connection)
+  → set process recorder
+  → modelRouter("/audit-events", AuditEvent, {create/update/delete: [], list/read: IsAdmin})
+  → adminContribution() for Platform Audit Log
+
+modelRouter(..., {audit: true | {redact?: string[]}})
+  → after successful create/update/delete/array *
+  → recordAuditEvent({actorId, modelName, recordId, recordLabel?, organizationId?, verb, operation, before, after, source: "modelRouter"})
+
+AdminApp
+  → after successful admin CRUD, if recorder present
+  → recordAuditEvent({..., source: "admin"})
+  → then onAdminAudit? (unchanged extra sink)
+
+createAccess({auditSink: persistRbacAuditToAuditEvent})
+  → source: "rbac"; before/after from permissionDelta when present
+```
+
+`AuditApp` implements `TerrenoPlugin` (+ `adminContribution` like FeatureFlags). Importing `@terreno/api` does **not** register `AuditEvent` on `mongoose.connection`.
+
+### Config shape
+
+```typescript
+interface AuditAppOptions {
+  enqueue?: (write: AuditEventWrite) => Promise<void>;
+  processQueuePath?: string;
+  processQueueSecret?: string;
+  /** Mongo TTL in days. Omit or 0 = forever (no TTL index). */
+  retentionDays?: number;
+}
+
+interface ModelRouterAuditOptions {
+  redact?: string[]; // extra field names; merged with defaults
+}
+
+// modelRouter options:
+audit?: boolean | ModelRouterAuditOptions;
+```
+
+`audit: true` equals `{redact: []}`.
+
+### Writer contract
+
+```typescript
+interface AuditEventWrite {
+  actorId?: string;
+  after?: Record<string, unknown>;
+  before?: Record<string, unknown>;
+  modelName: string;
+  operation: "create" | "update" | "delete" | "arrayPush" | "arrayUpdate" | "arrayRemove";
+  organizationId?: string;
+  recordId?: string;
+  recordLabel?: string;
+  source: "admin" | "modelRouter" | "rbac";
+  verb: "created" | "deleted" | "updated";
+}
+```
+
+Diff helper: shallow (plus one-level nested objects) comparison of previous JSON vs next JSON after redaction. Unchanged keys omitted. Create: `before` omitted, `after` is redacted new fields. Delete: `after` omitted, `before` is redacted last state.
+
+`organizationId` resolution order: `req.organization?.id` / `_id`, else string of `doc.organizationId` when present.
+
+## Models
+
+`AuditEvent` (collection `auditevents`):
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `actorId` | ObjectId, ref User, indexed | Optional (system / missing user) |
+| `modelName` | string, required, indexed | |
+| `recordId` | string, indexed | |
+| `recordLabel` | string | Short label (admin list fields / `title` / `name` / `email`) |
+| `organizationId` | string, indexed | Optional |
+| `verb` | `created` \| `updated` \| `deleted`, indexed | Widget-compatible |
+| `operation` | string, required | Fine-grained verb |
+| `source` | `admin` \| `modelRouter` \| `rbac`, indexed | |
+| `before` / `after` | Mixed | Changed fields only, redacted |
+| `created` / `updated` | dates | `createdUpdatedPlugin`; no `isDeletedPlugin` (append-only) |
+
+Indexes: `{created: -1}`, `{modelName: 1, recordId: 1, created: -1}`. Optional TTL on `created` when `retentionDays > 0`. Every field has `description`. Five-type pattern co-located with the schema. `strict: "throw"`.
+
+HTTP: `create`/`update`/`delete` empty permission arrays. No public POST/PATCH/DELETE even for admins. Denied list/create (including non-admin GET list) returns **405**, matching `permissionMiddleware`; instance-level denials after a loaded document remain **403**.
+
+## APIs
+
+| Method | Path | Who | Behavior |
+| --- | --- | --- | --- |
+| GET | `/audit-events` | IsAdmin | Paginated list, default sort `-created`, `queryFields`: `modelName`, `recordId`, `actorId`, `verb`, `source`, `organizationId` |
+| GET | `/audit-events/:id` | IsAdmin | Read one |
+| POST/PATCH/DELETE | `/audit-events` | — | Disabled |
+
+Admin mounts the same model via `adminContribution` (or example registers it once — do **not** double-mount). Route path includes `audit-log` **or** model name `AuditEvent` so `AdminShell.isAuditLogModel` lifts it into Platform.
+
+RBAC helper `persistRbacAuditToAuditEvent(model)` returns an `RbacAuditSink`. Built-in `RbacAudit` collection unchanged.
+
+## Notifications
+
+None.
+
+## UI
+
+Reuse Platform Audit Log + `RecentActivityWidget`. Update `isAuditLogModel` to match `AuditEvent` (keep `AdminAuditLog` and `audit-log` path for leftover apps). List columns: `created`, `verb`, `modelName`, `recordLabel`, `actorId`. Detail form is read-only; show `before`/`after` as JSON (existing object field rendering is enough). No new custom screen.
+
+example-backend: register `AuditApp`, enable `audit: true` on `Todo`, drop `AdminAuditLog` model and `onAdminAudit` persistence (optional `onAdminAudit` may remain no-op or be removed). Point home `recentActivity` at `AuditEvent`. RBAC `auditSink` uses the helper. Scripts that count/wipe `AdminAuditLog` switch to `AuditEvent` (wipe only in test/dev scripts — production HTTP still cannot delete).
+
+## Docs in this slice
+
+| Page | Change |
+| --- | --- |
+| `docs/how-to/audit-log.md` | **New.** Enable `AuditApp`, per-router `audit`, AdminApp auto-write, redaction, TTL, append-only, org field. |
+| `docs/reference/api.md` | `AuditApp`, `audit` option, `persistRbacAuditToAuditEvent`, no default-connection model. |
+| `docs/explanation/admin-interface.md` | Platform Audit Log is `AuditEvent` when `AuditApp` is registered. |
+| `docs/reference/admin-backend.md` | `onAdminAudit` is extra; framework write when `AuditApp` present. |
+| `docs/explanation/roadmap-seed-issues.md` | IP + task URLs; soft org depend. |
+| `docs/implementationPlans/b2b-platform-program.md` | Row for this IP. |
+| `.rulesync/rules/api/00-api.mdc` | AuditApp + `audit` option. |
+| `CHANGELOG.md` | Added opt-in framework audit log. |
+
+## Testing
+
+Tracer: `TerrenoApp` + `AuditApp` + test model with `audit: true` → authenticated PATCH changes `title` → `GET /audit-events` as admin returns one row with `verb: "updated"`, `before.title` / `after.title`, no `password` if present.
+
+Cases:
+
+- Plugin omitted: `audit: true` does not throw on CRUD; no collection on default connection; error logged once.
+- Create/update/delete each write one event; actorId matches `req.user`.
+- Unchanged fields absent from `before`/`after`.
+- Default redact list strips secrets even if not in `redact`.
+- Per-router `redact: ["ssn"]` strips `ssn`.
+- Array push writes `operation: "arrayPush"`, `verb: "updated"`.
+- Admin POST writes `source: "admin"` without `onAdminAudit`.
+- `onAdminAudit` still fires when both configured; mutation 201 if either sink throws.
+- AuditEvent HTTP POST is 404/not registered; PATCH/DELETE disabled.
+- `organizationId` copied from document; from `req.organization` when set.
+- `retentionDays` omitted: no TTL index. `retentionDays: 1`: TTL index present (assert index spec; do not sleep a day).
+- Example RBAC role change fans into `AuditEvent` with `source: "rbac"`.
+- Existing `onAdminAudit` tests stay green (best-effort extra sink).
+- Admin frontend: `isAuditLogModel` true for `AuditEvent`; Recent Activity still skips when no audit model.
+
+Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env` (if tests touch env), `building-admin-interfaces`, `verify-ui-changes` (example `/admin` audit log after Todo/admin mutation), `update-docs`, `generate-sdk` if example OpenAPI admin SDK lists the new route.
+
+## Risks
+
+| Risk | Mitigation |
+| --- | --- |
+| Write volume / PII | Opt-in per router; redaction; append-only HTTP. |
+| Missing plugin | No-op + once-per-process error; docs. |
+| Example `AdminAuditLog` break | Replace in the same slice; shell still matches old name. |
+| TTL index change later | How-to: drop old TTL index when changing `retentionDays`. |
+| Sync bypass | Documented non-goal; follow-up IP. |
+| Org filter incomplete | Field stored; list filter is `org-management-ui`. |
+
+## Phases
+
+1. Tracer: model + `AuditApp` + `audit: true` create/update/delete + list/read API + redaction.
+2. Array mutations + `organizationId`.
+3. AdminApp auto-write + example migration + shell matcher + RBAC helper.
+4. Optional TTL.
+5. Docs, changelog, rulesync, seed, B2B table.
+
+## Feature Flags & Migrations
+
+No feature flag. New collection. example-backend drops `AdminAuditLog` (example-only; no published schema). Apps that copied `AdminAuditLog` keep it until they register `AuditApp`.
+
+## Activity Log & User Updates
+
+This IP **is** the activity log. No `UserUpdate` spam.
+
+## Not Included / Future Work
+
+- Org-admin scoped list (`org-management-ui`).
+- Sync-path audit.
+- Auth / login events.
+- SIEM export, legal hold, immutable object storage.
+- Custom diff UI beyond JSON fields.
+
+## Files to Create / Modify
+
+| File | Role |
+| --- | --- |
+| `api/src/audit/*` | Model, recorder, diff/redact, `AuditApp`, tests |
+| `api/src/api.ts` | `audit` option + post hooks |
+| `api/src/index.ts` | Exports |
+| `admin-backend/src/adminApp.ts` | Auto-write when recorder present |
+| `admin-frontend/src/AdminShell.tsx`, `AdminHome.tsx` | `isAuditLogModel` |
+| `example-backend/src/server.ts`, `access.ts`, models, scripts | `AuditApp`; drop `AdminAuditLog` |
+| Docs listed above | Same slice |
+
+## Task List
+
+[docs/tasks/framework-audit-log.md](../tasks/framework-audit-log.md)
+
+## Acceptance Criteria
+
+- [ ] `AuditApp` omitted: no `AuditEvent` on the default connection; product CRUD unchanged.
+- [ ] `audit: true` + `AuditApp`: create/update/delete persist one event with actor, model, record, changed-field diff, redacted secrets.
+- [ ] HTTP `/audit-events` is list+read for admin only; create/update/delete disabled.
+- [ ] Admin mutations write `AuditEvent` when the plugin is registered, without requiring `onAdminAudit`.
+- [ ] `onAdminAudit` still runs as an extra best-effort sink.
+- [ ] example-backend Platform Audit Log and Recent Activity read `AuditEvent`; `AdminAuditLog` removed.
+- [ ] RBAC `auditSink` helper writes `source: "rbac"` without dropping `RbacAudit`.
+- [ ] Default: no TTL. `retentionDays > 0` adds TTL on `created`.
+- [ ] How-to + api reference + admin explanation match the shipped design.
+- [ ] Merging the implementation PR closes https://github.com/TerrenoLabs/terreno/issues/1186 (`Fixes #1186`).