@terreno/mcp 57.1.0 → 57.3.0

package/src/docs/versioned/next/tasks/ai-observability.md

@@ -0,0 +1,134 @@
+# Tasks: AI observability (Langfuse-light)
+
+IP: [ai-observability](../implementationPlans/ai-observability.md)
+
+Supporting skills (every task as applicable): `mongoose-schema-safety`, `terreno-backend-api`, `backend-test-env`, `ai-prompt-governance`, `update-docs`, `generate-sdk`, `verify-ui-changes`, `terreno-ui`, `terreno-data-fetching`, `building-terreno-apps`.
+
+## Phase 1 — Contracts and tracer
+
+- [ ] **Task 1.1**: Observability types + `ObservabilityApp` config validation
+  - Delivers: `ObservabilityPlugin` / sinks / `ObservabilityControlConfig`; boot throws on `experiments.primary !== datasets.primary` or `reviewQueue` ≠ `local`; throws if a primary’s plugin is missing
+  - Files: `ai/src/observability/types.ts`, `ai/src/observability/observabilityApp.ts`, `ai/src/observability/observabilityApp.test.ts`, `ai/src/index.ts`
+  - Blocked by: none
+  - Docs: stub `docs/explanation/ai-observability.md` (two planes + config errors)
+  - Acceptance: unit tests for valid local-only, both plugins + defaults, illegal mix, langfuse reviewQueue, local-off + prompts primary local
+
+- [ ] **Task 1.2**: In-memory TraceSink/ScoreSink + `AIService` emit
+  - Delivers: every `generate*` exports a trace unless `skipTrace`; sink failures logged not thrown; `AIRequest` still written; `userId`/`sessionId`/`promptRef`/`priceMap` on options
+  - Files: `ai/src/observability/memorySinks.ts`, `ai/src/service/aiService.ts`, `ai/src/types/index.ts`, `ai/src/service/aiService.test.ts`
+  - Blocked by: 1.1
+  - Docs: `docs/reference/ai.md` — `skipTrace`, `promptRef`, usage/cost fields
+  - Acceptance: tests: emit; skipTrace; throwing sink; costUsd from price map; missing model → no usd; multi-step still logs AIRequest
+
+- [ ] **Task 1.3**: GPT routes pass identity
+  - Delivers: `/gpt/prompt` sets `userId` from `req.user` and `sessionId` from body/header `x-ai-session-id` into `AIService`
+  - Files: `ai/src/routes/gpt.ts`, `ai/src/routes/gpt.test.ts` (or existing route tests)
+  - Blocked by: 1.2
+  - Docs: `docs/reference/ai.md` GPT section
+  - Acceptance: authenticated prompt produces a memory sink trace with that userId
+
+## Phase 2 — Local telemetry + prompts
+
+- [ ] **Task 2.1**: Local Mongo models for prompts + traces + spans + scores
+  - Delivers: schemas with descriptions, plugins, indexes from the IP; models registered only when local plugin constructs
+  - Files: `ai/src/observability/local/models/*.ts`, `ai/src/observability/local/types.ts`, model tests
+  - Blocked by: 1.1
+  - Docs: `docs/reference/ai.md` model tables
+  - Acceptance: save/load version immutability; unique `(promptId, label)`; findExactlyOne/findOneOrNone only
+
+- [ ] **Task 2.2**: Local `PromptRegistry` + prompt HTTP
+  - Delivers: create named prompt, immutable versions, move production/latest, compile `{{vars}}`, get by label
+  - Files: `ai/src/observability/local/promptStore.ts`, `ai/src/observability/routes/prompts.ts`, tests
+  - Blocked by: 2.1, 1.1
+  - Docs: `docs/how-to/observe-llm-calls.md` — create + pin production
+  - Acceptance: v1 unchanged after v2; get production returns v2; playground compile without new version
+
+- [ ] **Task 2.3**: Local `TraceSink`/`ScoreSink` + trace/session/user/cost HTTP
+  - Delivers: persist fan-in from ObservabilityApp; list/detail/filters; cost aggregates
+  - Files: `ai/src/observability/local/traceStore.ts`, `ai/src/observability/routes/traces.ts`, tests
+  - Blocked by: 2.1, 1.2
+  - Docs: `docs/reference/ai.md` routes
+  - Acceptance: filter user/session/prompt/minCost; nested spans round-trip; costs by model
+
+## Phase 3 — Evaluators, live sample, review
+
+- [ ] **Task 3.1**: Evaluator model + LLM-judge + code/json-assert
+  - Delivers: multidimensional scores; judge prompt from PromptRegistry production (or named constant in `prompts.ts` for the built-in judge wrapper); structured JSON via `generateJsonObject`
+  - Files: `ai/src/observability/local/evaluatorStore.ts`, `ai/src/observability/evaluate.ts`, `ai/src/service/prompts.ts` (judge wrapper constant), tests
+  - Blocked by: 2.2, 2.3
+  - Docs: explanation — dimensions; how-to — define evaluator
+  - Acceptance: numeric + boolean dimensions on one trace; judge parse failure records error score not throw to caller
+
+- [ ] **Task 3.2**: `sampleRate` live evals via BackgroundTask
+  - Delivers: default 0; >0 enqueues eval after trace export; still never throws from generate
+  - Files: `ai/src/observability/liveEval.ts`, `observabilityApp.ts`, tests
+  - Blocked by: 3.1
+  - Docs: how-to env `AI_OBS_SAMPLE_RATE`
+  - Acceptance: rate 0 → no task; rate 1 → BackgroundTask created (mock/stub runner ok)
+
+- [ ] **Task 3.3**: Local review queue API
+  - Delivers: enqueue from trace; list pending; submit scores; skip; assign
+  - Files: `ai/src/observability/local/reviewStore.ts`, `ai/src/observability/routes/review.ts`, tests
+  - Blocked by: 3.1
+  - Docs: how-to — review flow
+  - Acceptance: submit writes ScoreSink fan-out path; done item not in pending
+
+## Phase 4 — Datasets and local experiments
+
+- [ ] **Task 4.1**: Datasets + items (including from trace)
+  - Delivers: CRUD; add-from-trace copies input/output snapshot
+  - Files: dataset store + routes + tests
+  - Blocked by: 2.3
+  - Docs: how-to — gold set from traces
+  - Acceptance: item retains sourceTraceId; delete item does not delete trace
+
+- [ ] **Task 4.2**: Local ExperimentRunner always BackgroundTask
+  - Delivers: POST experiment compares 2–3 prompt versions on a dataset, runs evaluators, stores per-item results, aggregates; promote → production label
+  - Files: `ai/src/observability/local/experimentRunner.ts`, routes, tests
+  - Blocked by: 4.1, 3.1, 2.2
+  - Docs: how-to — run experiment + promote
+  - Acceptance: 1-item dataset still uses BackgroundTask; completed aggregates; promote moves label; failure sets experiment failed
+
+## Phase 5 — Langfuse adapter, OTel, admin, example
+
+- [ ] **Task 5.1**: Langfuse TraceSink + ScoreSink wrapping existing client
+  - Delivers: no second OTel SDK; best-effort; uses `getLangfuseClient()`
+  - Files: `ai/src/observability/langfuse/traceAdapter.ts`, tests (mock client)
+  - Blocked by: 1.2
+  - Docs: explanation — LangfuseApp vs ObservabilityApp
+  - Acceptance: generate with both sinks; langfuse mock throws → generate still ok; local row exists
+
+- [ ] **Task 5.2**: Langfuse PromptRegistry / DatasetStore / ExperimentRunner adapters
+  - Delivers: primaries can be `langfuse`; Terreno HTTP facade delegates; Open in Langfuse URLs on status
+  - Files: `ai/src/observability/langfuse/*.ts`, tests
+  - Blocked by: 5.1, 2.2, 4.2
+  - Docs: how-to — switch primaries via env
+  - Acceptance: prompts primary langfuse list uses client; experiments primary langfuse does not start BackgroundTask
+
+- [ ] **Task 5.3**: `OtelTraceSink` OpenInference
+  - Delivers: OTLP HTTP JSON or SDK exporter; `openinference.span.kind=LLM`; optional endpoint
+  - Files: `ai/src/observability/otel/otelTraceSink.ts`, tests with mock exporter
+  - Blocked by: 1.2
+  - Docs: how-to — Phoenix/collector endpoint
+  - Acceptance: mock exporter receives span with model + token attrs
+
+- [ ] **Task 5.4**: `admin-frontend` screens
+  - Delivers: prompts, traces, costs, evaluators, datasets, experiments, review; status chip; hide review without local; wire `customScreens`
+  - Files: `admin-frontend/src/widgets/aiObservability/*.tsx`, `builtInWidgets.ts`, `ai/src` adminContribution
+  - Blocked by: 2.2, 2.3, 3.3, 4.2
+  - Docs: `docs/reference/admin-frontend.md` screen names
+  - Acceptance: widget tests empty/loading; `verify-ui-changes` on admin (login admin, open Prompts + Traces)
+
+- [ ] **Task 5.5**: example-backend register + seed + env
+  - Delivers: local plugin on; Langfuse sinks if keys; OTel if endpoint; seed prompt/evaluator; fail-fast config
+  - Files: `example-backend/src/server.ts`, seed script, `.env.example`
+  - Blocked by: 5.1, 5.3, 2.2, 3.1
+  - Docs: how-to uses example-backend snippet
+  - Acceptance: server boots with local-only; invalid primary mix prevents listen (test or documented script)
+
+- [ ] **Task 5.6**: Docs completeness + Langfuse IP pointer + prompt-governance skill note
+  - Delivers: explanation, how-to, reference complete; `docs/implementationPlans/terreno-langfuse-integration.md` see-also; skill: registry production prompts allowed
+  - Files: docs listed in IP; `.github/skills/ai-prompt-governance/SKILL.md` (source) + `bun run skills:sync` if required
+  - Blocked by: 5.5
+  - Docs: (this task)
+  - Acceptance: a stranger can register ObservabilityApp from how-to without reading the IP

