@terreno/mcp 57.20.0 → 57.22.0

package/src/docs/versioned/57.21.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.21.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.21.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.21.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.21.0/tasks/infra-mcp.md

@@ -0,0 +1,44 @@
+# 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 (one team token per team, project→team by lookup): `vercel_list_projects`, `vercel_list_deployments`, `vercel_runtime_logs` via `POST /v1/observability/events` (read); `vercel.read` RBAC scope limiting machine users to their own projects. Port from the hive dogfood implementation
+- [ ] Per-sandbox machine users for orchestrated agents: mint user + service token at sandbox create, revoke at teardown; per-resource allow-list consumed by integration scopes
+
+## 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

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

@@ -0,0 +1,144 @@
+# Tasks: Durable background jobs
+
+IP: [job-queues.md](../implementationPlans/job-queues.md)  
+**Closes:** https://github.com/TerrenoLabs/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

package/src/docs/versioned/57.21.0/tasks/knip-cleanup.md

@@ -0,0 +1,146 @@
+# Task List: Remove the Knip baseline
+
+See: [`docs/implementationPlans/knip-cleanup.md`](../implementationPlans/knip-cleanup.md)
+
+**Status:** Complete  
+**RTK deprecation flag:** None
+
+## Instructions for the implementing agent
+
+- Re-run Knip (JSON reporter, default + production, same as `scripts/static-analysis/full.ts`) at the start of every task. The IP inventory is a snapshot, not the live list.
+- Disposition order: **entry → ignore (with comment) → unexport → delete**. Never `knip --fix`.
+- Do not delete the old Knip baseline until Task 6.1. Earlier tasks must keep `bun run analyze:full` green while the live finding count falls.
+- Do not remove symbols from published package public entries (`src/index.ts` / `src/index.tsx` / `package.json` `exports`).
+- Do not remove Expo autolink, native, or Metro packages from `demo`, `admin-spa`, `example-frontend`, or `ui` `package.json` because Knip cannot see them.
+- Tests: `bun test --only-failures` on the closest package; after config edits, `bun test scripts/static-analysis/lib.test.ts`.
+- Supporting skills: `update-docs`. UI deletes also use `verify-ui-changes`.
+
+### Phase 1: Entry graph
+
+- [x] **Task 1.1**: Register isolated suites and repo script tests as Knip entries
+  - Delivers: `*.isolated.ts(x)` and `scripts/**/*.test.ts` (plus `scripts/static-analysis/lib.test.ts`, `.github/scripts/*.test.ts`) stop reporting as unused files
+  - Files: `knip.jsonc`, `docs/explanation/static-analysis.md` (entry-graph section: isolated files and `scripts/` tests are first-class entries)
+  - Blocked by: none
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: live default Knip report has no `files` finding whose path contains `.isolated.` or `scripts/` + `.test.`; `bun run analyze:full` exits 0; docs name this entry rule
+
+- [x] **Task 1.2**: Put mcp-server tests back on the Bun plugin
+  - Delivers: `mcp-server/src/__tests__/**` are in the graph (today `workspaces.mcp-server.bun: false` because Knip 6.34 wants `test.preload` as an array)
+  - Files: `knip.jsonc` and/or `mcp-server/package.json` (`test.preload` array form if required)
+  - Blocked by: none
+  - Docs: none beyond a comment in `knip.jsonc`
+  - Acceptance: no default `files` findings under `mcp-server/src/__tests__/`; mcp `bun test` still runs; `analyze:full` exits 0
+
+- [x] **Task 1.3**: Register codegen, Metro stubs, Playwright, fingerprint, and Docusaurus theme entries
+  - Delivers: tool-owned files are entries instead of “unused files”: `openapi-config.ts`, `comms-openapi-config.ts`, `jspdf-native-stub.js`, `fingerprint.config.js`, `playwright.circleci.config.ts`, `ui/babel.config.js`, `website/src/theme/**`, `scripts/ci/prepare-package-publish.mjs`, `scripts/planning/fingerprintRisk.ts`, `scripts/planning/updateDependenciesPr.ts` if they are invoked from `package.json` / CI
+  - Files: `knip.jsonc`; `package.json` scripts only if an entry name is wrong
+  - Blocked by: none
+  - Docs: `docs/explanation/static-analysis.md` — table row for Metro stubs / codegen configs
+  - Skills: `update-docs`
+  - Acceptance: those paths are absent from live `files` findings or listed as `entry`; comments explain each ignore glob if an ignore is used instead; `analyze:full` exits 0
+
+- [x] **Task 1.4**: Ignore generated Expo skill script copies; keep the canonical copy in graph if it is real
+  - Delivers: duplicate `expo-cicd-workflows/scripts/{fetch,validate}.js` under `.agents/`, `.claude/`, `.cursor/`, `.devin/`, `.github/`, `.rulesync/`, `skills/` do not appear as unused files
+  - Files: `knip.jsonc` ignore globs; confirm canonical path (`.rulesync/skills/...` or `skills/...`)
+  - Blocked by: none
+  - Docs: one sentence in `docs/explanation/static-analysis.md` that generated skill copies are ignored
+  - Skills: `update-docs`
+  - Acceptance: no `files` findings whose path contains `expo-cicd-workflows/scripts/`; `analyze:full` exits 0
+
+### Phase 2: Documented ignores (cannot fix)
+
+- [x] **Task 2.1**: Ignore Expo autolink / Metro / font / native `dependencies` Knip cannot see
+  - Delivers: `ignoreDependencies` (or workspace-scoped equivalent) for the live unused-deps list on `demo`, `admin-spa`, `example-frontend`, `ui` that exist for autolinking or Metro, including `jspdf` unlisted from metro stubs and `expo-system-ui` / `expo-updates` unlisted from `app.json`
+  - Files: `knip.jsonc`, `docs/explanation/static-analysis.md` (why these stay in `package.json`)
+  - Blocked by: Task 1.3
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: those packages are gone from live `dependencies` / `unlisted` findings; each ignore has a comment; no app/`ui` `package.json` lost an Expo native dep; `analyze:full` exits 0
+
+- [x] **Task 2.2**: Ignore binaries, catalog-only, and optional peers that are real
+  - Delivers: `eas`, `maestro`, catalog `@sentry/react-native` if unused in this repo but required by the catalog contract, `admin-frontend` optional `react-native-webview`
+  - Files: `knip.jsonc`
+  - Blocked by: none
+  - Docs: comment in `knip.jsonc`; mention binaries in `docs/explanation/static-analysis.md` if not already there
+  - Skills: `update-docs`
+  - Acceptance: live report has no `binaries` / `catalog` / `optionalPeerDependencies` findings except any still destined for Task 3.1 deletion; `analyze:full` exits 0
+
+- [x] **Task 2.3**: Ignore remaining unlisted modules that are optional or type-only
+  - Delivers: honest ignores or `optionalDependencies` for `ioredis` (rate-limit redis store), `@ai-sdk/google-vertex`, `@docusaurus/plugin-content-docs`, `express` in ai tests, `@terreno/api` from `@terreno/test` if the graph cannot see the workspace package
+  - Files: `knip.jsonc` and/or the declaring `package.json` if the package should be listed instead of ignored
+  - Blocked by: Task 1.2
+  - Acceptance: Pick records in the task log each remaining unlisted name as either added to `package.json` or ignored with reason; live `unlisted` count is 0 or only items Task 3 will delete; `analyze:full` exits 0
+
+### Phase 3: Remove true unused packages
+
+- [x] **Task 3.1**: Delete unused `devDependencies` after the graph is honest
+  - Delivers: remove packages that still appear as unused `devDependencies` and are not CLIs invoked from scripts (`sinon`, `@types/sinon`, `@types/bcrypt`, `@types/cron`, leftover `typedoc`/`prettier`/`ts-node`/`tsx` only if no script references them). Keep `@rtk-query/codegen-openapi`, `@biomejs/biome`, `mongodb` as a driver for example-backend tests, etc., when a script or plugin uses them — those become entries or ignores in Phase 1–2, not deletions
+  - Files: affected `package.json` files, lockfile via `bun install`
+  - Blocked by: Task 1.1, Task 1.2, Task 1.3, Task 2.2
+  - Docs: none unless a documented install step named a removed tool
+  - Acceptance: `rg` of the repo and `package.json` scripts show no remaining reference; `bun run compile` (or package `compile`) and the package test script still pass for each touched package; live unused-devDep list for those names is empty; `analyze:full` exits 0
+
+- [x] **Task 3.2**: Remove unused runtime deps that are not Expo/autolink
+  - Delivers: example-backend / website / test / api leftovers (`clsx`, unused `lodash` in `@terreno/test`, `generaterr` / `scmp` / `@sentry/profiling-node` **only if** nothing loads them including Sentry init). If a dep is loaded via string/dynamic import, ignore it instead
+  - Files: affected `package.json`, source if an import must move
+  - Blocked by: Task 2.1, Task 3.1
+  - Acceptance: each removed name has no remaining import; package tests pass; `analyze:full` exits 0
+
+### Phase 4: Dead files
+
+- [x] **Task 4.1**: Delete in-repo-dead example-frontend modules
+  - Delivers: remove unused files Knip still reports after Phase 1 (candidates from snapshot: `hooks/useLogoutUser.ts`, `useSentryUserSetup.ts`, `useUpdateProfile.ts`, `constants/Colors.ts`, and any unused store helpers). Keep files that routes, tests, or docs still import — those need an entry or a real import
+  - Files: `example-frontend/**` listed by live Knip `files`
+  - Blocked by: Task 1.3
+  - Docs: update example-frontend docs/README only if a named file was documented
+  - Skills: `update-docs`, `verify-ui-changes` if a routed screen changes
+  - Acceptance: those paths absent from live `files` findings; `cd example-frontend && bun test` passes; if UI was unwired, login + related screen still work with artifacts under `/opt/cursor/artifacts/`
+
+- [x] **Task 4.2**: Delete or wire dead demo / example-backend / api example files
+  - Delivers: `demo/stories/PasswordField.stories.tsx` if unregistered; `demo/.eslintrc.js` if unused; `example-backend` unused scripts (`configuration-example.ts`, `seed-admin-spa-admin.ts`, `seedConsents.ts`) unless `package.json` / AdminApp should call them — then add entries; `example-backend/src/constants/index.ts` if a banned barrel leftover; `api/src/example.ts`; unused vendor `convert-yaml.js` only if nothing requires it
+  - Files: paths from live Knip `files` in those packages
+  - Blocked by: Task 1.3
+  - Docs: example-backend README / how-to if a seed script is removed or registered
+  - Skills: `update-docs`
+  - Acceptance: live `files` findings for those packages are 0 or only ignored globs; relevant `bun test` passes; `analyze:full` exits 0
+
+- [x] **Task 4.3**: Delete or keep-with-entry remaining unused files (`ui/checkDeps.js`, `processCounties.js`, `compileAuthEntry.ts`, leftover demo tests already covered)
+  - Delivers: every remaining default `files` finding is either an entry, an ignore glob with comment, or deleted
+  - Files: leftover paths from live Knip
+  - Blocked by: Task 1.1, Task 1.4, Task 4.1, Task 4.2
+  - Acceptance: live default+production `files` count is 0; `analyze:full` exits 0
+
+### Phase 5: Exports and types
+
+- [x] **Task 5.1**: Unexport unused **internal** symbols in `scripts/` and examples
+  - Delivers: after tests are in the graph, remaining unused exports/types in `scripts/`, `example-frontend/`, `example-backend/`, `demo/` that are not a public package entry become non-exported (or deleted if the whole helper is dead)
+  - Files: modules named by live `exports` / `types` findings in those trees
+  - Blocked by: Task 1.1, Task 4.1, Task 4.2
+  - Acceptance: those packages have no unused **internal** export/type findings; tests that imported the symbol still compile (they use the same module, not the export); `analyze:full` exits 0
+
+- [x] **Task 5.2**: Unexport unused **internal** symbols in published packages
+  - Delivers: same as 5.1 for `api`, `admin-frontend`, `comms`, `syncdb`, `mcp-server`, `ai`. Do **not** remove re-exports from `src/index.ts(x)`
+  - Files: internal modules named by live findings
+  - Blocked by: Task 1.2
+  - Docs: none unless a documented “internal helper” was publicized in explanation/reference — then update that page
+  - Skills: `update-docs`
+  - Acceptance: each remaining unused export/type is classified public (re-exported from the package entry) or is gone; package `bun test` / `compile` passes; `analyze:full` exits 0
+
+- [x] **Task 5.3**: Ignore leftover **public** unused exports and types
+  - Delivers: `ignoreIssues` (path-scoped `exports`/`types`) for public API unused inside this monorepo, with comments
+  - Files: `knip.jsonc`, `docs/explanation/static-analysis.md` (public API ignore rule)
+  - Blocked by: Task 5.1, Task 5.2
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: live `exports` and `types` counts are 0; no public `index` export removed; `analyze:full` exits 0
+
+### Phase 6: Remove baseline
+
+- [x] **Task 6.1**: Delete the Knip baseline and enforce zero findings directly
+  - Delivers: live default+production fingerprint set is `[]`; no Knip baseline exists; docs state that new findings are fixed or added to `knip.jsonc` with a reason
+  - Files: delete `scripts/static-analysis/knip-baseline.json`; update `docs/explanation/static-analysis.md`, `scripts/static-analysis/full.ts`, and tests
+  - Blocked by: Task 2.1, Task 2.2, Task 2.3, Task 3.2, Task 4.3, Task 5.3
+  - Docs: `docs/explanation/static-analysis.md`
+  - Skills: `update-docs`
+  - Acceptance: `test ! -e scripts/static-analysis/knip-baseline.json`; `bun run check:knip` prints no findings and exits 0; `bun run analyze:full` exits 0; static-analysis tests pass