@terreno/mcp 57.3.0 → 57.4.0

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

@@ -0,0 +1,87 @@
+# Tasks: DataTable server-side filtering and search
+
+Plan: [`docs/implementationPlans/datatable-server-side-filtering.md`](../implementationPlans/datatable-server-side-filtering.md)  
+**Status:** Pick complete — tasks 1.1–4.1 implemented
+**Closes:** https://github.com/FlourishHealth/terreno/issues/1177
+
+**Feature profile:** false (full IP)
+
+## Instructions for the implementing agent
+
+- Load `terreno-ui`, `update-docs`, `verify-ui-changes`. Admin tasks also load `building-admin-interfaces`.
+- TDD: failing test first per task.
+- Run `bun test` in touched packages (`ui`, `admin-frontend`, `admin-backend`).
+- Do not import RTK, axios, or admin packages from `@terreno/ui`.
+- Do not change modelRouter list behavior or admin `q` ObjectId search.
+- Frontend slices: `verify-ui-changes` (demo on 8085; admin list when AdminModelTable changes).
+
+---
+
+### Phase 1 — Tracer (query object, no chrome)
+
+- [x] **Task 1.1**: `buildDataTableListQuery` + regex escape
+  - Delivers: Pure helper from filter/search state → modelRouter-shaped object per the IP contract table; empty values omitted; user text escaped; choice always `$in` (including one value)
+  - Files: `ui/src/dataTableListQuery.ts`, `ui/src/dataTableListQuery.test.ts`, export from `ui/src/index.tsx` only if other UI modules need it (prefer importing the file, no new barrel)
+  - Blocked by: none
+  - Skills: `terreno-ui`, `update-docs`
+  - Docs: stub the query table in `docs/reference/ui.md` so the helper is named when it lands
+  - Acceptance: `bun test ui/src/dataTableListQuery.test.ts` — search `$or` regex; `.*` in input is literal; boolean omit/true; date `_gte`/`_lte`; number nested `$gte`; choice `$in`; no `page`/`sort` keys
+
+---
+
+### Phase 2 — DataTable chrome
+
+- [x] **Task 2.1**: Types + controlled props
+  - Delivers: `DataTableColumn.filter` and search/filter/`onQueryChange` props; omitted props preserve today’s UI
+  - Files: `ui/src/Common.ts`, `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`
+  - Blocked by: 1.1
+  - Skills: `terreno-ui`
+  - Docs: none beyond types (generated props in 4.1)
+  - Acceptance: tests — no filter prop → no filter controls; `onQueryChange` not required; existing sort cycle and pagination tests still pass
+
+- [x] **Task 2.2**: Web per-column `Filter` + search box
+  - Delivers: Toolbar search (debounced) and header `Filter` popovers; text / boolean / numberRange / dateRange / choice (`MultiselectField`); `renderFilter` slot; Apply/Clear call `onFilterValuesChange` and `onQueryChange`
+  - Files: `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`, `demo/stories/DataTable.stories.tsx`
+  - Blocked by: 2.1
+  - Skills: `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: demo story is the tutorial surface; reference example in `docs/reference/ui.md`
+  - Acceptance: tests fire `onQueryChange` for each kind; demo story renders search + four kinds; `verify-ui-changes` on demo DataTable story
+
+- [x] **Task 2.3**: Native Filters sheet
+  - Delivers: On non-web, one Filters control + `Modal` sheet containing the same fields and search; same query object as web
+  - Files: `ui/src/DataTable.tsx`, `ui/src/DataTable.test.tsx`
+  - Blocked by: 2.2
+  - Skills: `terreno-ui`
+  - Docs: one row in the platform table in `docs/reference/ui.md`
+  - Acceptance: test with `Platform.OS` mock (or testIDs) — sheet apply emits the same params as web Apply; no `Filter` portal on native
+
+---
+
+### Phase 3 — Admin
+
+- [x] **Task 3.1**: `parseAdminListFilters` choice `$in` and text `$regex`
+  - Delivers: Declared `choice` accepts `{ $in: string[] }` (subset of `choices`); `text` accepts `{ $regex, $options: "i" }`; scalar choice/text still work; top-level `$or` still errors; values outside `choices` error
+  - Files: `admin-backend/src/filterParser.ts`, `admin-backend/src/filterParser.test.ts`
+  - Blocked by: none (can parallel 2.x)
+  - Skills: `building-admin-interfaces`
+  - Docs: note in `docs/how-to/admin-add-model.md` that choice filters may be multi-value `$in`
+  - Acceptance: `bun test admin-backend/src/filterParser.test.ts` covers happy `$in`, invalid choice, text regex, rejected `$or`
+
+- [x] **Task 3.2**: AdminModelTable adopts DataTable filters
+  - Delivers: Map `filters` → column `filter` / `renderFilter` for `ref`; search → `q`; drop `AdminFilterDrawer` from the table; `buildAdminListQueryParams` forwards `$in` and omits `$or`
+  - Files: `admin-frontend/src/AdminModelTable.tsx`, `admin-frontend/src/adminModelListQueryParams.ts`, `admin-frontend/src/adminModelListQueryParams.test.ts`, `admin-frontend/src/AdminModelTable.test.tsx`, `admin-frontend/src/AdminFilterDrawer.tsx` / `index.tsx` if unused
+  - Blocked by: 2.2, 3.1
+  - Skills: `building-admin-interfaces`, `terreno-ui`, `verify-ui-changes`, `update-docs`
+  - Docs: `docs/reference/admin-frontend.md`, `docs/explanation/admin-interface.md`, `docs/how-to/admin-add-model.md` (filters on columns, not a drawer)
+  - Acceptance: tests — search param is `q` not `$or`; choice multi → `$in`; drawer not in table output; admin list verification in admin-spa or example admin
+
+---
+
+### Phase 4 — Docs and seed
+
+- [x] **Task 4.1**: Diátaxis + generated props + changelog
+  - Delivers: Query contract and platform table in `docs/reference/ui.md`; admin how-to/reference/explanation; regenerate UI component reference; CHANGELOG Added; seed IP/task links already in Grow stay accurate
+  - Files: `docs/reference/ui.md`, `docs/how-to/admin-add-model.md`, `docs/reference/admin-frontend.md`, `docs/explanation/admin-interface.md`, `docs/explanation/roadmap-seed-issues.md`, `CHANGELOG.md`; `ui` types + `bun run website:generate` as required by `update-docs`
+  - Blocked by: 2.3, 3.2
+  - Skills: `update-docs`
+  - Acceptance: a stranger can wire `onQueryChange` to a modelRouter list from docs; admin text contains + choice `$in` are explicit; `bun run website:build` if the site is in the slice

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

@@ -2,7 +2,7 @@
 
 See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPlans/examples-demo-coverage.md)
 
-**RTK deprecation flag:** **Partial.** Tasks marked `[RTK]` touch the example apps' data layer and must wait for PR #869. Demo-app and coverage-infrastructure tasks are `@terreno/ui`-only or CI-only and are safe to implement now.
+**RTK deprecation flag:** **Partial.** Tasks 5.1–5.3 originally waited on PR #869. `@terreno/syncdb` is in the example apps on this branch; those tasks are unblocked.
 
 ## Instructions for the implementing agent
 
@@ -14,25 +14,107 @@ See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPla
 
 ## Phase 1: Demo coverage — audit and P0
 
-- [ ] **Task 1.1**: Audit demo story coverage
+- [x] **Task 1.1**: Audit demo story coverage
   - Description: Extract the list of components exported from `ui/src/index.tsx`. Extract the list of components registered in `demo/demoConfig.tsx`. Produce the difference. Classify each missing component as P0 (demonstrates a pillar: AI, auth, responsive layout), P1 (common in real apps), P2 (uncommon), or "cannot be demoed in isolation" with a reason. Report the full table in the PR body.
   - Files: none (findings in the PR body)
   - Depends on: none
   - Acceptance: the table is derived from the two actual source files; every missing component has a classification; every "cannot be demoed" entry has a stated reason.
 
-- [ ] **Task 1.2**: Add P0 stories
+### Task 1.1 audit (2026-09-10, `ui/src/index.tsx` + `demo/demoConfig.tsx`)
+
+Registered stories (65 configs, including OpenAPI Context): Accordion, AddressField, AiSuggestionBox, Avatar, Badge, Banner, BooleanField, Box, Button, Card, CheckBox, ConsentFormScreen, CustomSelectField, DataTable, DateTimeField, EditableCard, EmailField, EmojiSelector, Field, Filter, Heading, HeightField, Icon, IconButton, Link, LoginScreen, MarkdownEditorField, MarkdownView, Modal, MultiselectField, NumberField, OpenAPIContext, Page, Pagination, PasswordField, PhoneNumberField, Popover, RadioField, SectionDivider, SegmentedControl, SelectBadge, SelectField, SidebarNavigation (+ Panel), SideDrawer, SignatureCaptureField, SignatureField, Slider, Spinner, Table (+ Badge/Boolean/Date/IconButton/Number/Text/Title), TapToEdit, Text, TextArea, TextField, Theme, ThumbsUpDownFeedback, Toast, Tooltip, TypedSignatureField, UserInactivity.
+
+`ModalSheet.tsx` does not export a `ModalSheet` identifier; the public component is `SimpleContent`. Matching uses `component:` in `demo/story-config/*.config.tsx` plus `OpenAPIContext` in `demoConfig.tsx`.
+
+| Export | Class | Reason |
+| --- | --- | --- |
+| `GPTChat` | P0 | AI pillar |
+| `SocialLoginButton` | P0 | Auth pillar |
+| `SplitPage` | P0 | Responsive layout pillar |
+| `ActionSheet` | P1 | Common overlay |
+| `SimpleContent` | P1 | ModalSheet public export; bottom sheet |
+| `FilePickerButton` | P1 | Common file input |
+| `Image` | P1 | Common media |
+| `SignUpScreen` | P1 | Auth screen (LoginScreen already demos) |
+| `OAuthButtons` | P1 | Grouped social login |
+| `ErrorPage` | P1 | Common error UI |
+| `ErrorBoundary` | P1 | Common error UI |
+| `DismissButton` | P1 | Common chrome |
+| `ImageBackground` | P1 | Common layout |
+| `MarkdownEditor` | P1 | Editor (field already demos) |
+| `InfoTooltipButton` | P1 | Common help affordance |
+| `InfoModalIcon` | P1 | Common help affordance |
+| `OfflineBanner` | P1 | Sync/offline status |
+| `SyncStatusBanner` | P1 | Sync status |
+| `AttachmentPreview` | P1 | Chat/file UX |
+| `ConflictSheet` | P1 | Sync conflict UX |
+| `AIRequestExplorer` | P1 | AI admin surface |
+| `Body` | P1 | Layout primitive |
+| `PasswordRequirements` | P1 | Auth helper |
+| `UnifiedAddressAutoCompleteField` | P1 | Address (AddressField demos a wrapper) |
+| `WebAddressAutocomplete` | P1 | Web address |
+| `MobileAddressAutocomplete` | P1 | Native address |
+| `Radio` | P2 | Primitive under RadioField |
+| `DraggableList` | P2 | Uncommon |
+| `UpgradeRequiredScreen` | P2 | Uncommon |
+| `GPTMemoryModal` | P2 | GPTChat sub-surface |
+| `ConsentNavigator` | P2 | ConsentFormScreen already demos |
+| `DateTimeActionSheet` | P2 | DateTimeField already demos |
+| `HeightActionSheet` | P2 | HeightField already demos |
+| `DecimalRangeActionSheet` | P2 | Uncommon picker |
+| `NumberPickerActionSheet` | P2 | Uncommon picker |
+| `FilterAccordion` | P2 | Filter already demos |
+| `FilterBoolean` | P2 | Filter already demos |
+| `FilterChangesBadge` | P2 | Filter already demos |
+| `FilterSelectMenu` | P2 | Filter already demos |
+| `TableHeader` | P2 | Table already demos |
+| `TableHeaderCell` | P2 | Table already demos |
+| `TableRow` | P2 | Table already demos |
+| `Signature` | P2 | SignatureField already demos |
+| `Swiper` | P2 | Onboarding helper |
+| `BarsFilterIcon` | P2 | Icon primitive |
+| `ScrollView` | P2 | RN wrapper |
+| `FlatList` | P2 | RN wrapper |
+| `TerrenoProvider` | cannot | Demo root already wraps the app |
+| `ThemeProvider` | cannot | Theme story already exercises theme; provider is shell |
+| `OpenAPIProvider` | cannot | OpenAPI Context story already wraps usage |
+| `IconRegistryProvider` | cannot | Registry is app shell, not a visual component |
+| `TableContextProvider` | cannot | Table stories already wrap table context |
+| `Host` | cannot | Portal host is app shell |
+| `Portal` | cannot | Portal is a host primitive, not a visual story |
+| `PortalContext` | cannot | React context object |
+| `ThemeContext` | cannot | React context object |
+| `Unifier` | cannot | Platform utility singleton, not a component |
+| `SPACING_MAP` | cannot | Constant, not a component |
+| `USSTATESLIST` | cannot | Constant, not a component |
+| `COUNTY_AND_COUNTY_EQUIVALENT_ENTITIES` | cannot | Constant, not a component |
+| `GOOGLE_PLACES_API_RESTRICTIONS` | cannot | Constant, not a component |
+| `SIDEBAR_BADGE_STATUS_MAP` | cannot | Constant, not a component |
+| `SUPPORTED_ORIENTATIONS` | cannot | Constant, not a component |
+| `NATIVE_BREAKPOINT_MIN_WIDTH` | cannot | Constant, not a component |
+| `WEB_BREAKPOINT_MIN_WIDTH` | cannot | Constant, not a component |
+| `DEFAULT_SIGNATURE_FONTS` | cannot | Constant, not a component |
+| `CONFLICT_METADATA_FIELDS` | cannot | Constant, not a component |
+| `NO_CONFLICT_DIFF_FIELDS` | cannot | Constant, not a component |
+| `StyleProp` | cannot | Type re-export |
+| `ViewStyle` | cannot | Type re-export |
+| `OAuthProvider` | cannot | Type, not a component |
+| `OnboardingPage` | cannot | Type, not a component |
+| `PasswordRequirement` | cannot | Type, not a component |
+
+- [x] **Task 1.2**: Add P0 stories
   - Description: Write stories for every P0 component from Task 1.1 (expected to include `GPTChat`, `SocialLoginButton`, and `SplitPage` — confirm against the audit). Each story shows multiple states where the component supports them: default, loading, error, disabled, and any variant enumerations. `GPTChat` needs a story that works without a live backend — use a static message list rather than wiring a real AI call. `SocialLoginButton` needs all three providers and both variants. `SplitPage` needs a story demonstrating the responsive breakpoint behavior. Register each in `demoConfig.tsx`.
   - Files: `demo/stories/*.stories.tsx` (new), `demo/demoConfig.tsx`
   - Depends on: Task 1.1
   - Acceptance: every P0 component has a story reachable in the running demo (`bun run demo:start`, port 8085); each shows at least two states; `GPTChat`'s story renders with no backend running; `bun run demo:compile` passes.
 
-- [ ] **Task 1.3**: Add the demo coverage check
+- [x] **Task 1.3**: Add the demo coverage check
   - Description: Create `scripts/check-demo-coverage.ts` (Bun, TypeScript, `const` arrow functions with explicit return types). It parses the export list from `ui/src/index.tsx` and the registered components from `demo/demoConfig.tsx`, then fails with a list of unstoried components. Support an allowlist file or an in-script allowlist where each entry requires a comment explaining why the component cannot be demoed. Add a `check:demo-coverage` script to the root `package.json` and wire it into `.github/workflows/ui-demo-ci.yml`.
   - Files: `scripts/check-demo-coverage.ts` (new), `package.json`, `.github/workflows/ui-demo-ci.yml`
   - Depends on: Task 1.2
   - Acceptance: the check passes with the current allowlist; adding a new export to `ui/src/index.tsx` without a story makes it fail and name the component; the CI job runs it.
 
-- [ ] **Task 1.4**: Make the demo's `test:ci` real
+- [x] **Task 1.4**: Make the demo's `test:ci` real
   - Description: `demo/package.json`'s `test:ci` is currently `echo 'No tests'`. Replace it with something meaningful: at minimum a smoke test that every registered story renders without throwing, using the `renderWithTheme` helper from `@terreno/ui`'s test utilities. This catches the most common demo breakage — a story that crashes after a component's props change.
   - Files: `demo/package.json`, `demo/**` test files (new)
   - Depends on: Task 1.2
@@ -40,13 +122,13 @@ See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPla
 
 ## Phase 2: Remaining demo stories
 
-- [ ] **Task 2.1**: Add P1 stories
+- [x] **Task 2.1**: Add P1 stories
   - Description: Write stories for every P1 component from the Task 1.1 audit (expected to include `ActionSheet`, `ModalSheet`, `FilePickerButton`, and `Image`). Interactive components need a story that can actually be triggered from the demo UI, not just a static render. Register each in `demoConfig.tsx`.
   - Files: `demo/stories/*.stories.tsx` (new), `demo/demoConfig.tsx`
   - Depends on: Task 1.3
   - Acceptance: every P1 component has a story; interactive components can be opened and dismissed in the running demo; `bun run demo:compile` passes.
 
-- [ ] **Task 2.2**: Add P2 stories and close the allowlist
+- [x] **Task 2.2**: Add P2 stories and close the allowlist
   - Description: Write stories for the remaining P2 components. For any component that genuinely cannot be demoed in isolation, add it to the allowlist with a specific reason (not "hard to demo"). The goal is an empty or near-empty gap list with a justified allowlist.
   - Files: `demo/stories/*.stories.tsx` (new), `demo/demoConfig.tsx`, the allowlist
   - Depends on: Task 2.1
@@ -54,25 +136,47 @@ See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPla
 
 ## Phase 3: Coverage enforcement
 
-- [ ] **Task 3.1**: Measure current coverage per package
+- [x] **Task 3.1**: Measure current coverage per package
   - Description: Run every published package's `test:coverage` on a clean `master` and record the actual coverage. Report which packages are below the 95% threshold in the PR body. This is a planning step — do not lower the threshold or add exemptions.
   - Files: none (findings in the PR body)
   - Depends on: none
   - Acceptance: every published package has a measured coverage value; packages below 95% are listed with their gap.
 
-- [ ] **Task 3.2**: Wire the threshold into every package CI
+### Task 3.1 coverage (2026-09-10)
+
+Measured with `bun run ../scripts/check-coverage.ts --threshold=0` from each package directory after compile. Figures are the script's `Coverage summary` when present (isolated-test merge); otherwise the Bun `All files` row. Threshold is **95% functions and 95% lines** — not lowered.
+
+| Package | Functions % | Lines % | Below 95%? | Gap |
+| --- | --- | --- | --- | --- |
+| `@terreno/api` | 98.84 | 99.06 | no | — |
+| `@terreno/ui` | 99.78 | 99.65 | no | — |
+| `@terreno/rtk` | 99.67 | 98.98 | no | — |
+| `@terreno/syncdb` | 97.81 | 96.84 | no | — |
+| `@terreno/ai` | 99.21 | 99.63 | no | — |
+| `@terreno/comms` | 96.76 | 98.22 | no | — |
+| `@terreno/mcp` | 99.68 | 97.44 | no | — |
+| `@terreno/feature-flags` | 100.00 | 99.55 | no | — |
+| `@terreno/api-health` | 100.00 | 100.00 | no | — |
+| `@terreno/admin-backend` | 97.25 | 96.65 | no | — |
+| `@terreno/admin-frontend` | 95.11 | 95.55 | no | — |
+| `@terreno/admin-spa` | 100.00 | 100.00 | no | — |
+| `@terreno/test` | 96.34 | 95.32 | no | — |
+
+Packages below 95%: none (all published packages meet the 95% function and line thresholds as of the latest local `test:coverage` runs).
+
+- [x] **Task 3.2**: Wire the threshold into every package CI
   - Description: Add `scripts/check-coverage.ts` (default 95% threshold) to every published package's CI — either the existing dedicated workflow or the new matrix job from Task 3.3. Packages below threshold when this lands will fail CI until catch-up work merges; track that in the implementation PR.
   - Files: `.github/workflows/ui-ci.yml`, `ai-ci.yml`, `admin-spa-ci.yml`, `.github/workflows/packages-ci.yml`, package `package.json` files as needed
   - Depends on: Task 3.1
   - Acceptance: every published package's CI runs the coverage check at 95%; no package has a permanent exemption.
 
-- [ ] **Task 3.3**: Add the matrix CI job for uncovered packages
+- [x] **Task 3.3**: Add the matrix CI job for uncovered packages
   - Description: Per IP question E3, create `.github/workflows/packages-ci.yml` with a matrix over the published packages that lack a dedicated workflow (`admin-backend`, `feature-flags`, `api-health`, `test` — verify the current set against `.github/workflows/`). Each matrix entry runs compile, lint, tests, and the coverage check. Use path filters so the job only runs for the affected package where practical. Follow the repo's required-input validation convention.
   - Files: `.github/workflows/packages-ci.yml` (new)
   - Depends on: Task 3.2
   - Acceptance: the workflow parses as valid YAML; the matrix covers exactly the published packages without their own workflow; each entry runs compile, lint, test, and coverage at 95%.
 
-- [ ] **Task 3.4**: Catch up packages below threshold
+- [x] **Task 3.4**: Catch up packages below threshold
   - Description: For each package measured below 95% in Task 3.1, add tests until `scripts/check-coverage.ts` passes. This may be a separate PR if the gap is large; do not merge the CI wiring until every package passes or the IP owner explicitly defers a package with a linked issue.
   - Files: package test files as needed
   - Depends on: Task 3.2
@@ -80,13 +184,13 @@ See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPla
 
 ## Phase 4: Codecov
 
-- [ ] **Task 4.1**: Configure Codecov
+- [x] **Task 4.1**: Configure Codecov
   - Description: Add `codecov.yml` configuring per-package flags so each package's coverage is reported separately, a target of "auto" with a small allowed threshold so trivial deltas do not fail PRs, and comment settings that post the delta on pull requests. Add the upload step to every package CI workflow. Note in the file where the `CODECOV_TOKEN` secret must be configured (a maintainer action for a public repo, though public repos often need no token — verify current Codecov requirements before documenting).
   - Files: `codecov.yml` (new), every package CI workflow
   - Depends on: Task 3.4
   - Acceptance: `codecov.yml` is valid; every package workflow uploads with a distinct flag; the token requirement is documented accurately for a public repo.
 
-- [ ] **Task 4.2**: Add the coverage badge
+- [x] **Task 4.2**: Add the coverage badge
   - Description: Add a Codecov badge to `README.md` next to the existing npm and license badges. Add a "Testing and coverage" section to `CONTRIBUTING.md` explaining: the 95% coverage expectation for new code, that coverage must not drop in a PR, and how to run coverage locally per package.
   - Files: `README.md`, `CONTRIBUTING.md`
   - Depends on: Task 4.1
@@ -94,19 +198,21 @@ See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPla
 
 ## Phase 5: Example feature matrix
 
-- [ ] **Task 5.1**: `[RTK]` Audit example app feature coverage
+- [x] **Task 5.1**: `[RTK]` Audit example app feature coverage
   - Description: Build the capability matrix from the IP by reading `example-backend/src/` and `example-frontend/app/`. Resolve every `?`: does an example actually exercise AI structured output, Better Auth, and (after #869) syncdb local-first behavior? For each capability, cite the file that exercises it or record it as a gap. Include capabilities that are not shipped (RBAC, background jobs) marked as such with links to their IPs.
   - Files: `docs/explanation/example-coverage.md` (new)
-  - Depends on: PR #869 merged
+  - Depends on: none (`@terreno/syncdb` is in-tree; PR #869 closed)
   - Acceptance: no `?` remains; every "yes" cites a file path; every gap is explicit; unshipped capabilities link their IPs.
 
-- [ ] **Task 5.2**: `[RTK]` Fill the highest-value example gaps
+- [x] **Task 5.2**: `[RTK]` Fill the highest-value example gaps
   - Description: For each gap found in Task 5.1, either add the example or record it as a known gap with an issue. Prioritize capabilities the launch documentation depends on — if a tutorial or reference page describes something with no working example, that is the highest priority because the docs claim will be tested by readers. Do not add examples for unshipped features.
   - Files: `example-backend/src/**`, `example-frontend/app/**`, `docs/explanation/example-coverage.md`
   - Depends on: Task 5.1
   - Acceptance: every gap that a launch document depends on is filled with a working example; remaining gaps are recorded with issue links; both example apps still pass their CI.
 
-- [ ] **Task 5.3**: Link the matrix into the contribution process
+Recorded gaps (2026-09-11): AI structured output → [#1010](https://github.com/FlourishHealth/terreno/issues/1010); generic background jobs → [#1188](https://github.com/FlourishHealth/terreno/issues/1188). No launch tutorial currently depends on either.
+
+- [x] **Task 5.3**: Link the matrix into the contribution process
   - Description: Add a note to `CONTRIBUTING.md` and the PR template: when adding a framework capability, add or update the example that exercises it and update `docs/explanation/example-coverage.md`. This is what keeps the matrix true. Link the matrix from `docs/explanation/README.md`.
   - Files: `CONTRIBUTING.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `docs/explanation/README.md`
   - Depends on: Task 5.1

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

@@ -0,0 +1,86 @@
+# Tasks: Framework-level audit log
+
+IP: [framework-audit-log.md](../implementationPlans/framework-audit-log.md)  
+**Closes:** https://github.com/FlourishHealth/terreno/issues/1186
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (model, plugin, CRUD diffs)
+
+- [x] **Task 1.1**: `AuditEvent` model + `AuditApp` list/read router
+  - Delivers: `createAuditEventModel(connection)` (no default-connection singleton); `new AuditApp()` registers GET list/read at `/audit-events` with `Permissions.IsAdmin`; create/update/delete permission arrays empty; default no TTL; field `description`s; append-only (no `isDeletedPlugin`)
+  - Files: `api/src/audit/auditEventModel.ts`, `api/src/audit/auditApp.ts`, `api/src/audit/auditApp.test.ts`, `api/src/index.ts`
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`
+  - Docs: stub `AuditApp` in `docs/reference/api.md` so the tracer is documented when it lands
+  - Acceptance: bun + supertest — import `@terreno/api` does not register `AuditEvent` on `mongoose.connection`; with plugin, admin GET list 200 empty; POST/PATCH/DELETE not available; non-admin list 405 (modelRouter `permissionMiddleware` for failed list perms)
+
+- [x] **Task 1.2**: `modelRouter` `audit` + recorder + redacted diffs
+  - Delivers: `audit: true | {redact?: string[]}` after successful create/update/delete writes one `AuditEvent` (`source: "modelRouter"`, `verb` created/updated/deleted); changed-fields only; default redact `password`/`hash`/`salt`/`token`/`secret`/`refreshToken`; extra `redact` merged; best-effort (`logger.error`, CRUD still 2xx); never audit `AuditEvent`; without `AuditApp`, skip write and log error once per process
+  - Files: `api/src/audit/record.ts`, `api/src/audit/diff.ts`, `api/src/api.ts`, `api/src/audit/auditRouter.test.ts` (or extend 1.1 tests)
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`
+  - Docs: one-line `audit` option on the api.md stub
+  - Acceptance: bun tests — PATCH `title` yields one event with `before.title`/`after.title`; secret fields absent; `redact: ["ssn"]` strips `ssn`; create has `after` only; delete has `before` only; thrown recorder still returns 200/201; plugin omitted: CRUD 201 and zero events
+
+## Phase 2 — Array ops + org field
+
+- [x] **Task 2.1**: Array mutations
+  - Delivers: modelRouter array push/update/remove with `audit: true` write `verb: "updated"` and `operation` `arrayPush` / `arrayUpdate` / `arrayRemove`; `recordId` set
+  - Files: `api/src/api.ts`, `api/src/audit/*.test.ts`
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: operation table in `docs/how-to/audit-log.md` (create page if 5.1 not started)
+  - Acceptance: bun + supertest for each array verb; one event each; product array tests still pass
+
+- [x] **Task 2.2**: Optional `organizationId`
+  - Delivers: copy `req.organization` id when set, else string `doc.organizationId`; omit when neither exists; list `queryFields` includes `organizationId`
+  - Files: `api/src/audit/record.ts`, tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: org field note on the how-to (org-admin filter is future)
+  - Acceptance: two tests — document field vs `req.organization`; neither → field absent
+
+## Phase 3 — Admin, example, RBAC
+
+- [x] **Task 3.1**: AdminApp auto-write
+  - Delivers: when recorder is present, successful admin POST/PATCH/DELETE persist `AuditEvent` with `source: "admin"` even if `onAdminAudit` is omitted; still invoke `onAdminAudit` when set; skip `AuditEvent` model; mutation succeeds if the framework write throws
+  - Files: `admin-backend/src/adminApp.ts`, `admin-backend/src/adminApp.models.test.ts`
+  - Blocked by: 1.2
+  - Skills: `building-admin-interfaces`, `terreno-backend-api`
+  - Docs: `docs/reference/admin-backend.md` — `onAdminAudit` is extra
+  - Acceptance: existing `onAdminAudit` tests still pass; new tests — plugin present, no `onAdminAudit`, POST creates an `AuditEvent`; both configured → both run; throw in recorder → still 201
+
+- [x] **Task 3.2**: example-backend + RBAC helper + Platform shell
+  - Delivers: `persistRbacAuditToAuditEvent` exported from `@terreno/api`; example registers `AuditApp`, `audit: true` on Todo, removes `AdminAuditLog` model/`onAdminAudit` persistence, points admin config + scripts + `access.ts` sink at `AuditEvent`; `isAuditLogModel` matches `AuditEvent` (keep old name/path); Recent Activity uses it
+  - Files: `api/src/audit/rbacSink.ts`, `example-backend/src/server.ts`, `example-backend/src/access.ts`, `example-backend/src/models/adminAuditLog.ts` (delete), `example-backend/src/modelInterfaces.ts`, `example-backend/src/adminScripts.ts`, `admin-frontend/src/AdminShell.tsx`, `admin-frontend/src/AdminHome.tsx`, matching tests
+  - Blocked by: 3.1
+  - Skills: `building-admin-interfaces`, `verify-ui-changes`, `generate-sdk` if OpenAPI admin SDK must list `/audit-events`
+  - Docs: example README admin paragraph
+  - Acceptance: bun tests for shell matcher + RBAC sink mapping; example compile; UI: admin login → mutate a Todo or admin model → Platform Audit Log / Recent Activity shows the row (`verify-ui-changes`, artifacts under `/opt/cursor/artifacts/`)
+
+## Phase 4 — Retention
+
+- [x] **Task 4.1**: Optional TTL
+  - Delivers: `AuditApp({retentionDays: n})` for `n > 0` creates TTL index on `created` (`expireAfterSeconds = n * 86400`); omit or `0` → no TTL index
+  - Files: `api/src/audit/auditEventModel.ts`, `api/src/audit/auditApp.ts`, tests
+  - Blocked by: 1.1
+  - Skills: `mongoose-schema-safety`
+  - Docs: TTL + index-drop note on the how-to
+  - Acceptance: index spec assertions; default plugin has no TTL index
+
+## Phase 5 — Docs and roadmap
+
+- [x] **Task 5.1**: Diátaxis + changelog + rules
+  - Delivers: operator how-to, api reference (full, not stub), admin-interface Platform row, admin-backend `onAdminAudit` note, rulesync api rule, `CHANGELOG.md` Added, `bun run rules` / `skills:sync` if rulesync changed
+  - Files: `docs/how-to/audit-log.md`, `docs/reference/api.md`, `docs/explanation/admin-interface.md`, `docs/reference/admin-backend.md`, `.rulesync/rules/api/00-api.mdc`, `CHANGELOG.md`
+  - Blocked by: 1.2 (content can land with 2.x–4.x; must match shipped options)
+  - Skills: `update-docs`
+  - Acceptance: a stranger can enable `AuditApp` + `audit: true` from the how-to; append-only and forever-default are explicit; `bun run website:build` if the docs site is in the slice
+
+- [x] **Task 5.2**: Roadmap seed + B2B table
+  - Delivers: `docs/explanation/roadmap-seed-issues.md` `framework-audit-log` points at IP/task GitHub URLs, `IP=framework-audit-log`, depends line is soft-org; `b2b-platform-program.md` lists this IP as Draft/Approved matching the IP header
+  - Files: `docs/explanation/roadmap-seed-issues.md`, `docs/implementationPlans/b2b-platform-program.md`
+  - Blocked by: 5.1
+  - Skills: `update-docs`
+  - Acceptance: seed `Implementation plan` / `Tasks` links are not `*(not yet written)*`

package/src/docs/versioned/next/tasks/gpt-chat-mascot.md

@@ -0,0 +1,13 @@
+# GPTChat optional mascot
+
+**Plan:** [gpt-chat-mascot.md](../implementationPlans/gpt-chat-mascot.md)
+
+- [x] **Task 1**: Optional `mascot` slot on `GPTChat`
+  - Files: `ui/src/GPTChat.tsx`, `ui/src/GPTChat.test.tsx`
+  - Acceptance: empty chat renders consumer node; omitted prop hides `gpt-mascot`; messages hide it
+  - Docs: `docs/reference/ui.md`, `docs/how-to/add-gpt-chat-mascot.md`
+  - Skills: `terreno-ui`, `update-docs`, `verify-ui-changes`
+
+- [x] **Task 2**: Demo + example consumer
+  - Files: `demo/stories/GPTChat.stories.tsx`, `demo/story-config/GPTChat.config.tsx`, `example-frontend/app/(tabs)/ai.tsx`
+  - Acceptance: Mascot story and example AI tab pass a node; example coverage notes optional branding

package/src/docs/versioned/next/tasks/job-queues.md

@@ -0,0 +1,144 @@
+# Tasks: Durable background jobs
+
+IP: [job-queues.md](../implementationPlans/job-queues.md)  
+**Closes:** https://github.com/FlourishHealth/terreno/issues/1188
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (package, enqueue, Mongo worker)
+
+- [x] **Task 1.1**: Scaffold `@terreno/jobs`
+  - Delivers: workspace package compiles and lints; root `jobs:compile` / `jobs:test` / `jobs:lint` scripts; empty `JobsApp` registers as `TerrenoPlugin` without starting a worker
+  - Files: `jobs/package.json`, `jobs/tsconfig.json`, `jobs/src/index.ts`, `jobs/src/jobsApp.ts`, root `package.json`
+  - Blocked by: none
+  - Skills: `terreno-backend-api`
+  - Docs: none (Phase 5)
+  - Acceptance: `bun run jobs:compile` and `bun run jobs:lint` pass; `new TerrenoApp().register(new JobsApp())` boots in a bun test
+
+- [x] **Task 1.2**: `Job` model + `define` / `enqueue` + Mongo claim
+  - Delivers: five-type `Job` model; `jobs.define(name, {handler})`; `getJobsService().enqueue({name, payload})` inserts `pending`; `MongoJobRunner` claims with `findOneAndUpdate`; handler runs inside `runWithRequestContext({jobId})`; unknown `name` throws `APIError` 400
+  - Files: `jobs/src/models/job.ts`, `jobs/src/modelTypes.ts`, `jobs/src/jobsService.ts`, `jobs/src/runners/mongoRunner.ts`, tests
+  - Blocked by: 1.1
+  - Skills: `mongoose-schema-safety`, `backend-test-env`, `terreno-backend-api`
+  - Docs: stub one sentence in `docs/reference/jobs.md` if the file exists; else wait for 5.1
+  - Acceptance: bun test — enqueue then `startWorker` completes the job; missing handler fails loud; every schema field has `description`
+
+- [x] **Task 1.3**: Explicit `startWorker` in-process and lock reclaim
+  - Delivers: `JobsApp.register` does **not** poll; `startWorker()` starts the runner; `stopWorker()` aborts; expired `lockedAt` reclaims `running`; two workers claim one job once
+  - Files: `jobs/src/jobsApp.ts`, `jobs/src/runners/mongoRunner.ts`, tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: none (5.1)
+  - Acceptance: bun test — no worker until `startWorker`; kill-the-process simulation: leave `pending`, new worker runs it; dual-worker claim uniqueness
+
+## Phase 2 — Retries, DLQ, delay, cron
+
+- [x] **Task 2.1**: Attempts, backoff, `dead`
+  - Delivers: throw → `attemptCount++`, `attempts[]`, `runAt` backoff with jitter; at `maxAttempts` → `status: "dead"`; success → `completed`; `ctx.signal` abort on cancel
+  - Files: `jobs/src/jobsService.ts`, retry helper, tests
+  - Blocked by: 1.3
+  - Skills: `terreno-backend-api`
+  - Docs: none (5.1)
+  - Acceptance: bun test — three failures with `maxAttempts: 3` land `dead`; between attempts status is `pending` with future `runAt`; Luxon used for delay math
+
+- [x] **Task 2.2**: Delayed `runAt` + `idempotencyKey`
+  - Delivers: `enqueue({runAt})` not claimed before `runAt`; duplicate `(name, idempotencyKey)` returns the existing job and does not insert a second row
+  - Files: `jobs/src/jobsService.ts`, Job indexes, tests
+  - Blocked by: 1.2
+  - Skills: `mongoose-schema-safety`
+  - Docs: none (5.1)
+  - Acceptance: bun test — frozen clock (Luxon); unique index violation path covered
+
+- [x] **Task 2.3**: `JobSchedule` + recurring cron + IANA timezone
+  - Delivers: `define(..., {schedule: {cron, timezone}})`; upsert `JobSchedule`; tick enqueues a child `Job`; skip tick if a child is still `running`/`pending` for that schedule; invalid cron fails at define/start
+  - Files: `jobs/src/models/jobSchedule.ts`, scheduler, tests
+  - Blocked by: 1.3
+  - Skills: `mongoose-schema-safety`, `terreno-backend-api`
+  - Docs: none (5.1)
+  - Acceptance: bun test — `America/New_York` vs `UTC` next-run; overlap skip; default timezone `UTC`
+
+## Phase 3 — Runners and execute HTTP
+
+- [x] **Task 3.1**: `JobRunner` interface + custom runner
+  - Delivers: injected `runner` used on enqueue/start; test fake runner records `enqueue` calls; Mongo remains default
+  - Files: `jobs/src/types.ts`, `jobs/src/runners/custom.ts` (or types-only), tests
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: none (5.1)
+  - Acceptance: bun test — custom runner `enqueue` called once per job; Mongo runner tests still pass
+
+- [x] **Task 3.2**: `POST /jobs/execute` auth gate
+  - Delivers: route mounted when `mountExecuteRoute` or cloud runner; body `{jobId}`; loads/claims/runs; unsigned 401; terminal completed → 200 no-op; live lock → 409
+  - Files: `jobs/src/routes/jobsExecute.ts`, tests
+  - Blocked by: 1.3
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: none (5.1)
+  - Acceptance: bun + supertest; path can be omitted from SDK codegen (internal tag); rate-limit not skipped
+
+- [x] **Task 3.3**: GCP Cloud Tasks adapter (mocked)
+  - Delivers: `@terreno/jobs/runners/gcpCloudTasks` optional peer `@google-cloud/tasks`; `enqueue` creates HTTP task to `{publicUrl}/jobs/execute` with OIDC audience; no live GCP
+  - Files: `jobs/src/runners/gcpCloudTasks.ts`, tests with fake client, `jobs/package.json` exports/peers
+  - Blocked by: 3.1, 3.2
+  - Skills: `terreno-backend-api`
+  - Docs: env names listed in 5.1
+  - Acceptance: bun test — fake client receives queue/url/oidc; missing config fails startup loud
+
+- [x] **Task 3.4**: Vercel Queues adapter (mocked)
+  - Delivers: `@terreno/jobs/runners/vercelQueues` optional peer; `send(topic,{jobId})` with retention/delay coupling; private `handleCallback` consumer → `executeJobById`; no Workflows API; no live Vercel
+  - Files: `jobs/src/runners/vercelQueues.ts`, tests
+  - Blocked by: 3.1, 3.2
+  - Skills: `terreno-backend-api`
+  - Docs: 5.1
+  - Acceptance: bun test — fake queue publish/send options, consumer retry directives, >7d dispatch compensation; platform auth delegated to vendor `handleCallback`
+
+## Phase 4 — Admin API and UI
+
+- [x] **Task 4.1**: Admin HTTP + `admin:jobs`
+  - Delivers: list/detail/retry/requeue/cancel + schedule pause/resume; `terrenoStatements.admin` includes `jobs`; 403 without permission; retry creates linked row; requeue from `dead`
+  - Files: `jobs/src/routes/jobsAdmin.ts`, `api/src/rbac/statements.ts`, RBAC tests in jobs package, example-backend OpenAPI if needed
+  - Blocked by: 2.1, 2.3
+  - Skills: `terreno-backend-api`
+  - Docs: none (5.1)
+  - Acceptance: bun + supertest for 200/403/401; retry vs requeue semantics per IP
+
+- [x] **Task 4.2**: Admin frontend Jobs screens
+  - Delivers: `JOBS_ADMIN_WIDGETS`, `JobsDashboardScreen`, `JobsJobDetail`, home widget `jobs`; built-in registry (no host remap)
+  - Files: `admin-frontend/src/jobs/*`, widget registry, tests + isolated specs
+  - Blocked by: 4.1
+  - Skills: `building-admin-interfaces`, `terreno-ui`, `terreno-data-fetching`
+  - Docs: `docs/how-to/admin-import-prebuilt.md` in 5.1
+  - Acceptance: bun tests for render/filter/actions; no `fetch`/`axios`; no syncdb
+
+- [x] **Task 4.3**: example-backend + example-frontend + admin-spa + UI verify
+  - Delivers: example registers `JobsApp` + Mongo runner; demo job; optional `jobs:worker` script; routes `/admin/jobs`; admin-spa `/jobs`; SDK regen if OpenAPI changed; `JOBS_START_WORKER` gates API-process worker (default true)
+  - Files: `example-backend/src/server.ts`, worker entry, `example-frontend/app/admin/**`, `admin-spa/app/**`, `store/openApiSdk.ts` (generated)
+  - Blocked by: 4.2, 1.3
+  - Skills: `building-admin-interfaces`, `verify-ui-changes`, `generate-sdk`
+  - Docs: none (5.1)
+  - Acceptance: `verify-ui-changes` — `/opt/cursor/artifacts/jobs_admin_dlq_workflow.mp4` (script→dead attempts→requeue execution→retry linked row); `/opt/cursor/artifacts/jobs_admin_cancel_scheduled_job.mp4` (scheduled cancel confirmation, refresh persistence, no attempts); worker script documented
+
+## Phase 5 — Docs, CI, publish
+
+- [x] **Task 5.1**: Diátaxis + agent docs + changelog + seed
+  - Delivers: how-to, reference, api.md cron contrast, env table, import-prebuilt, seed IP/task URLs, jobs rule, backend-api skill mention, unreleased changelog, `bun run rules` / `skills:sync`
+  - Files: `docs/how-to/background-jobs.md`, `docs/reference/jobs.md`, `docs/how-to/README.md`, `docs/reference/api.md`, `docs/reference/environment-variables.md`, `docs/how-to/admin-import-prebuilt.md`, `docs/explanation/roadmap-seed-issues.md`, `.rulesync/rules/jobs/00-jobs.md`, `plugins/terreno-planning/skills/terreno-backend-api/SKILL.md`, `changelog/unreleased/job-queues.md`
+  - Blocked by: 3.4, 4.3
+  - Skills: `update-docs`, `update-agent-docs`
+  - Docs: (this task)
+  - Acceptance: stranger can define, enqueue, run a worker, and choose Mongo vs GCP vs Vercel from the how-to; `bun run website:build`; `cronjob()` still documented as process-local
+
+- [x] **Task 5.2**: CI + publish wiring
+  - Delivers: `jobs-ci.yml`; `publish-on-tag` for `@terreno/jobs`; `cd.yml` path filter includes `jobs/**`
+  - Files: `.github/workflows/*`
+  - Blocked by: 1.1
+  - Skills: none
+  - Docs: none
+  - Acceptance: workflow validates required secrets if any; package listed in publish job graph
+
+- [x] **Task 5.3**: Positioning row (when Complete)
+  - Delivers: `docs/explanation/positioning.md` Celery/ActiveJob cell updated only when IP header is **Complete**
+  - Files: `docs/explanation/positioning.md`
+  - Blocked by: 5.1 and all prior acceptance criteria
+  - Skills: `update-docs`
+  - Docs: positioning
+  - Acceptance: row no longer says Not shipped