package/src/docs/versioned/next/tasks/app-mcp-server.md

@@ -0,0 +1,199 @@
+# Tasks: App MCP server
+
+See: [`docs/implementationPlans/app-mcp-server.md`](../implementationPlans/app-mcp-server.md)
+
+**Status:** Draft (Grow). Do not Pick until the IP header is **Approved**.
+
+## Instructions for the implementing agent
+
+- Load `update-docs`, `terreno-backend-api`, `backend-test-env`. For `MCPService` / RTK also `terreno-data-fetching`.
+- TDD: failing test for the primitive, then implementation.
+- After API export changes, update `docs/reference/api.md` and `docs/how-to/expose-mcp-tools.md` in the same task.
+- Run focused `bun test` in `api/` (and `ai/` / `mcp-server/` for those phases). `bun run lint` on touched packages.
+- Do not implement MCP Apps or streaming handlers.
+
+---
+
+### Phase 1: Prompts, resources, richer tools
+
+- [ ] **Task 1.1**: MCP result helper + richer custom tool types
+  - Delivers: `mcpResult.text` / `.json` / `.error`; optional `annotations`, `outputSchema`, `shouldRegister` on `registerMCPTool` without breaking existing callers
+  - Files: `api/src/mcp/result.ts`, `api/src/mcp/result.test.ts`, `api/src/mcp/types.ts`, `api/src/mcp/registry.ts`, `api/src/mcp/registry.test.ts`, `api/src/index.ts`
+  - Blocked by: none
+  - Docs: `docs/reference/api.md` (custom tool options table)
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: existing `registerMCPTool` tests pass; new test covers `shouldRegister` returning false omits the tool from `getAllMCPTools` for that user; `mcpResult.json` returns text JSON plus `structuredContent` when the SDK result type allows it
+
+- [ ] **Task 1.2**: Register and serve prompts
+  - Delivers: `registerMCPPrompt` / list / get on the default `/mcp` server
+  - Files: `api/src/mcp/prompts.ts`, `api/src/mcp/prompts.test.ts`, `api/src/mcp/server.ts`, `api/src/mcp/registry.ts`
+  - Blocked by: Task 1.1
+  - Docs: `docs/how-to/add-mcp-prompts-and-resources.md` (create; prompts section)
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: HTTP or in-process MCP client `prompts/list` includes the prompt; `prompts/get` returns messages; `shouldRegister: false` hides it; tools still list
+
+- [ ] **Task 1.3**: Register and serve resources
+  - Delivers: `registerMCPResource` / list / read on `/mcp`
+  - Files: `api/src/mcp/resources.ts`, `api/src/mcp/resources.test.ts`, `api/src/mcp/server.ts`, `api/src/mcp/registry.ts`
+  - Blocked by: Task 1.1
+  - Docs: same how-to, resources section
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: `resources/list` + `resources/read` for a `terreno://` or `app://` URI; missing URI is an MCP error; hidden resource omitted
+
+- [ ] **Task 1.4**: CRUD tool annotations
+  - Delivers: generated list/read `readOnlyHint`; delete `destructiveHint`; create/update not read-only
+  - Files: `api/src/mcp/toolGenerator.ts`, `api/src/mcp/toolGenerator.test.ts`
+  - Blocked by: Task 1.1
+  - Docs: `docs/how-to/expose-mcp-tools.md` one-line note
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: tests assert annotation flags on generated tool defs passed to `registerTool`
+
+- [ ] **Task 1.5**: Example-backend tracer primitives
+  - Delivers: one prompt + one resource next to existing custom tool; README how to list them
+  - Files: `example-backend/src/` (MCP module or next to `usersTodoStatus`), `example-backend/README.md`
+  - Blocked by: Task 1.2, Task 1.3
+  - Docs: example README only
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: booting example-backend, authenticated `prompts/list` and `resources/list` return the new names (API integration test)
+
+---
+
+### Phase 2: Named servers
+
+- [ ] **Task 2.1**: `mountMCPServer` path + include lists
+  - Delivers: second mount that only exposes named tools/prompts/resources; default `/mcp` still union
+  - Files: `api/src/mcp/server.ts`, `api/src/mcp/server.test.ts`, `api/src/terrenoApp.ts` (optional `mcpServers` or `configureApp` example)
+  - Blocked by: Task 1.2, Task 1.3
+  - Docs: `docs/how-to/expose-mcp-tools.md` named-server section; `docs/reference/api.md`
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: test app mounts `/mcp` and `/mcp/weather`; weather path lists only included names; `/mcp` still has CRUD + weather tool if globally registered
+
+- [ ] **Task 2.2**: TerrenoApp helper for extra servers
+  - Delivers: documented `configureApp` or `app.addMCPServer` so consumers do not call `mountMCPServer` internals
+  - Files: `api/src/terrenoApp.ts`, `api/src/terrenoApp.test.ts` (or server tests), `api/src/index.ts`
+  - Blocked by: Task 2.1
+  - Docs: reference + how-to
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: public method/options covered by a test that boots `TerrenoApp` and hits both paths
+
+---
+
+### Phase 3: Factories + hosted generators
+
+- [ ] **Task 3.1**: `defineMCPTool` / `defineMCPPrompt` / `defineMCPResource`
+  - Delivers: exported factories that call register functions; example-backend migrated to factories
+  - Files: `api/src/mcp/define.ts`, `api/src/mcp/define.test.ts`, `api/src/index.ts`, example-backend MCP module
+  - Blocked by: Task 1.5
+  - Docs: how-to examples switch to `defineMCP*`
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: factories are the documented API; `registerMCPTool` still exported
+
+- [ ] **Task 3.2**: Hosted `terreno_generate_mcp_tool`
+  - Delivers: `@terreno/mcp` tool that returns a `defineMCPTool` snippet from name/description/fields
+  - Files: `mcp-server/src/tools.ts`, `mcp-server` tests, `docs/reference/mcp-server.md`
+  - Blocked by: Task 3.1
+  - Docs: `docs/reference/mcp-server.md` tool table
+  - Skills: `update-docs`
+  - Acceptance: returned TypeScript typechecks against public factory types (snapshot or compile test); tool description tells agents to call this before inventing tool shapes
+
+- [ ] **Task 3.3**: Hosted `terreno_generate_mcp_prompt` and `terreno_generate_mcp_resource`
+  - Delivers: sibling generators for prompts and resources
+  - Files: `mcp-server/src/tools.ts`, tests, `docs/reference/mcp-server.md`
+  - Blocked by: Task 3.2
+  - Docs: same reference page
+  - Skills: `update-docs`
+  - Acceptance: each tool returns a snippet that matches `defineMCPPrompt` / `defineMCPResource`; tests cover required vs optional arguments / URI + mimeType
+
+---
+
+### Phase 4: Test helpers + Inspector how-to
+
+- [ ] **Task 4.1**: `invokeMCPTool` / `invokeMCPPrompt` / `readMCPResource`
+  - Delivers: helpers used by api tests; assert `isError`, text, structured JSON
+  - Files: `api/src/mcp/testHelpers.ts`, `api/src/mcp/testHelpers.test.ts`, re-export from a test-only path if consumers need it
+  - Blocked by: Task 1.2, Task 1.3
+  - Docs: how-to testing section
+  - Skills: `terreno-backend-api`, `backend-test-env`, `update-docs`
+  - Acceptance: helper test authenticates a user, calls the tracer tool, asserts JSON; unauthenticated call matches production auth rules
+
+- [ ] **Task 4.2**: MCP Inspector operator docs
+  - Delivers: copy-paste Inspector command against example-backend `/mcp` with bearer header
+  - Files: `docs/how-to/add-mcp-prompts-and-resources.md` or `docs/how-to/expose-mcp-tools.md`
+  - Blocked by: Task 1.5
+  - Docs: that how-to only
+  - Skills: `update-docs`
+  - Acceptance: command uses current example-backend URL/port; auth header documented; no vendored Inspector binary
+
+---
+
+### Phase 5: First-party client
+
+- [ ] **Task 5.1**: `MCPService` Streamable HTTP default
+  - Delivers: tools listed over HTTP against `mountMCPServer`; SSE still selectable
+  - Files: `ai/src/service/mcpService.ts`, `ai/src/service/mcpService.test.ts`, types
+  - Blocked by: Task 2.1 (server stable)
+  - Docs: `docs/reference/ai.md` if MCPService is documented there; else api/ai README
+  - Skills: `terreno-data-fetching`, `update-docs`
+  - Acceptance: test does not mock away the transport type; SSE path still unit-tested
+
+- [ ] **Task 5.2**: Client prompt + resource methods
+  - Delivers: `listPrompts` / `getPrompt` / `listResources` / `readResource` on `MCPService`
+  - Files: `ai/src/service/mcpService.ts` + tests
+  - Blocked by: Task 5.1, Task 1.2, Task 1.3
+  - Docs: same reference
+  - Skills: `terreno-data-fetching`, `update-docs`
+  - Acceptance: methods return the tracer prompt/resource from Phase 1 example or a test server
+
+---
+
+### Phase 6: OAuth 2.1 via Better Auth
+
+- [ ] **Task 6.1**: Catalog deps + Better Auth MCP plugin wiring
+  - Delivers: `@better-auth/mcp` and `@better-auth/oauth-provider` on the Better Auth instance `BetterAuthApp` already builds; JWT-only apps do not load the plugin
+  - Files: root catalog / `api/package.json`, Better Auth setup module, tests that plugin registers only when Better Auth is on
+  - Blocked by: none (can start in parallel with Phase 1; do not merge OAuth onto `/mcp` until 6.2)
+  - Docs: `docs/how-to/configure-better-auth.md` pointer that MCP OAuth is enabled with Better Auth
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: versions match [infra-mcp.md](../implementationPlans/infra-mcp.md) pins; JWT-only boot does not import the MCP OAuth plugin
+
+- [ ] **Task 6.2**: Protected-resource metadata + 401 challenge
+  - Delivers: RFC 9728 well-known document; unauthenticated `/mcp` returns 401 with `WWW-Authenticate` pointing at it
+  - Files: `api/src/mcp/server.ts`, `api/src/mcp/oauth.ts` (or Better Auth route hook), tests
+  - Blocked by: Task 6.1
+  - Docs: `docs/how-to/secure-app-mcp.md` (create); `docs/reference/api.md` well-known paths
+  - Skills: `terreno-backend-api`, `update-docs`
+  - Acceptance: Better Auth test app: no Authorization header → 401 + challenge; JWT-only app: no well-known required, bearer JWT still works
+
+- [ ] **Task 6.3**: Access token → app User in `extractUserFromHeaders`
+  - Delivers: OAuth access tokens on `Authorization: Bearer` resolve to the same `User` as REST; tool calls honor permissions
+  - Files: `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts`, server integration test
+  - Blocked by: Task 6.2
+  - Docs: `docs/how-to/secure-app-mcp.md` client connect steps (Claude/ChatGPT-style OAuth vs Inspector bearer)
+  - Skills: `terreno-backend-api`, `backend-test-env`, `update-docs`
+  - Acceptance: issued access token lists tools as that user; expired/wrong audience token is 401; JWT bearer still succeeds on the same app
+
+---
+
+### Phase 7: Explanation page
+
+- [ ] **Task 7.1**: Two-layer MCP explanation
+  - Delivers: `docs/explanation/app-mcp.md` + index link
+  - Files: `docs/explanation/app-mcp.md`, `docs/explanation/README.md`
+  - Blocked by: Task 2.2, Task 3.1, Task 6.3 (API and auth names stable)
+  - Docs: that explanation + README
+  - Skills: `update-docs`
+  - Acceptance: page tables Boost vs app MCP, generated vs registered primitives, JWT bearer vs Better Auth OAuth; links how-tos; does not document MCP Apps as shipped
+
+---
+
+## Frontier after Approve
+
+Unblocked: **Task 1.1** and **Task 6.1** (OAuth plugin wiring is independent until 6.2).
+Blocked until 1.1: 1.2–1.4.
+1.5 after 1.2+1.3.
+2.x after prompts+resources.
+3.2–3.3 after 3.1 (required generators).
+4.1 can start after 1.2+1.3 in parallel with 2.x.
+5.x after server HTTP surface is stable (2.1).
+6.2 after 6.1; 6.3 after 6.2.
+7.1 last for name-stable docs.

