@terreno/mcp 57.2.0 → 57.3.0

package/src/docs/versioned/next/reference/ui.md

@@ -1,6 +1,6 @@
 # @terreno/ui
 
-React Native UI component library (88+ components). Layout (Box, Page, Card), forms (TextField, SelectField), display (Text, DataTable), actions (Button), feedback (Modal, Toast), and theming via TerrenoProvider.
+React Native UI component library (a large component library). Layout (Box, Page, Card), forms (TextField, SelectField), display (Text, DataTable), actions (Button), feedback (Modal, Toast), and theming via TerrenoProvider.
 
 ## Key exports
 
@@ -13,6 +13,32 @@ React Native UI component library (88+ components). Layout (Box, Page, Card), fo
 - Theming: `TerrenoProvider`, `useTheme`, custom icon registry (`icons` prop)
 - **Type re-exports:** `StyleProp`, `ViewStyle` (re-exported from react-native to avoid version conflicts)
 
+## Performance-sensitive imports
+
+Use a component subpath when startup parse and evaluation cost matters:
+
+```typescript
+import {Box} from "@terreno/ui/Box";
+import {DataTable} from "@terreno/ui/DataTable";
+import {Icon} from "@terreno/ui/Icon";
+```
+
+Every compiled UI module is available through `@terreno/ui/<Module>`. Existing
+`@terreno/ui/dist/<file>` imports still resolve to the compiled `.js` / `.d.ts` files. The root import remains fully
+supported and is convenient when startup cost is not material:
+
+```typescript
+import {Box, DataTable, Icon} from "@terreno/ui";
+```
+
+Heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent flows, and related admin tools) are
+re-exported from the root entry through lazy boundaries. Importing them from `@terreno/ui` stays type-compatible, but
+their implementation modules load on first render instead of during the initial root import. `MarkdownView` and
+`DataTable` header info defer `react-native-markdown-display`; `EmojiSelector` defers `emoji-datasource` until open.
+
+For the smallest cold-start graph, keep using subpaths for screens that only need a few primitives (for example
+`import {Button} from "@terreno/ui/Button"`).
+
 ## Type Re-exports
 
 @terreno/ui re-exports commonly-used React Native types to help consumers avoid version conflicts:
@@ -52,6 +78,27 @@ Buttons automatically size to their content unless `fullWidth` is specified:
 
 Internally, Button sets `alignSelf: 'flex-start'` when `fullWidth={false}` to prevent stretching in column layouts.
 
+### Page Back Navigation
+
+Set `backButton` to render the standard header back arrow. By default it calls `router.back()`; provide `onBack` when the screen needs a deterministic destination instead of browser history.
+
+```typescript
+<Page backButton onBack={() => router.push("/admin")} title="Operations">
+  <OperationsDashboard />
+</Page>
+```
+
+### Button Press Animation
+
+Buttons use a scale animation by default. Set `pressAnimation="opacity"` for an opacity response or
+`pressAnimation="none"` when surrounding motion already provides feedback:
+
+``````typescript
+<Button text="Save" onClick={handleSave} pressAnimation="opacity" />
+``````
+
+Disabled and loading buttons use a non-interactive pressable regardless of the selected animation.
+
 ## Authentication Components
 
 ### SocialLoginButton
