@terreno/mcp 57.15.0 → 57.16.2

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

@@ -0,0 +1,219 @@
+# Task List: Examples, Demo, and Test Coverage
+
+See: [`docs/implementationPlans/examples-demo-coverage.md`](../implementationPlans/examples-demo-coverage.md)
+
+**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
+
+- Derive the missing-component list from `ui/src/index.tsx` at implementation time. The list in the IP is a snapshot and will be stale.
+- When a component turns out to be hard to demo because of a bug, fix the bug and note it — that is a valuable side effect of this work, not a distraction.
+- Per IP decision E4, enforce the existing 95% threshold immediately. Packages below threshold must catch up before CI passes — do not introduce a ratchet floors file.
+- Follow the existing story conventions: read several files in `demo/stories/` first and match their structure, and use only `@terreno/ui` components inside stories.
+- Run `bun run lint`, `bun run demo:compile`, and `bun run ui:test` before each commit.
+
+## Phase 1: Demo coverage — audit and P0
+
+- [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.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.
+
+- [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.
+
+- [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
+  - Acceptance: `bun run --filter 'terreno-demo' test:ci` runs real tests and passes; deliberately breaking one story's props makes it fail; the test iterates the registered stories rather than a hardcoded list.
+
+## Phase 2: Remaining demo 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.
+
+- [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
+  - Acceptance: `bun run check:demo-coverage` passes with no unstoried, unallowlisted components; every allowlist entry has a specific reason.
+
+## Phase 3: Coverage enforcement
+
+- [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.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.
+
+- [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%.
+
+- [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
+  - Acceptance: `bun run check-coverage` (or per-package equivalent) passes at 95% for every published package.
+
+## Phase 4: 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.
+
+- [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
+  - Acceptance: the badge renders and reflects real coverage; the contributing section explains the 95% threshold and gives the local command.
+
+## Phase 5: Example feature matrix
+
+- [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: 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.
+
+- [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.
+
+Recorded gaps (2026-09-11): AI structured output → [#1010](https://github.com/TerrenoLabs/terreno/issues/1010); generic background jobs → [#1188](https://github.com/TerrenoLabs/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
+  - Acceptance: both the contributing guide and the PR template reference the requirement; the matrix is linked from the explanation index.

package/src/docs/versioned/57.15.0/tasks/feature-flags-openfeature.md

@@ -0,0 +1,79 @@
+# Feature Flags → OpenFeature — Task List
+
+**Status:** Closed (2026-08-25) — IP complete; `@terreno/feature-flags` and `@terreno/rtk` ship on OpenFeature. The two open boxes are verification steps (SDK regen, full workspace run) that landed with the merge.
+
+See `docs/implementationPlans/feature-flags-openfeature.md` for full details.
+
+## Phase 0: Catalog & deps
+
+- [x] **0.1** Add `@openfeature/server-sdk`, `@openfeature/web-sdk`, `@openfeature/react-sdk`, `@openfeature/core` to the root `package.json` `catalog` (pin minor; check latest at time of work). Verify with `bun install` from root.
+
+## Phase 1: Backend OpenFeature integration
+
+- [x] **1.1** Add `@openfeature/server-sdk` (catalog version) to `feature-flags/package.json` dependencies. Run `bun install`.
+- [x] **1.2** Add `defaultVariant` field to `FeatureFlag` schema (`feature-flags/src/featureFlagModel.ts`) with description and validation. **No getter** — use a `pre("save")` hook that populates `defaultVariant` when undefined (boolean → "off"; variant → first variant key). Validation: if set, boolean must be `"on"`/`"off"`; variant must be one of `variants[].key`. Add `defaultVariant` to `featureFlagAdminConfig.listFields`.
+- [x] **1.3** Update `FeatureFlagDocument` type in `feature-flags/src/types.ts` with optional `defaultVariant`. Add `FlagDefinition` and `FlagConfigurationResponse` interfaces.
+- [x] **1.4** Create `feature-flags/src/openFeatureProvider.ts` exporting `MongoFeatureFlagProvider` implementing OpenFeature's `Provider` interface. Use `findOneOrNone` (per repo rule — never `findOne`). Returns `FLAG_NOT_FOUND` / `TYPE_MISMATCH` `ResolutionDetails` shapes for missing or wrong-type flags. Delegates the targeting math to existing `evaluateFlag()`.
+- [x] **1.5** Update `FeatureFlagsApp.register()` (`feature-flags/src/featureFlagsApp.ts`): construct provider, call `OpenFeature.setProvider(domain, provider)` (default domain `"feature-flags"`), register new `/flagConfiguration` route, keep `/evaluate` with `Deprecation: true` + `Sunset: <90d>` headers + one-shot warn log.
+- [x] **1.6** Add `buildFlagDefinition(flag, targetingKey, user, segments)` helper. **Critical filter**: `/flagConfiguration` matches today's `evaluateAllFlags` filter (`archived: $ne true, enabled: true`) — disabled flags are omitted entirely. Every returned `FlagDefinition` has `disabled: false`.
+- [x] **1.7** Update `FeatureFlagsOptions` type (`feature-flags/src/types.ts`) to add `liveUpdates` and `openFeatureDomain` fields.
+- [x] **1.8** Update `feature-flags/src/index.ts` to export `MongoFeatureFlagProvider`, `FlagDefinition`, `FlagConfigurationResponse`.
+- [x] **1.9** Add `feature-flags/src/tests/openFeatureProvider.test.ts` covering: boolean and variant resolution; disabled flag returns default + reason "DISABLED"; `TYPE_MISMATCH` on wrong-type call; `FLAG_NOT_FOUND` on missing flag; rule-match path; segment-match path; deterministic-hash path; missing `targetingKey`; variant default fallback; `resolveNumberEvaluation` and `resolveObjectEvaluation` return `FLAG_NOT_FOUND`.
+- [x] **1.10** Extend `feature-flags/src/tests/featureFlagsApp.test.ts`: `/flagConfiguration` returns the right shape for both flag types; **explicitly verifies disabled flags are OMITTED**; verifies `defaultVariant` flows through; verifies `/evaluate` still works AND now includes `Deprecation` + `Sunset` headers. Add `featureFlagModel.test.ts` (or extend existing tests) with: legacy doc (no `defaultVariant`) can be saved and the hook populates a default; explicit `defaultVariant: "on"` on boolean passes; `defaultVariant: "bad"` on boolean is rejected.
+- [x] **1.11** Run `bun run --filter=@terreno/feature-flags compile test lint`. Fix issues.
+
+## Phase 2: Frontend OpenFeature integration
+
+- [x] **2.0 (blocking spike)** Verify `@openfeature/react-sdk` works under React Native. Write a tiny `bun test` using `@testing-library/react-native` that wraps a component in `<OpenFeatureProvider>` with a `TypedInMemoryProvider` and asserts `useBooleanFlagValue("k", false)` returns `true` after `PROVIDER_READY`. If it fails on RN, fall back to importing only from `@openfeature/web-sdk` and writing a thin React adapter inside `@terreno/rtk` that uses `useSyncExternalStore` against the OF client's event emitter. Do not proceed to 2.1 until this is green.
+- [x] **2.1** Add `@openfeature/web-sdk` + `@openfeature/react-sdk` as **peerDependencies** (NOT direct deps) in `rtk/package.json`. Add `@openfeature/core` as a direct dep for types. Run `bun install` from root.
+- [x] **2.2** Create `rtk/src/useTerrenoFeatureFlags.ts`. Critical behaviors:
+  - RTK Query endpoint cache key includes `userId` so user switching invalidates cache.
+  - On data success, `await OpenFeature.setProvider(domain, new TypedInMemoryProvider(data))`; subscribe to `PROVIDER_READY` via `client.addHandler`.
+  - `isLoading` stays `true` until BOTH RTK has data AND `PROVIDER_READY` has fired (gated by a ref-tracked boolean).
+  - On `userId` change: `OpenFeature.setContext(domain, {targetingKey: userId})` BEFORE the refetch resolves.
+  - Module-level ref counter for provider lifetime; do not clear provider on individual unmount; clear only when count returns to zero (last consumer leaves).
+  - StrictMode safety: ref tracks in-flight `setProvider` promise to dedupe double-effect.
+  - If `options.socket` is provided, subscribe to `socketEventName ?? "featureFlagsChanged"` → `refetch()`. Cleanup on unmount.
+  - Return `{flags, isLoading, error, refetch, client}`.
+- [x] **2.3** Rewrite `rtk/src/useFeatureFlags.ts` as a BC wrapper over `useTerrenoFeatureFlags`. Preserve overloaded signature (`string | UseFeatureFlagsOptions`). `getFlag` uses `client.getBooleanValue(key, false)`. `getVariant` returns `null` when `!flags[key]` (the flag is disabled/missing — disabled flags are filtered out of `/flagConfiguration`); otherwise returns `client.getStringValue(key, "") || null`. Build `flatFlags: Record<string, boolean | string | null>` from the raw `FlagConfiguration` map by projecting each `FlagDefinition`: boolean → `variants[defaultVariant]`, variant → `defaultVariant`. Add explicit type tests.
+- [x] **2.4** Update `rtk/src/index.ts` to export `useTerrenoFeatureFlags` and its types. Do **not** re-export OpenFeature hooks (consumers add `@openfeature/react-sdk` directly).
+- [x] **2.5** Update `rtk/src/useFeatureFlags.test.ts` to match the new wire shape. Cover: legacy options shape (string), modern options shape (object), `skip`, `getFlag`/`getVariant` for boolean and variant flags, `null` on disabled/missing, timing logs preserved, **snapshot test** locking the `flatFlags` projection so `profile.tsx`'s render output is byte-identical to before.
+- [x] **2.6** Add `rtk/src/useTerrenoFeatureFlags.test.ts` covering: provider is set on success; `isLoading` stays `true` until `PROVIDER_READY`; domain isolation (default provider not affected); refetch path; no-op when `skip: true`; `userId` change triggers context + refetch + provider replacement; StrictMode double-mount does not double-set provider; ref count prevents premature provider clearing; socket event triggers refetch.
+- [x] **2.7** Run `bun run --filter=@terreno/rtk compile test lint`. Fix issues.
+
+## Phase 3: Live updates (opt-in)
+
+- [x] **3.1** In `FeatureFlagsApp.register()`, when `options.liveUpdates?.socketIoServer` is provided (accept either a value or a `() => Server | null` getter — example-backend's `io` is lazily initialized), start `FeatureFlag.watch([], {fullDocument: "updateLookup"})`. On each change, emit `featureFlagsChanged` (configurable event name) plus call `provider.emitConfigurationChanged()`. Log on stream `error`; one auto-reconnect attempt, then disable + warn.
+- [x] **3.2** Add `feature-flags/src/tests/featureFlagsApp.liveUpdates.test.ts`. Test approach: **mock `FeatureFlag.watch`** to return a fake `EventEmitter` with the change-stream interface (`on`, `close`). The tests do NOT spin up a replica-set Mongo. Cover: emission on insert/update/delete (via emitting fake change events), custom event name, error handler logs a warn, double-error disables the stream.
+- [x] **3.3** In `useTerrenoFeatureFlags`, when `options.socket` is provided, subscribe to `options.socketEventName ?? "featureFlagsChanged"` and call `refetch()` on each event. Cleanup on unmount. Acknowledge that the emit is global broadcast (all connected clients) — no PII in the payload.
+- [x] **3.4** Add a test in `useTerrenoFeatureFlags.test.ts` proving: when a fake `EventEmitter` socket emits the event, the hook refetches and OF consumers re-render.
+- [x] **3.5** Document the Mongoose replica-set requirement (production must use a replica set, including single-node replica set) and Socket.io wiring in `docs/how-to/add-feature-flags.md` (new "Live updates" section). Also document the broadcast scope (flag-key payload visible to every authenticated socket) — acceptable since flag keys ship to every authed client via `/flagConfiguration` anyway.
+
+## Phase 4: Example apps + docs + SDK regen
+
+- [x] **4.1** Update `example-backend` `FeatureFlagsApp` construction to pass `liveUpdates: {socketIoServer: () => io}` — use a getter, since `example-backend/src/websockets.ts:24` initializes `io` lazily during `connectToWebsockets`.
+- [x] **4.2** Update `example-backend/src/scripts/seed-feature-flags.ts`: add `defaultVariant` to each `SEED_FLAGS` entry (`"off"` for boolean flags; for the `profile-layout` variant flag, `"compact"`). **Bump the seed**: either add a `seedVersion` field to FeatureFlag (skip if too invasive) OR add an idempotent "patch missing defaultVariant" upsert at the top of the script that updates existing docs in dev DBs to populate the new field. Document the dev-db backfill in the migration note.
+- [x] **4.3** Update `example-frontend/app/_layout.tsx` to wrap children in `<OpenFeatureProvider domain="feature-flags">` and call `useTerrenoFeatureFlags(terrenoApi, {socket, userId})` once user is authenticated.
+- [x] **4.4** Update `example-frontend/app/(tabs)/profile.tsx`: add a small section that uses `useBooleanFlagDetails("dark-mode-toggle", false)` and renders `reason` alongside value — verifies OF metadata is plumbed through and proves the `reason` field shape downstream.
+- [x] **4.5** Add `example-frontend/types/openfeature.d.ts` demonstrating the type-safe flag keys augmentation. Reference it from the docs.
+- [ ] **4.6** Regenerate frontend SDK: `cd example-frontend && bun run sdk`. Verify the new endpoint is in `openApiSdk.ts` and document that consumers should NOT call the generated hook directly; use `useTerrenoFeatureFlags`/`useFeatureFlags` instead.
+- [x] **4.7** Update `docs/reference/feature-flags.md`: new endpoint shape, `MongoFeatureFlagProvider` export, `defaultVariant` field semantics, recommended OF hooks for new code, BC notes, **number/object flag types not supported** (always returns default), **type-safe flag keys drift warning**, dev-db backfill note for existing seeded flags.
+- [x] **4.8** Update `docs/how-to/add-feature-flags.md`: recommend OF hooks for new code; show `useFeatureFlags` only in a "BC / migration" section.
+- [x] **4.9** Add a short note at the top of `docs/implementationPlans/feature-flags.md` linking to this new IP.
+- [x] **4.10** Add `example-frontend/e2e/feature-flags.spec.ts` Playwright test:
+  - Login as admin
+  - PATCH a flag via `/feature-flags/flags/:id` (e.g., toggle `enabled` on `todo-summary-card`)
+  - Within ~5s, assert the example-frontend's todos screen shows/hides the summary card accordingly **without** a page reload
+  - Verifies the full live-update loop (change stream → socket emit → hook refetch → OF re-render)
+  - Skip the test if the test environment does not have a Mongo replica set (use `test.skip` with a clear message) so CI doesn't fail when devs run without one.
+- [ ] **4.11** Run full workspace check: `bun run lint && bun run compile && bun run test`. Run example stack manually (`bun run backend:dev` + `bun run frontend:web`) and verify the profile screen shows flags identical to before.
+
+## Definition of Done
+
+- All workspace tests pass.
+- `example-frontend` runs end-to-end with seeded flags, showing identical values to before the migration.
+- Admin edits to a flag (via the admin panel) propagate to an open example-frontend session within ~1 second without a manual refresh.
+- A consumer using only `useFeatureFlags(api)` requires zero code changes.
+- A consumer can now also use `useBooleanFlagValue("key", false)` directly from `@openfeature/react-sdk`.
+- Type-safe flag keys augmentation is documented and demonstrated in `example-frontend`.
+- The legacy `/evaluate` endpoint still works, returns the old shape, and includes a `Deprecation` header.

package/src/docs/versioned/57.15.0/tasks/feature-flags.md

@@ -0,0 +1,25 @@
+# Feature Flags — Task List
+
+**Status:** Closed (2026-08-20) — IP deferred; superseded by [feature-flags-openfeature.md](./feature-flags-openfeature.md). Open tasks below will not be executed.
+
+## Phase 1: Backend + Evaluation Engine
+
+- [ ] **Task 1.1**: Create `feature-flags/` package with FeatureFlag model (including archived field)
+- [ ] **Task 1.2**: Implement FeatureFlagsApp plugin with modelRouter CRUD
+- [ ] **Task 1.3**: Implement evaluation engine (field rules with dot notation, segment rules, deterministic hashing for boolean rollout and variant assignment)
+- [ ] **Task 1.4**: Implement `/evaluate` and `/segments` custom endpoints
+- [ ] **Task 1.5**: Write tests for evaluation logic
+- [ ] **Task 1.6**: Integrate with example-backend
+
+## Phase 2: Frontend Hook
+
+- [ ] **Task 2.1**: Add `useFeatureFlags()` hook to `@terreno/rtk`
+- [ ] **Task 2.2**: Export from rtk index
+
+## Phase 3: Example App Integration
+
+- [ ] **Task 3.1**: Wire up FeatureFlagsApp in example-backend, register model in AdminApp
+- [ ] **Task 3.2**: Add sample flags and use `useFeatureFlags()` in example-frontend
+- [ ] **Task 3.3**: Regenerate SDK
+
+See `docs/implementationPlans/feature-flags.md` for full details on each task.

package/src/docs/versioned/57.15.0/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/TerrenoLabs/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/57.15.0/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/57.15.0/tasks/inbound-webhooks.md

@@ -0,0 +1,77 @@
+# Tasks: Inbound webhook framework
+
+IP: [inbound-webhooks.md](../implementationPlans/inbound-webhooks.md)  
+**Closes:** https://github.com/TerrenoLabs/terreno/issues/1172
+
+**Feature profile:** false (full IP)
+
+## Phase 1 — Tracer (raw body, HMAC, memory claim)
+
+- [x] **Task 1.1**: Raw-body capture on TerrenoApp parsers
+  - Delivers: JSON (and urlencoded) parse stores `req.rawBody` as a `Buffer`; existing JSON routes still work
+  - Files: `api/src/webhooks/rawBody.ts`, `api/src/terrenoApp.ts`, `api/src/webhooks/rawBody.test.ts`
+  - Blocked by: none
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: stub one sentence in `docs/reference/api.md` that inbound routes will use `rawBody`
+  - Acceptance: bun test — parsed `req.body` matches today; `rawBody` equals the sent bytes; mutating parsed JSON does not change `rawBody`
+
+- [x] **Task 1.2**: `WebhooksApp` + HMAC verifier + memory idempotency
+  - Delivers: `new WebhooksApp().route({path, source, verify, eventId, handler})`; `app.register(webhooks)` mounts anonymous POST; valid HMAC 200 once; bad/missing signature 401 `webhook-signature-invalid`; duplicate `eventId` 200 `duplicate: true` without second handler; handler throw 500 then retry succeeds; path not in `/openapi.json`
+  - Files: `api/src/webhooks/webhooksApp.ts`, `api/src/webhooks/verifiers/hmac.ts`, `api/src/webhooks/idempotency/memoryStore.ts`, `api/src/webhooks/webhooksApp.test.ts`, `api/src/index.ts`, `api/src/terrenoPlugin.ts` (early capture hook if needed)
+  - Blocked by: 1.1
+  - Skills: `terreno-backend-api`
+  - Docs: stub `WebhooksApp` example in `docs/reference/api.md`
+  - Acceptance: bun + supertest cover the Goal tracer in the IP; timing-safe compare; empty `eventId` skips claim and warns; `webhooks.claim` is callable from a handler for nested ids
+
+## Phase 2 — Provider verifiers + Mongo receipts
+
+- [x] **Task 2.1**: Stripe + Twilio + SendGrid verifiers
+  - Delivers: `stripeSignature`, `twilioSignature`, `sendgridEventSignature` helpers; Stripe and SendGrid timestamps outside tolerance fail; Twilio form-urlencoded verifies; SendGrid ECDSA with a test keypair
+  - Files: `api/src/webhooks/verifiers/stripe.ts`, `twilio.ts`, `sendgrid.ts`, `verifiers/*.test.ts`
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`
+  - Docs: verifier table in `docs/how-to/inbound-webhooks.md` (create page if 3.1 not started)
+  - Acceptance: fixture tests only (no network); mutated payload 401
+
+- [x] **Task 2.2**: Mongo idempotency store
+  - Delivers: `idempotency: {store: "mongo", ttlDays?}` uses mongoose connection and `webhookReceipts` unique `(source, eventId)` + TTL; claim-before-handler; release on throw
+  - Files: `api/src/webhooks/idempotency/mongoStore.ts`, schema/types if a model is used, tests via `@terreno/test`
+  - Blocked by: 1.2
+  - Skills: `mongoose-schema-safety`, `backend-test-env`
+  - Docs: collection / TTL note on the how-to
+  - Acceptance: two sources can share an event id string; TTL index present; no public modelRouter
+
+## Phase 3 — Example HMAC + comms routes
+
+- [x] **Task 3.1**: example-backend HMAC demo
+  - Delivers: `POST /webhooks/example` registered only when `WEBHOOK_SECRET` is set; handler logs `[Webhook]` and returns `{received: true}`
+  - Files: `example-backend/src/server.ts` (or small `webhooksExample.ts` + test)
+  - Blocked by: 1.2
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: none (4.1)
+  - Acceptance: bun test — unset secret → no route (404); set secret → signed POST 200
+
+- [x] **Task 3.2**: Twilio status + inbound routes on CommsApp
+  - Delivers: `CommsApp({webhooks, webhookPublicUrl, sms: TwilioSmsProvider})` mounts `POST {basePath}/webhooks/twilio/status` and `.../inbound`; Twilio verifier; status mapping per comms-adapter-twilio-sms table including `ErrorCode`; STOP/START → `recordOptOut`; `statusCallbackUrl` defaults to the public status URL; skip routes and `logger.error` if auth token missing
+  - Files: `comms/src/commsApp.ts`, `comms/src/adapters/twilioSms.ts` (or `comms/src/webhooks/twilio.ts`), tests, `example-backend/src/server.ts` (pass `webhooks` when SMS adapter is on)
+  - Blocked by: 2.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: paths in `docs/reference/comms.md` (full page in 4.1)
+  - Acceptance: bun tests — signed delivered/failed fixtures update `CommsMessage`; unsigned 401; STOP fires `onOptOut` `reason: "sms-stop"`; no `webhooks` option → those paths 404
+
+- [x] **Task 3.3**: SendGrid Event Webhook on CommsApp
+  - Delivers: `CommsApp({webhooks, mail: SendGridMailProvider})` mounts `POST {basePath}/webhooks/sendgrid`; ECDSA verifier; per-`sg_event_id` `webhooks.claim`; mapping per comms-adapter-sendgrid table; correlate `sg_message_id` prefix to stored `x-message-id`; `SENDGRID_WEBHOOK_VERIFICATION_KEY` (or constructor `webhookVerificationKey`); skip + `logger.error` if key missing
+  - Files: `comms/src/commsApp.ts`, `comms/src/adapters/sendgrid.ts` (or `comms/src/webhooks/sendgrid.ts`), tests, `example-backend/src/server.ts`
+  - Blocked by: 2.1
+  - Skills: `terreno-backend-api`, `backend-test-env`
+  - Docs: path + key in `docs/reference/comms.md` / env table (4.1)
+  - Acceptance: bun tests — signed delivered/bounce/spamreport fixtures; unsigned 401; duplicate `sg_event_id` no second `recordDeliveryEvent`; batch of two events both applied
+
+## Phase 4 — Docs and seed
+
+- [x] **Task 4.1**: Diátaxis + changelog + agent docs
+  - Delivers: how-to, reference, replace auth HMAC snippet, env table (`SENDGRID_WEBHOOK_VERIFICATION_KEY`, `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL`), comms webhook section, custom-routes skill, api rule, unreleased changelog, seed IP/task URLs, adapter Phase 2 ownership note, `bun run rules` / `skills:sync` if rulesync changed
+  - Files: `docs/how-to/inbound-webhooks.md`, `docs/how-to/README.md`, `docs/reference/api.md`, `docs/reference/comms.md`, `docs/explanation/authentication.md`, `docs/reference/environment-variables.md`, `docs/explanation/roadmap-seed-issues.md`, `docs/implementationPlans/billing-stripe.md`, `docs/implementationPlans/comms-adapter-twilio-sms.md`, `docs/implementationPlans/comms-adapter-sendgrid.md`, `.rulesync/skills/terreno-backend-api/references/custom-routes.md`, `.rulesync/rules/api/00-api.mdc`, `.rulesync/rules/comms/00-comms.md`, `changelog/unreleased/inbound-webhooks.md`
+  - Blocked by: 1.2 (content must match 2.x and 3.x)
+  - Skills: `update-docs`, `update-agent-docs`
+  - Acceptance: a stranger can register HMAC, Twilio, and SendGrid routes from the how-to/comms reference without reading this IP; `bun run website:build`; old `JSON.stringify(req.body)` snippet gone

package/src/docs/versioned/57.15.0/tasks/infra-mcp.md

@@ -0,0 +1,43 @@
+# Tasks: Infrastructure MCP server (`@terreno/infra-mcp`)
+
+Plan: [docs/implementationPlans/infra-mcp.md](../implementationPlans/infra-mcp.md)
+Status: Blocked — Phase 1 RBAC wiring depends on the RBAC module PR ([rbac-permissions.md](../implementationPlans/rbac-permissions.md)). Scaffold/adapter tasks marked (unblocked) can start now.
+
+## Phase 1 — Read-only core
+
+- [ ] (unblocked) Scaffold `infra-mcp/` workspace package: package.json (catalog deps), tsconfig, biome, bun test setup, root workspace + catalog entries (zod 4, `@modelcontextprotocol/server`, `@better-auth/oauth-provider`, `@better-auth/mcp`)
+- [ ] (unblocked) `src/config.ts`: `defineInfraMcp` config schema (zod), secret resolution (env/Secret Manager), boot validation
+- [ ] (unblocked) `src/server.ts`: Express/TerrenoApp server with SDK v2 `/mcp` endpoint (`createMcpHandler`, `legacy: "stateless"`, `toNodeHandler`) + `/health`
+- [ ] (unblocked) `src/auth.ts`: Better Auth OAuth 2.1 setup — authorization server, RFC 9728 protected-resource metadata, bearer verification middleware; login page flow verified with Cursor and Claude Code
+- [ ] `src/access.ts`: `infraStatements`, default roles (`infra-readonly`, `infra-operator`), `createAccess` wiring, `Mcp-Name`-keyed authz middleware, per-user filtered `tools/list` (**blocked on RBAC PR**)
+- [ ] `src/models/infraAuditLog.ts` + audit middleware around `tools/call` (statuses: allowed/denied/confirmed/rejected/error; per-tool arg redaction)
+- [ ] (unblocked) Integration adapter types + registry (`src/integrations/types.ts`, `registry.ts`)
+- [ ] (unblocked) GCP native adapter (ADC): `gcp_query_logs`, `gcp_list_log_names`, `gcp_query_metrics`, `gcp_list_error_groups`, `gcp_list_cloud_run_services`, `gcp_get_cloud_run_service`
+- [ ] (unblocked) Sentry native adapter (REST + static token): `sentry_search_issues`, `sentry_get_issue`, `sentry_list_issue_events`, `sentry_get_event`
+- [ ] (unblocked) Mongo native adapter (read URI): `mongo_list_collections`, `mongo_collection_schema`, `mongo_find`, `mongo_aggregate` (reject `$out`/`$merge`). Extract the shared read-query/schema logic from `mcp-server/src/local/tools/databaseQuery.ts` + `databaseSchema.ts` into a reusable module both packages import — do not fork copies into infra-mcp (per architectural review)
+- [ ] Admin panel registration (`@terreno/admin-backend`): Users, InfraAuditLog (read-only)
+- [ ] Terraform: `infra_mcp_service` Cloud Run module instance, Artifact Registry, runtime SA with viewer/logging IAM only
+- [ ] Tests: authz matrix (role × tool × tools/list filtering), adapter handlers, audit records, legacy-client fallback
+- [ ] Deploy + end-to-end verification from a real MCP client; docs: `.cursor/rules/infra-mcp/00-infra-mcp.mdc`, AGENTS.md/CLAUDE.md package lists
+- [ ] Roadmap: open the tracking issue from [roadmap-seed-issues.md](../explanation/roadmap-seed-issues.md#infra-mcp) once the IP is Approved, add it to the Terreno Roadmap board, and register `@terreno/infra-mcp` → `area:mcp` in `scripts/issueAreaLabels.ts` + the bug-report package dropdown when the package lands
+
+## Phase 2 — Write tier + machine callers
+
+- [ ] `confirmWrite` elicitation wrapper; fail-closed behavior for clients without elicitation support
+- [ ] Config override (`confirmWrites: false`) gated by `infra:writeUnconfirmed`; tests for both paths
+- [ ] Write tools: `sentry_resolve_issue`, `sentry_assign_issue`, `gcp_rollback_cloud_run_revision`, `gcp_update_cloud_run_traffic`, `mongo_update_one`, `mongo_delete_one`; widen runtime SA IAM minimally
+- [ ] Service tokens: spike Better Auth `apiKey` plugin; fallback `ServiceToken` model; machine users (`isServiceAccount`) with role assignment; admin surface (token shown once)
+- [ ] Cloud agent migration: `INFRA_MCP_URL` + service token in agent environments; verify log-digging flows; remove `GCP_SA_*` injection; update AGENTS.md Cursor Cloud instructions
+
+## Phase 3 — Proxied adapters + remaining vendors
+
+- [ ] `ProxiedAdapter`: `@modelcontextprotocol/client` (stdio + HTTP), deny-by-default `allowedTools` with mandatory tier annotations, tool name prefixing, upstream lifecycle management
+- [ ] Reference proxied integration (`@sentry/mcp-server` stdio or `@google-cloud/observability-mcp`) with parity tests against native tools
+- [ ] Expo/EAS native adapter (`EXPO_TOKEN`): build status, update status, submission status (read); trigger tools deferred to write expansion
+- [ ] Vercel native adapter (API token): deployments, logs, project info (read)
+
+## Phase 4 — OSS packaging
+
+- [ ] `defineInfraMcp` config reference + quickstart docs (website); one-man-shop deploy path (container anywhere)
+- [ ] Publish `@terreno/infra-mcp`; changelog + upgrade notes
+- [ ] Dogfood writeup: our deployment as the reference architecture