package/src/docs/versioned/next/tasks/better-auth-strict-oauth-provider.md

@@ -0,0 +1,41 @@
+# Task List: Better Auth sync omits unset `oauthProvider`
+
+**Feature profile:** true  
+**IP:** [better-auth-strict-oauth-provider.md](../implementationPlans/better-auth-strict-oauth-provider.md)  
+**Issue:** https://github.com/FlourishHealth/terreno/issues/1218
+
+## Durable contract
+
+- **Destination:** email/password Better Auth sync creates the app `User` on a `strict: "throw"` schema that has no `oauthProvider` field, so the first authenticated `modelRouter` request gets `req.user` instead of 401.
+- **Scope:** omit `oauthProvider` on `syncBetterAuthUser` create unless a non-empty provider string is passed; regression tests; docs and agent rules; changelog fragment.
+- **Non-goals:** bootstrap User schema; inventing `betterAuthUserPlugin`; session-middleware 401-on-sync-failure behavior; JWT.
+- **Decisions:** Q1 = option 1 (omit unset field). OAuth apps must still declare `oauthProvider`. Do not add the field to bootstrap.
+- **Tracer:** `syncBetterAuthUser` create path in `api/src/betterAuthSetup.ts`.
+- **Verification seam:** focused `bun test api/src/betterAuthSetup.test.ts` (red without the payload change), then `bun run api:test` and `bun run lint`.
+
+## Instructions for the implementing agent
+
+- TDD: add the `strict: "throw"` regression first and confirm it fails, then change the create payload.
+- Do not set `oauthProvider: null`. Omit the key.
+- When updating `docs/how-to/configure-better-auth.md` § User Model, replace the `betterAuthUserPlugin` example (that export does not exist) with explicit `betterAuthId` plus optional `oauthProvider`.
+- Use `backend-test-env` for any `process.env` mutations. Follow existing `betterAuthSetup.test.ts` helpers (separate MongoMemoryServer connection).
+- Supporting skills: `update-docs`, `backend-test-env`, `mongoose-schema-safety`, `terreno-backend-api`.
+
+### Phase 1: Fix lazy User create
+
+- [x] **Task 1.1**: Omit unset `oauthProvider` on Better Auth User create
+  - Delivers: email/password sign-up then first authenticated API call works on a bootstrap-like User schema (`strict: "throw"`, `betterAuthId`, no `oauthProvider`).
+  - Files: `api/src/betterAuthSetup.ts`, `api/src/betterAuthSetup.test.ts`, `docs/how-to/configure-better-auth.md`, `docs/explanation/authentication.md`, `.rulesync/rules/api/00-api.md` (regenerate agent copies with `bun run rules` and `bun run skills:sync`), `changelog/unreleased/better-auth-strict-oauth-provider.md`
+  - Blocked by: none
+  - Docs: how-to User model fields; explanation lazy sync; agent rule field list. Do not hand-edit generated TypeDoc.
+  - Skills: `update-docs`, `backend-test-env`, `mongoose-schema-safety`, `terreno-backend-api`
+  - Acceptance:
+    - New test: schema `{strict: "throw"}` without `oauthProvider`; `syncBetterAuthUser(model, baUser)` resolves; saved doc has `betterAuthId` and no `oauthProvider` path.
+    - New test: schema that declares `oauthProvider`; third argument `"google"` persists `"google"`.
+    - That first test fails on current `oauthProvider: oauthProvider || null` (StrictModeError).
+    - `bun test api/src/betterAuthSetup.test.ts` and `bun run api:test` pass after the fix.
+    - Docs state `betterAuthId` is required for sync; `oauthProvider` is required only when using OAuth.
+
+## Plan vs Actual
+
+- Task 1.1: `syncBetterAuthUser` create spreads `oauthProvider` only when truthy. Strict-throw schema without the field is green; create with `"google"` still persists. Docs dropped the non-existent `betterAuthUserPlugin` example.