@@ -150,6 +197,29 @@ describe("MyComponent", () => {
 
 **Why:** Most @terreno/ui components require ThemeProvider context to access theme values.
 
+### TapToEdit testIDs
+
+Pass `testID` on `TapToEdit`. The Field input uses that id. Action controls suffix it:
+
+| Control | test id |
+| --- | --- |
+| Edit (pencil) | `{testID}.edit-clickable` |
+| Cancel | `{testID}.cancel` |
+| Clear | `{testID}.clear` |
+| Save | `{testID}.save` |
+
+```typescript
+<TapToEdit
+  testID="profile.name"
+  setValue={setName}
+  onSave={saveName}
+  title="Name"
+  value={name}
+/>
+// Edit:  profile.name.edit-clickable
+// Cancel / Clear / Save: profile.name.cancel, .clear, .save
+```
+
 ### createCommonMocks
 
 Creates mock functions for common component callbacks.
@@ -305,9 +375,9 @@ import {
   isMobileDevice,
 } from "@terreno/ui";
 
-// Check if matches breakpoint
-if (mediaQuery("md")) {
-  console.log("Medium or larger");
+// Read the current breakpoint
+if (mediaQuery() === "md") {
+  console.info("Medium viewport");
 }
 
 // Greater than breakpoint
@@ -322,15 +392,48 @@ if (mediaQuerySmallerThan("lg")) {
 
 // Detect mobile
 if (isMobileDevice()) {
-  console.log("Running on mobile device");
+  console.info("Running on mobile device");
 }
 ``````
 
-**Breakpoints:**
-- `sm`: 640px
-- `md`: 768px
-- `lg`: 1024px
-- `xl`: 1280px
+**Breakpoints are platform-specific.** `lg` and `xl` do not mean the same width on native and web.
+
+Native (iOS/Android):
+
+| Token | Width (pt) | Use |
+| --- | --- | --- |
+| Below `sm` | < 320 | Not supported. Accessible, not optimized. |
+| `sm` | 320–374 | Small phone. Critical workflows stay usable. |
+| `md` | 375–599 | Standard phone. |
+| `lg` | 600–1023 | Large mobile / tablet, including Samsung A11. |
+| `xl` | ≥ 1024 | Not a supported mobile layout. Use the desktop web experience where available. |
+
+Web (desktop staff):
+
+| Token | Width (pt) | Use |
+| --- | --- | --- |
+| Below `lg` | < 1024 | Not a supported desktop experience. Accessible, not optimized. |
+| `lg` | 1024–1279 | Smaller desktop. Collapse secondary content; keep core workflows. |
+| `xl` | ≥ 1280 | Primary desktop (M1/M4 MacBook Air 13"). Full multi-panel layouts. |
+
+On web, `sm` (320) and `md` (375) still classify widths below 1024 so layouts can remain accessible.
+
+`isMobileDevice()` is true below the supported desktop floor: native width < 1024 (`xl`), web width < 1024 (`lg`).
+
+Responsive `Box` direction props update automatically when the window resizes or a device rotates:
+
+``````typescript
+<Box
+  direction="column"
+  smDirection="row"
+  mdDirection="column"
+  lgDirection="row"
+  xlDirection="column"
+/>
+``````
+
+All responsive Boxes share one dimension listener; non-responsive Boxes do not subscribe.
+When multiple direction props match, the largest active breakpoint wins (`xl` over `lg` over `md` over `sm`).
 
 ## Icons
 
@@ -473,4 +576,5 @@ import {TerrenoProvider} from "@terreno/ui";
 
 ## Related Documentation
 
-See the [ui package source](../../ui/src/) and [.cursor/rules/ui/](../../.cursor/rules/ui/) for props and conventions.
+- [UI performance benchmarks](ui-performance.md)
+- [UI package source](https://github.com/flourishhealth/terreno/tree/master/ui/src)

package/src/docs/versioned/next/tasks/README.md

@@ -10,8 +10,8 @@ The filename slug matches the IP it belongs to.
 
 The loop's small-feature profile may use a task file with `**Feature profile:** true` and
 no full IP when repository policy permits. The destination, scope, decisions, acceptance
-criteria, tracer, and verification seam live in that durable contract so a fresh Pick
-agent can implement one task without conversation history.
+criteria, tracer, and verification seam live in that durable contract so Pick can
+implement one task, roast it, and continue to the next without conversation history.
 
 ## Task shape
 

package/src/docs/versioned/next/tasks/ai-agents-and-failover.md

@@ -0,0 +1,107 @@
+# Tasks: AI agents and provider failover
+
+IP: [ai-agents-and-failover](../implementationPlans/ai-agents-and-failover.md)
+
+Instructions for Pick:
+
+- TDD: failing test first on every task that ships code.
+- Mock `LanguageModel` with `doGenerate` / `doStream` (see `ai/src/service/aiService.test.ts`). Never call a live provider.
+- Agent instructions are named constants (`ai-prompt-governance`).
+- Docs in the same slice as the public API they describe (`update-docs`).
+- Import concrete files, not internal barrels.
+- `bun test` from `ai/` after each task; `bun run compile` before considering a phase done.
+
+## Phase 1 — Failover LanguageModel (tracer)
+
+- [ ] **Task 1.1**: `isFailoverableError`
+  - Delivers: shared predicate used by the wrapper and tests
+  - Files: `ai/src/service/failoverModel.ts`, `ai/src/service/failoverModel.test.ts`
+  - Blocked by: none
+  - Acceptance: 429 / 502 / 503 / 529 → true; `{statusCode: 429}` → true; 400 / 401 / 404 → false; `NoObjectGeneratedError`-shaped errors → false
+  - Docs: none (internal until 1.3)
+  - Skills: none
+
+- [ ] **Task 1.2**: `createFailoverModel` generate + stream
+  - Delivers: LanguageModel that tries the next model on failoverable `doGenerate` / `doStream` rejection
+  - Files: `ai/src/service/failoverModel.ts`, `ai/src/service/failoverModel.test.ts`
+  - Blocked by: 1.1
+  - Acceptance: two mocks, first 429, second succeeds; non-failoverable error does not call the second; empty `models` throws at construct; last error rethrown when all fail; `doStream` that returns then errors does **not** failover; `lastServedModelId` set on success
+  - Docs: none until 1.3
+  - Skills: none
+
+- [ ] **Task 1.3**: Export failover helpers
+  - Delivers: public package surface
+  - Files: `ai/src/index.ts`
+  - Blocked by: 1.2
+  - Acceptance: `createFailoverModel` and `isFailoverableError` importable from `@terreno/ai`; `bun run compile` in `ai/` succeeds
+  - Docs: none until Phase 4
+  - Skills: none
+
+## Phase 2 — Logging served model (tracer with AIService)
+
+- [ ] **Task 2.1**: Log the model that actually served
+  - Delivers: `AIRequest.aiModel` + `metadata.failover` after a failover generate
+  - Files: `ai/src/service/aiService.ts`, `ai/src/service/aiService.test.ts` (or `failoverModel` integration test using `AIService`)
+  - Blocked by: 1.2
+  - Acceptance: `generateText` through `createFailoverModel` logs backup `modelId`; `metadata.failover.attempts` length 2; logging failure still does not throw
+  - Docs: none until Phase 4
+  - Skills: none
+
+## Phase 3 — Agent
+
+- [ ] **Task 3.1**: `Agent` text `run`
+  - Delivers: named agent → `generateText` with instructions as `systemPrompt`
+  - Files: `ai/src/agent/agent.ts`, `ai/src/agent/agent.test.ts`, `ai/src/types/index.ts`
+  - Blocked by: none (can parallelize with Phase 1; logging assertions need 2.1)
+  - Acceptance: mock sees named instruction constant as system; `requestType` `"agent"`; `metadata.agentName` set; constructor requires `name` + `instructions`
+  - Docs: none until 3.4
+  - Skills: `ai-prompt-governance`
+
+- [ ] **Task 3.2**: `Agent` schema `run`
+  - Delivers: `schema` path uses `generateJsonObject`
+  - Files: `ai/src/agent/agent.ts`, `ai/src/agent/agent.test.ts`
+  - Blocked by: 3.1
+  - Acceptance: typed object returned; fence-stripping behavior unchanged; tools ignored when schema is set (asserted)
+  - Docs: none until 3.4
+  - Skills: `ai-prompt-governance`
+
+- [ ] **Task 3.3**: `Agent` tools + `runStream` + middleware
+  - Delivers: chat/tool loop, text stream, middleware chain
+  - Files: `ai/src/agent/agent.ts`, `ai/src/agent/agent.test.ts`
+  - Blocked by: 3.1
+  - Acceptance: tools passed through to `generateChatStream`; `maxSteps` default 5; `runStream` yields chunks; middleware order outer-first; short-circuit skips the model
+  - Docs: none until 3.4
+  - Skills: none
+
+- [ ] **Task 3.4**: Export Agent + explorer filter
+  - Delivers: public export; admin explorer can filter `agent`
+  - Files: `ai/src/index.ts`, `ai/src/routes/aiRequestsExplorer.ts`, explorer tests if present
+  - Blocked by: 3.1
+  - Acceptance: `Agent` importable from `@terreno/ai`; explorer query accepts `requestType=agent`
+  - Docs: Phase 4
+  - Skills: `update-docs`
+
+## Phase 4 — Docs and agent rules
+
+- [ ] **Task 4.1**: Reference + how-tos
+  - Delivers: operators can use Agent and failover without reading the IP
+  - Files: `docs/reference/ai.md`, `docs/how-to/define-an-ai-agent.md`, `docs/how-to/configure-ai-failover.md`, `docs/how-to/README.md`, `ai/README.md`
+  - Blocked by: 1.3, 3.4
+  - Acceptance: one minimal example per API; exports match `ai/src/index.ts`; how-to index links both pages
+  - Skills: `update-docs`
+
+- [ ] **Task 4.2**: Cursor rules + prompt-governance skill
+  - Delivers: agents use named instruction constants and failover wrapper, not ad-hoc retries in routes
+  - Files: `.cursor/rules/ai/00-ai.mdc` (or rulesync source), `skills/ai-prompt-governance/SKILL.md`; run `bun run rules` / `bun run skills:sync` if that is the repo workflow
+  - Blocked by: 4.1
+  - Acceptance: rule mentions `Agent` and `createFailoverModel`; prompt skill mentions agent instructions
+  - Skills: `update-docs`, `update-agent-docs`
+
+## Phase 5 — Optional example (skip if dual providers are not already wired)
+
+- [ ] **Task 5.1**: example-backend agent **or skip with recorded reason**
+  - Delivers: one in-repo Agent using existing Google/Vertex setup if both exist
+  - Files: `example-backend/src/api/ai.ts` (or adjacent module), named prompt constant
+  - Blocked by: 3.4, 1.3
+  - Acceptance: either (a) example constructs `createFailoverModel` + `Agent` without new required env, tests or typecheck pass, **or** (b) PR notes why skipped
+  - Skills: `ai-prompt-governance`

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.