@terreno/mcp 57.1.0 → 57.3.0

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

@@ -0,0 +1,255 @@
+# UI performance benchmarks
+
+Run the benchmark that covers the component being changed:
+
+```bash
+cd ui
+bun run performance:p0
+bun run performance:p0:openapi
+bun run performance:p1
+bun run performance:p2:button
+bun run performance:p2:responsive-box
+bun run performance:datatable-virtual
+bun run performance:imports
+```
+
+The benchmarks render large trees through the same React Native test environment as the UI
+component suite. They report median wall-clock times after two warmups and seven measured samples:
+
+- 500 `Box`, `Text`, and `Heading` instances
+- 100 `MarkdownView` instances
+- 500 theme consumers
+- 500 `useOpenAPISpec` consumers
+- a 100-row, eight-column `DataTable` with two pinned columns
+- 500 `Icon` instances
+- 500 plain `Button` instances and 100 confirmation `Button` instances
+- 500 responsive `Box` instances with `sm`, `md`, and `lg` direction props
+- 1,000-row `DataTable` workloads with pinned and unpinned virtualization
+- initial mount, same-prop update, and changed-prop/theme update timings
+
+Use it for before/after comparisons on the same machine. It is not a device frame-rate benchmark;
+native and browser profiling remain necessary for user-visible regressions.
+
+## August 2026 P0 optimization results
+
+All measurements below came from the same Cursor Cloud VM using Bun 1.3.11 and the default benchmark
+settings. Times are milliseconds; lower is better.
+
+| Step | Box same | Text same | Heading same | Markdown same | Theme same |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Baseline | 6.86 | 4.70 | 4.69 | 37.87 | 1.29 |
+| Memoize `Box` and reuse its style/ref | 5.78 | 4.84 | 4.69 | 30.58 | 1.63 |
+| Centralize fonts; memoize typography and markdown styles | 5.71 | 4.03 | 3.94 | 0.63 | 1.20 |
+| Stabilize theme actions and context value | 1.07 | 0.96 | 0.86 | 0.33 | 1.22 |
+| Share `Box` style mappers per computed theme | 1.01 | 0.90 | 0.79 | 0.31 | 1.21 |
+
+Final same-prop improvements versus baseline:
+
+| Workload | Improvement |
+| --- | ---: |
+| `Box` | 85.2% |
+| `Text` | 80.9% |
+| `Heading` | 83.2% |
+| `MarkdownView` | 99.2% |
+| Theme consumers | 6.4% |
+
+Changed-prop work remains intact: the final medians were 9.02ms for `Box`, 6.89ms for `Text`,
+6.52ms for `Heading`, and 28.08ms for `MarkdownView`. This is intentional: memoization skips only
+equivalent props, while changed props and theme values still render and are covered by
+`P0RenderRegression.test.tsx`.
+
+## August 2026 P1 optimization results
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11, with 21 measured samples to reduce
+variance. The changed `DataTable` workload replaces one cell while preserving the other row
+references. Times are milliseconds; lower is better.
+
+| Workload | Phase | Baseline | Optimized | Change |
+| --- | --- | ---: | ---: | ---: |
+| `DataTable` | Initial render | 23.20 | 24.08 | Within benchmark variance |
+| `DataTable` | Same-prop update | 32.49 | 0.18 | 99.4% faster |
+| `DataTable` | One-cell update | 31.74 | 1.57 | 95.1% faster |
+| `Icon` | Initial render | 1.47 | 1.50 | Within benchmark variance |
+| `Icon` | Same-prop update | 1.81 | 0.93 | 48.6% faster |
+| `Icon` | Changed-prop update | 3.07 | 3.61 | Full redraw retained |
+
+`DataTable` now reuses equivalent table, content, row, and cell work; computes pinned offsets once;
+and applies the default text size without cloning the full grid. `Icon` skips equivalent parent
+updates while still redrawing for icon prop and theme changes. `P1RenderRegression.test.tsx` covers
+both guarantees.
+
+The P1 example renderers import public component subpaths such as `@terreno/ui/DataTable` and
+`@terreno/ui/Icon`. These subpaths avoid evaluating the complete root export graph. The root
+`@terreno/ui` import and existing direct `src`/`dist` paths remain supported.
+
+## August 2026 OpenAPI context optimization results (Task 1.1)
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11, with 21 measured samples and 3
+warmups. The workload renders 500 `useOpenAPISpec` consumers under a parent rerender with an
+unchanged spec, then replaces the spec URL so field lookups must refresh. Times are milliseconds;
+lower is better.
+
+| Phase | Baseline | Optimized | Change |
+| --- | ---: | ---: | ---: |
+| Initial render | 1.65 | 1.64 | Within benchmark variance |
+| Same-prop update | 1.91 | 1.70 | 11.0% faster |
+| Spec replacement update | 1.76 | 1.79 | Within benchmark variance |
+
+`OpenAPIProvider` now memoizes `getModelField`, `getModelFields`, and the context value with complete
+`spec` dependencies. Unchanged metadata skips memoized consumers; replacing the spec updates field
+lookups immediately. `OpenAPIRenderRegression.test.tsx` covers both guarantees.
+
+## August 2026 DataTable virtualization results
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11, with 21 measured samples and 1,000-row
+pinned and unpinned workloads (`bun run performance:datatable-virtual`). Mounted row counts count unique
+`bench-table.row-*` test ids present after the initial render. Times are milliseconds; lower is better.
+
+| Workload | Phase | Baseline | Virtualized | Change |
+| --- | --- | ---: | ---: | ---: |
+| `DataTable` unpinned | Initial render | 224.59 | 3.45 | 98.5% faster |
+| `DataTable` unpinned | Same-prop update | 4.38 | 0.72 | 83.6% faster |
+| `DataTable` unpinned | One-cell update | 4.19 | 1.25 | 70.2% faster |
+| `DataTable` unpinned | Mounted rows | 1,000 | 15 | 98.5% fewer |
+| `DataTable` pinned (2 cols) | Initial render | 232.72 | 3.09 | 98.7% faster |
+| `DataTable` pinned (2 cols) | Same-prop update | 7.17 | 0.69 | 90.4% faster |
+| `DataTable` pinned (2 cols) | One-cell update | 6.86 | 1.31 | 80.9% faster |
+| `DataTable` pinned (2 cols) | Mounted rows | 1,000 | 15 | 98.5% fewer |
+
+Large `DataTable` bodies now virtualize with React Native `FlatList`, syncing pinned, more-column, and
+scrollable row lists while preserving horizontal header/body scroll sync, sorting, pagination, pinned
+columns, row-detail modals, custom cells, highlights, and row test ids. `DataTableVirtualizationRegression.test.tsx`
+covers viewport-bounded mounts, queued vertical-scroll flush after the sync lock, and changed rows after scrolling.
+
+## August 2026 root import optimization results
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11. Each workload uses a fresh Bun test process
+(seven measured samples, two warmups). The graph columns count evaluated `@terreno/ui` source modules reached through
+static `import`/`export` edges (type-only re-exports are excluded). Output bytes sum those module file sizes. Elapsed
+time includes dependency evaluation in the Bun test harness. Lower is better.
+
+| Workload | Modules | Output bytes | Elapsed (ms) | Baseline modules | Baseline bytes | Baseline elapsed (ms) |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| `@terreno/ui/Button` subpath | 17 | 345,992 | 22.8 | 19 | 383,185 | 22.3 |
+| `@terreno/ui` root | 138 | 889,124 | 189.3 | 151 | 1,031,537 | 207.9 |
+| `@terreno/ui/DataTable` subpath | 25 | 387,392 | 24.9 | 26 | 424,006 | 44.6 |
+| `@terreno/ui/MarkdownView` subpath | 5 | 19,036 | 3.5 | 7 | 148,456 | 27.0 |
+
+Changes in this slice:
+
+- Measured heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent/admin tools, and related
+  exports) now cross lazy root boundaries so their implementation files stay off the cold root import path.
+- `MarkdownView`, `DataTable` header info, and `EmojiSelector` defer `react-native-markdown-display` and
+  `emoji-datasource` until first use.
+- `RootImportRegression.test.tsx` and `bun run performance:imports` guard the public entrypoints.
+
+Run the import benchmark locally:
+
+```bash
+cd ui
+bun run performance:imports
+```
+
+Override sample counts when comparing smaller deltas:
+
+```bash
+UI_IMPORT_BENCHMARK_SAMPLES=21 \
+UI_IMPORT_BENCHMARK_WARMUPS=3 \
+bun run performance:imports
+```
+
+The benchmark prints a machine-readable `UI_IMPORT_BENCHMARK_RESULTS` JSON line for CI or local reporting.
+
+## August 2026 P2 Button optimization results
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11, with 21 measured samples. The
+changed workload replaces one button label or confirmation message while preserving every other
+prop. Times are milliseconds; lower is better.
+
+| Workload | Phase | Baseline | Optimized | Change |
+| --- | --- | ---: | ---: | ---: |
+| Plain `Button` | Initial render | 7.85 | 8.66 | Within benchmark variance |
+| Plain `Button` | Same-prop update | 13.73 | 0.94 | 93.1% faster |
+| Plain `Button` | One-label update | 11.99 | 0.98 | 91.8% faster |
+| Confirmation `Button` | Initial render | 1.71 | 1.93 | Within benchmark variance |
+| Confirmation `Button` | Same-prop update | 2.79 | 0.30 | 89.2% faster |
+| Confirmation `Button` | One-message update | 2.71 | 0.32 | 88.3% faster |
+
+`Button` now skips equivalent parent updates, keeps debounce identity stable, and cancels retained
+debounce timers on replacement or unmount. Plain buttons use a separate path that does not allocate
+confirmation state or request the lazy modal. Delayed handlers remain disabled until completion.
+Confirmation buttons clear the press cooldown when the modal closes, so Cancel, dismiss, or Confirm
+still allows an immediate reopen while repeated presses that do not close the modal stay debounced.
+`P2ButtonRenderRegression.test.tsx` covers equivalent props plus changed labels, confirmation
+content, and theme values.
+
+## August 2026 P2 responsive Box optimization results
+
+These measurements used the same Cursor Cloud VM and Bun 1.3.11, with 21 measured samples. Times
+are milliseconds; lower is better.
+
+| Phase | Baseline | Optimized | Change |
+| --- | ---: | ---: | ---: |
+| Initial render | 3.01 | 3.12 | Within benchmark variance |
+| Same-prop update | 0.89 | 0.88 | Within benchmark variance |
+| One-direction update | 0.92 | 0.90 | Within benchmark variance |
+| Initial `Dimensions.get` calls | 1,500 | 1 | 99.9% fewer |
+
+Responsive Boxes now subscribe to one shared window-dimension source. A resize or rotation updates
+the cached breakpoint and every subscribed Box without a synchronous dimension read per responsive
+prop. Non-responsive Boxes do not subscribe. Focused regressions cover the native 320pt / 375pt / 600pt /
+1024pt boundaries, the web 1024pt / 1280pt desktop boundaries, listener sharing, cleanup, and
+changed responsive styles.
+
+## Environment overrides
+
+Increase samples or workload size when comparing smaller changes:
+
+```bash
+UI_P0_BENCHMARK_SAMPLES=21 \
+UI_P0_BENCHMARK_WARMUPS=3 \
+UI_P0_BENCHMARK_SIZE=1000 \
+bun run performance:p0
+```
+
+```bash
+UI_P1_BENCHMARK_SAMPLES=21 \
+UI_P1_BENCHMARK_WARMUPS=3 \
+UI_P1_BENCHMARK_TABLE_ROWS=200 \
+UI_P1_BENCHMARK_ICONS=1000 \
+bun run performance:p1
+```
+
+```bash
+UI_P0_OPENAPI_BENCHMARK_SAMPLES=21 \
+UI_P0_OPENAPI_BENCHMARK_WARMUPS=3 \
+UI_P0_OPENAPI_BENCHMARK_SIZE=500 \
+bun run performance:p0:openapi
+```
+
+```bash
+UI_P2_BUTTON_BENCHMARK_SAMPLES=21 \
+UI_P2_BUTTON_BENCHMARK_WARMUPS=3 \
+UI_P2_BUTTON_BENCHMARK_SIZE=1000 \
+UI_P2_CONFIRMATION_BUTTON_BENCHMARK_SIZE=200 \
+bun run performance:p2:button
+```
+
+```bash
+UI_P2_RESPONSIVE_BOX_BENCHMARK_SAMPLES=21 \
+UI_P2_RESPONSIVE_BOX_BENCHMARK_WARMUPS=3 \
+UI_P2_RESPONSIVE_BOX_BENCHMARK_SIZE=1000 \
+bun run performance:p2:responsive-box
+```
+
+```bash
+UI_DATATABLE_VIRTUAL_BENCHMARK_SAMPLES=21 \
+UI_DATATABLE_VIRTUAL_BENCHMARK_WARMUPS=3 \
+UI_DATATABLE_VIRTUAL_BENCHMARK_ROWS=1500 \
+bun run performance:datatable-virtual
+```
+
+The benchmarks print machine-readable `UI_P0_BENCHMARK_RESULTS`, `UI_P1_BENCHMARK_RESULTS`,
+`UI_P2_BUTTON_BENCHMARK_RESULTS`, `UI_P2_RESPONSIVE_BOX_BENCHMARK_RESULTS`,
+`UI_DATATABLE_VIRTUAL_BENCHMARK_RESULTS`, or `UI_IMPORT_BENCHMARK_RESULTS` JSON lines for CI or
+local reporting.

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`