package/src/docs/versioned/next/tasks/billing-stripe.md

@@ -25,7 +25,7 @@ IP: [billing-stripe](../implementationPlans/billing-stripe.md)
 - [ ] **Task 2.1**: Customer creation + checkout/portal session routes
   - Description: `POST /billing/checkoutSession` (IsOrgAdmin), `POST /billing/portalSession`, `GET /billing/plans`
   - Files: `billing/src/billingApp.ts`
-  - Depends on: 1.2, orgs-and-teams Phase 3
+  - Depends on: 1.2, org-management-ui Phase 3
   - Acceptance: mocked-Stripe supertest incl. permission denials
 - [ ] **Task 2.2**: `getEntitlements` + `planSegment` + `RequiresPlan`
   - Description: cache-backed entitlement service; feature-flag segment factory; permission

package/src/docs/versioned/next/tasks/can-as-permission-seam.md

@@ -0,0 +1,32 @@
+# Tasks: `can()` as the permission seam
+
+IP: [can-as-permission-seam.md](../implementationPlans/can-as-permission-seam.md)
+
+## Phase 1 — `assertAllowed`
+
+- [ ] **Task 1.1**: Helper + unit tests
+  - Delivers: `assertAllowed` implements legacy `checkPermissions` and `accessControl.can()`; double-gate test (access allow + permissions deny → allow)
+  - Files: `api/src/rbac/assertAllowed.ts`, `api/src/rbac/assertAllowed.test.ts`
+  - Blocked by: none (can land before MCP adapters; executors wiring waits on unified writes if MCP still duplicates checks)
+  - Acceptance: bun tests cover 405 empty array, 403 can() deny, legacy AND, access-wins-over-permissions
+
+## Phase 2 — Hot path
+
+- [ ] **Task 2.1**: Middleware + executors
+  - Delivers: `permissionMiddleware` and `executeCreate/Update/Delete` call `assertAllowed`; `buildAccessPermissions` not used on requests
+  - Files: `api/src/permissions.ts`, `api/src/sync/executors.ts`, `api/src/api.ts`, `api/src/rbac/modelRouterAccess.ts`, tests
+  - Blocked by: 1.1; unified-mutation-executors Phase 2 so MCP is included automatically
+  - Acceptance: modelRouter + executor + MCP permission tests pass; grep shows no request-path `buildAccessPermissions`
+
+## Phase 3 — Consumers and docs
+
+- [ ] **Task 3.1**: example-backend dual config
+  - Delivers: routers with `access` drop redundant AND `permissions` where RBAC is the intent
+  - Files: `example-backend/src/**` model routers
+  - Blocked by: 2.1
+  - Acceptance: example-backend tests pass
+- [ ] **Task 3.2**: Docs + breaking changelog
+  - Files: `docs/reference/api.md`, `docs/how-to/create-a-model.md`, `docs/implementationPlans/rbac-permissions.md` pointer, changelog
+  - Blocked by: 2.1
+  - Skills: `update-docs`
+  - Acceptance: evaluation order is documented; 403 vs 405 table exists

package/src/docs/versioned/next/tasks/collection-registry.md

@@ -0,0 +1,42 @@
+# Tasks: One collection registry
+
+IP: [collection-registry.md](../implementationPlans/collection-registry.md)
+
+## Phase 1 — Dual-write catalog
+
+- [ ] **Task 1.1**: `CollectionRegistry` module
+  - Delivers: `registerCollection`, `replaceCollectionOptions`, `getCollection`, `listCollections`, `clearCollectionRegistry` with unit tests (unknown path no-op, options replace)
+  - Files: `api/src/collectionRegistry.ts`, `api/src/collectionRegistry.test.ts`
+  - Blocked by: none
+  - Acceptance: bun tests for the module pass without wiring modelRouter
+- [ ] **Task 1.2**: Dual-write from `modelRouter`
+  - Delivers: `modelRouter` / `_buildModelRouter` write the catalog in addition to existing `register*` / `update*`
+  - Files: `api/src/api.ts`
+  - Blocked by: 1.1
+  - Acceptance: existing api tests still pass
+
+## Phase 2 — Surfaces read the catalog
+
+- [ ] **Task 2.1**: MCP and realtime views
+  - Delivers: `getMCPRegistry` / realtime finders read `CollectionRegistry`; arrays in those files removed
+  - Files: `api/src/mcp/registry.ts`, `api/src/realtime/registry.ts`, related tests
+  - Blocked by: 1.2
+  - Acceptance: MCP and realtime tests pass; `updateMCPRegistryOptions` updates the shared record
+- [ ] **Task 2.2**: Sync view + keep validation
+  - Delivers: sync lookup uses catalog; `registerSync` validation + index promises still run
+  - Files: `api/src/sync/registry.ts`, `api/src/sync/*.test.ts`
+  - Blocked by: 1.2
+  - Acceptance: missing `deleted` / `_syncSeq` still throws; sync tests pass
+
+## Phase 3 — Contract
+
+- [ ] **Task 3.1**: Single writer + clear-all
+  - Delivers: `modelRouter` only writes `CollectionRegistry`; wrapper register/update/clear functions; tests that used independent clears updated
+  - Files: `api/src/api.ts`, registry wrappers, tests
+  - Blocked by: 2.1, 2.2
+  - Acceptance: one `replaceCollectionOptions` is enough for MCP+sync options identity
+- [ ] **Task 3.2**: Docs + changelog
+  - Files: `docs/explanation/modular-api-design.md`, `docs/reference/api.md`, changelog
+  - Blocked by: 3.1
+  - Skills: `update-docs`
+  - Acceptance: docs name the catalog as the runtime seam

package/src/docs/versioned/next/tasks/comms-adapter-expo-push.md

@@ -2,27 +2,27 @@
 
 IP: [comms-adapter-expo-push](../implementationPlans/comms-adapter-expo-push.md)
 
-- [ ] **Task 1**: `ExpoPushProvider` implementation
+- [x] **Task 1**: `ExpoPushProvider` implementation
   - Description: token validation, chunked send, ticket collection per IP
   - Files: `comms/src/adapters/expoPush.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests pass, one `SendResult` per token
-- [ ] **Task 2**: Receipt polling → `DeliveryEvent` + dead-token marking
+- [x] **Task 2**: Receipt polling → `DeliveryEvent` + dead-token marking
   - Description: poll receipts after configurable delay; map `DeviceNotRegistered` to permanent failure
   - Files: `comms/src/adapters/expoPush.ts`
   - Depends on: Task 1
   - Acceptance: dead token deactivated in test
-- [ ] **Task 3**: Dependency moves
+- [x] **Task 3**: Dependency moves
   - Description: optional peer `expo-server-sdk` on comms; remove from `@terreno/api`
   - Files: `comms/package.json`, `api/package.json`, root catalog if needed
   - Depends on: Task 1
   - Acceptance: `bun install` + full compile pass; api tests unaffected
-- [ ] **Task 4**: example-frontend token registration + dev test-send
+- [x] **Task 4**: example-frontend token registration + dev test-send
   - Description: register token on login via `POST /comms/pushTokens`; profile dev row triggers `sendPushToUser`
   - Files: `example-frontend/app/_layout.tsx` or profile screen, `example-backend` dev route
   - Depends on: Task 1, comms-abstraction Phase 2
   - Acceptance: UI verification per verify-ui-changes with screenshots
-- [ ] **Task 5**: Docs
+- [x] **Task 5**: Docs
   - Description: adapter section in `docs/reference/comms.md` with env/config table
   - Files: `docs/reference/comms.md`
   - Depends on: Task 1

package/src/docs/versioned/next/tasks/comms-adapter-sendgrid.md

@@ -25,15 +25,19 @@ IP: [comms-adapter-sendgrid](../implementationPlans/comms-adapter-sendgrid.md)
   - Depends on: 1.1
   - Acceptance: boot without key skips registration; compile passes without the SDK installed
 
-## Phase 2 — Delivery events + opt-outs (gated on inbound-webhooks)
+## Phase 2 — Delivery events + opt-outs (owned by inbound-webhooks)
+
+HTTP routes and mapping land in [inbound-webhooks](../implementationPlans/inbound-webhooks.md)
+Task 3.3. The tables in the SendGrid IP remain the contract. Do not Pick these on this
+adapter branch.
 
 - [ ] **Task 2.1**: Event Webhook route
   - Description: ECDSA signature verification via inbound-webhooks; event mapping per the IP table → `DeliveryEvent`; `x-message-id` prefix correlation
   - Files: `comms/src/adapters/sendgrid.ts`, webhook registration
-  - Depends on: inbound-webhooks IP
+  - Depends on: inbound-webhooks Task 3.3
   - Acceptance: signed fixtures per event type update `CommsMessage.status` (+ `errorCode` for bounce/dropped); unsigned rejected 401
 - [ ] **Task 2.2**: Opt-out events
   - Description: `spamreport`/`unsubscribe`/`group_unsubscribe` → `OptOutEvent` → consumer `onOptOut`
   - Files: `comms/src/adapters/sendgrid.ts` + tests
-  - Depends on: 2.1
+  - Depends on: inbound-webhooks Task 3.3
   - Acceptance: spamreport fixture fires `onOptOut`; subsequent `dropped` classified `permanent`

package/src/docs/versioned/next/tasks/comms-adapter-twilio-sms.md

@@ -4,36 +4,40 @@ IP: [comms-adapter-twilio-sms](../implementationPlans/comms-adapter-twilio-sms.m
 
 ## Phase 1 — Send path
 
-- [ ] **Task 1.1**: `TwilioSmsProvider` with config resolution
+- [x] **Task 1.1**: `TwilioSmsProvider` with config resolution
   - Description: constructor/env config, messaging-service-first sender selection
   - Files: `comms/src/adapters/twilioSms.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests cover both sender configs
-- [ ] **Task 1.2**: E.164 validation + error classification
+- [x] **Task 1.2**: E.164 validation + error classification
   - Description: `libphonenumber-js` normalization; Twilio error-code → `errorCode`/`errorClass` map per the IP table (unknown codes → `transient`); full error payload into `CommsMessage.metadata`; Twilio SDK calls wrapped with `withApiErrorHandling`
   - Files: `comms/src/adapters/twilioSms.ts`
   - Depends on: 1.1
-  - Acceptance: invalid number → 400 before API call; fixtures for at least one code per class (e.g. 21610 permanent, 20429 transient, 20003 config) assert `errorClass`; permanent failures skip the inline retry
-- [ ] **Task 1.3**: Dashboard metadata + hooks coverage
+  - Acceptance: invalid number → permanent `SendResult` before API call; fixtures for at least one code per class (e.g. 21610 permanent, 20429 transient, 20003 config) assert `errorClass`; permanent failures skip the inline retry
+- [x] **Task 1.3**: Dashboard metadata + hooks coverage
   - Description: `metadata.consoleUrl` deep link per message SID; `onError` fires with the classified `SendResult`
   - Files: `comms/src/adapters/twilioSms.ts` + tests
   - Depends on: 1.2
   - Acceptance: failed-send test asserts consoleUrl and onError invocation
-- [ ] **Task 1.4**: Peer dep + example-backend registration + docs
+- [x] **Task 1.4**: Peer dep + example-backend registration + docs
   - Description: optional peer `twilio`; env-gated registration; reference + env-var docs
   - Files: `comms/package.json`, `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
   - Depends on: 1.1
   - Acceptance: compile + boot without twilio installed when unconfigured
 
-## Phase 2 — Delivery callbacks + opt-outs (gated on inbound-webhooks)
+## Phase 2 — Delivery callbacks + opt-outs (owned by inbound-webhooks)
+
+HTTP routes and mapping land in [inbound-webhooks](../implementationPlans/inbound-webhooks.md)
+Tasks 3.2–3.3. The tables in the Twilio SMS IP remain the contract. Do not Pick these on
+this adapter branch.
 
 - [ ] **Task 2.1**: Status callback route
   - Description: webhook endpoint with Twilio signature verification via inbound-webhooks framework; status mapping per IP table incl. `ErrorCode` propagation
   - Files: `comms/src/adapters/twilioSms.ts`, webhook registration
-  - Depends on: inbound-webhooks IP
+  - Depends on: inbound-webhooks Task 3.2
   - Acceptance: signed payload updates `CommsMessage.status` (+ `errorCode` on failure); unsigned rejected 401
 - [ ] **Task 2.2**: STOP/START opt-out handling
   - Description: inbound keyword webhook → `OptOutEvent` → consumer `onOptOut`; opt-in (START) emitted symmetrically
   - Files: `comms/src/adapters/twilioSms.ts`, webhook registration + tests
-  - Depends on: 2.1
+  - Depends on: inbound-webhooks Task 3.2
   - Acceptance: STOP fixture fires `onOptOut` with `reason: "sms-stop"`; 21610 on later sends classified `permanent`

package/src/docs/versioned/next/tasks/comms-adapter-twilio-verify.md

@@ -2,17 +2,17 @@
 
 IP: [comms-adapter-twilio-verify](../implementationPlans/comms-adapter-twilio-verify.md)
 
-- [ ] **Task 1**: `TwilioVerifyProvider` start/check
+- [x] **Task 1**: `TwilioVerifyProvider` start/check
   - Description: provider per IP with config resolution and status mapping
   - Files: `comms/src/adapters/twilioVerify.ts`
   - Depends on: comms-abstraction Phase 1
   - Acceptance: mocked-client tests for approved/pending/expired/max-attempts
-- [ ] **Task 2**: Redacted logging + error classification
+- [x] **Task 2**: Redacted logging + error classification
   - Description: `CommsMessage` rows with channel `verification`, fully redacted destination, no codes, and verification channel metadata on start; `errorCode`/`errorClass` mapping (rate-limit transient, expired/max-attempts permanent, bad SID config); rows flagged non-retryable; `onError` fires on failures
   - Files: `comms/src/adapters/twilioVerify.ts`
   - Depends on: Task 1
   - Acceptance: log assertion tests prove no code/full destination in any row; failure fixtures assert class + onError
-- [ ] **Task 3**: Registration + docs
+- [x] **Task 3**: Registration + docs
   - Description: env-gated example-backend registration; fail-fast on missing service SID; reference + env docs
   - Files: `example-backend/src/server.ts`, `docs/reference/comms.md`, `docs/reference/environment-variables.md`
   - Depends on: Task 1