@terreno/mcp 57.2.0 → 57.3.0

package/dist/docs/versioned/next/how-to/upgrade-terreno.md

@@ -0,0 +1,78 @@
+# Upgrade Terreno
+
+Bump every `@terreno/*` package together. Mixing versions is unsupported ([versioning policy](../explanation/versioning-policy.md)).
+
+## 1. Check current versions
+
+From the app root:
+
+```bash
+bun pm ls --all | rg '@terreno/'
+```
+
+Or call MCP `application_info` (`terreno-mcp-local`) and read each `package.json`. Record the lowest `@terreno/*` version as `fromVersion` and the target as `toVersion` (usually the latest tag on [GitHub Releases](https://github.com/FlourishHealth/terreno/releases)).
+
+## 2. Fetch notes for the range
+
+```text
+terreno_get_upgrade_guide({ fromVersion, toVersion })
+```
+
+Or browse [`mcp-server/src/docs/upgrades/`](../../mcp-server/src/docs/upgrades/). The tool lists recorded notes and names same-major minors with no file — a gap is not “nothing changed.”
+
+## 3. Order (do not skip)
+
+| Step | Why |
+| --- | --- |
+| Clean git tree, work on a branch | Rollback is `git checkout -- .` / `git reset --hard` on that branch. |
+| Backend `@terreno/*` first | `/openapi.json` is the contract the frontend typed client is generated from. Regenerating against an old backend omits new routes; screens fail at compile. |
+| Backend compile + tests | Catch API breaks before touching Expo or UI. |
+| Expo SDK (if the Terreno major tracks a new Expo) | `@terreno/ui` pins `react-native` (for example `~0.86.0` on the 57 line in `ui/package.json` `peerDependencies`). Installing Terreno frontend packages before Expo leaves unmet peers. |
+| Frontend `@terreno/*` | UI, syncdb, admin-frontend, admin-spa, rtk. |
+| Regenerate typed client | Only after the **upgraded** backend is running. |
+| Compile, lint, tests | Whole app. |
+| Run the app | UI verification. |
+
+Use the `upgrading-expo` skill at the Expo step. Do not copy Expo’s checklist into a Terreno-only bump.
+Maintainers watching the next SDK beta use `track-upstream-expo` / [`track-upstream-expo.md`](track-upstream-expo.md) instead of mixing native bumps onto master.
+
+### Backend vs frontend packages
+
+From `publish-on-tag.yml`: **backend** `api`, `test`, `admin-backend`, `ai`, `api-health`, `comms`, `feature-flags`, `mcp`. **frontend** `ui`, `rtk`, `syncdb`, `admin-frontend`, `admin-spa`.
+
+## 4. RTK → syncdb is not a version bump
+
+If the range includes the syncdb release (`56.0.0-beta.2` and later), treat collection CRUD as a **platform migration**. Follow [migrate-rtk-to-syncdb.md](migrate-rtk-to-syncdb.md) in a separate change from the routine lockstep bump. Keep `@terreno/rtk` for the OpenAPI SDK, Better Auth, feature flags, and sockets until that migration is done.
+
+## 5. Manual steps
+
+1. Branch from a clean tree. Confirm tests pass on HEAD so later failures are from the upgrade.
+2. Print `fromVersion`, `toVersion`, notes, affected packages, and this order. **Stop until the human confirms.**
+3. Bump backend packages to `toVersion`. `bun install`. `bun run compile` and backend tests.
+4. If Expo must move, run `upgrading-expo`, then rebuild native binaries.
+5. Bump frontend packages. `bun install`.
+6. Start the upgraded backend. `cd <frontend> && bun run sdk`.
+7. `bun run compile`, `bun run lint`, and the app test suite.
+8. Log in and exercise the screens that use changed APIs.
+
+Stop at the first failed compile or test. Do not continue. Compile is a typecheck (`tsc --noEmit`); a bundler that ignores types is not enough.
+
+## 6. Verification
+
+- Every `@terreno/*` version in the lockfile is `toVersion`.
+- `terreno_get_upgrade_guide` verification sections for notes in the range all pass.
+- App boots; auth and one write path work.
+
+## 7. Rollback
+
+On the upgrade branch, with no extra uncommitted work you need:
+
+```bash
+git status --short   # only upgrade edits
+git reset --hard HEAD
+# or restore the previous lockfile commit:
+git checkout <pre-upgrade-sha> -- package.json bun.lock
+bun install
+```
+
+If you already committed, `git revert` the upgrade commit or reset the branch to the pre-upgrade SHA before it was pushed. Do not leave a half-upgraded lockfile on `master`.

package/dist/docs/versioned/next/implementationPlans/IP_TEMPLATE.md

@@ -1,6 +1,9 @@
 # Implementation plan template
 
-Copy to `docs/implementationPlans/<slug>.md` and replace placeholders. Pair with `docs/tasks/<slug>.md`.
+Copy to `docs/implementationPlans/<slug>.md` and replace placeholders. Pair with
+`docs/tasks/<slug>.md`. Add `**Parent IP:** [other](other.md)` only when this plan
+rides on another plan's roadmap entry instead of getting its own. A filled Parent
+IP header skips reconcile for that file.
 
 **Status:** Draft | Approved | In progress | Complete | Deferred  
 **Branch:**  

package/dist/docs/versioned/next/implementationPlans/ModularAPI.md

@@ -1,6 +1,8 @@
 # Modular API Implementation Plan
 
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1084
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1084  
+**Status:** Complete
+
 ## Overview
 
 This document outlines the implementation plan for a new modular API design in `@terreno/api`. The goal is to create a `TerrenoApp` class that provides a cleaner, more flexible interface for building APIs while maintaining backward compatibility with the existing `setupServer` function.

package/dist/docs/versioned/next/implementationPlans/README.md

@@ -45,19 +45,19 @@ index** (destination, in/out, tracer, task graph, test seam). When grilling prod
 human decisions, it lists **every** one in a Decisions table with no row cap. If there
 were none, that table is omitted.
 
-For a small feature, an outer loop may use the plugin's **feature profile**: a compact
-approved task contract, one fresh Pick invocation per frontier task, independent Roast,
-then Brew and bounded Taste iterations. This preserves the former Grind behavior without
-putting orchestration inside a lifecycle skill.
+For a small feature, the plugin's **feature profile** uses a compact approved task
+contract: invoke Pick once; it implements one frontier task, roasts it, then picks the
+next until the list is done, then Brew and bounded Taste iterations.
 
 1. **Grow** (`terreno-1-grow`) — grill until answers are executable, then write the IP + tracer-bullet task list; end with the 15-line verify index and a full Decisions table when any exist.
-2. **Pick** (`terreno-2-pick`) — implement one approved slice via TDD.
-3. **Roast** (`terreno-3-roast`) — independently verify the implementation against the IP.
-4. **Brew** (`terreno-4-brew`) — commit, push, open the PR.
+2. **Pick** (`terreno-2-pick`) — implement one approved slice via TDD, then continue the pick-roast inner loop.
+3. **Roast** (`terreno-3-roast`) — independently verify the current task, then return (`next: pick` or `next: brew`).
+4. **Brew** (`terreno-4-brew`) — commit, push, open the PR after every in-scope task has Roast `PASS`.
 5. **Taste** (`terreno-5-taste`) — react once to current CI, mergeability, and review state.
 
-The outer loop owns stage selection, execution-state persistence, waiting, retries, and
-human/external escalation. Each stage emits the compact machine-readable result described
+The outer loop owns Grow/Brew/Taste selection, execution-state persistence, waiting,
+retries, and human/external escalation. Pick owns the inner task loop. Roast never
+invokes Pick. Each stage emits the compact machine-readable result described
 in [`plugins/terreno-planning/references/lifecycle-contract.md`](../../plugins/terreno-planning/references/lifecycle-contract.md)
 (collapsed behind a Details toggle in chat and on the PR).
 

package/dist/docs/versioned/next/implementationPlans/agentic-sdlc-plugin.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Loop-Engineering Lifecycle Plugin
 
-**Status:** In Progress
+**Status:** Complete — shipped as `plugins/terreno-planning`
 **Approved:** 2026-08-22
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1006
 **Priority:** High
@@ -17,7 +17,11 @@ transitions optimized for repeated fresh agent invocations:
 Grow (shape) → Pick (build) → Roast (prove) → Brew (submit) → Taste (react)
 ```
 
-The outer loop owns invocation, persistence, waiting, retry, stop, and escalation.
+The outer loop owns invocation, persistence, Taste `PENDING` reinvocation, retry, stop,
+and escalation. Brew waits in-process for async review bots. Taste waits in-process for
+review bots and for product CI (GitHub CLI or CircleCI CLI watch loop). Before any
+push it pulls latest `master`, lints in a no-context subagent, then pushes and watches
+CI.
 Lifecycle skills own how one stage is performed. Repository skills own how this codebase
 works. Roast owns independent acceptance proof. State/evidence bridge fresh invocations.
 
@@ -30,8 +34,8 @@ This is a refactor of the existing strong workflow, not a parallel implementatio
 - Shared machine-readable result and execution-state schemas
 - Supporting-skill discovery/composition
 - Repository-specific detail removed from portable stages
-- Brew exits after PR setup
-- Taste performs one reactive iteration and exits
+- Brew exits after PR setup and the review-bot wait
+- Taste performs one reactive iteration after waiting for review bots and product CI, then exits
 - Outer-loop reference including small-feature and CI/review scenarios
 - Static validation for names, status values, transitions, portability, and loop bounds
 - Documentation, metadata, and generated integrations
@@ -52,13 +56,16 @@ This is a refactor of the existing strong workflow, not a parallel implementatio
 | AP2 | Sensitive-data rules cover credentials, customer data, PII/PHI, and evidence media |
 | AP3 | Canonical stages are Grow, Pick, Roast, Brew, Taste |
 | AP4 | Stages discover supporting skills by description; exact skill names are never universal dependencies |
-| AP5 | Taste is one observe/act/emit iteration; the outer loop owns waiting and reinvocation |
+| AP5 | Taste is one observe/act/emit iteration after in-process waits for async review bots and product CI. Before any push: always pull latest `master`, then run lint, typecheck, and affected tests in a fresh subagent with no parent conversation, then push and watch CI (`gh` / `circleci`). The outer loop reinvokes on Taste `PENDING` |
 | AP6 | Shared results use compact `v: 2` YAML; required keys are `v`, `stage`, `status`, `next`, `action`; empty keys are omitted; YAML is collapsed for humans |
 | AP7 | Existing repository state convention wins; fallback reuses loop-owned `.terreno/pipeline/<slug>.json`, not committed by default |
 | AP8 | Brew emits PR/head state and exits; direct Taste invocation is standalone compatibility only |
 | AP9 | No deprecated command aliases: old implementation-Roast conflicts with new verification-Roast and no maintained alias mechanism exists |
 | AP10 | Plugin major version is `2.0.0` because lifecycle semantics and command names are breaking |
 | AP11 | Grow lists every grilled decision in an unbounded Decisions table after the 15-line index, or omits the table when there were none; grilling stays on a question until the answer is executable |
+| AP12 | Brew and Taste wait until Bugbot, CodeQL, and similar review bots on the current head have reported, preferring hooks targeted to the matched bot or harness subscriptions over timer polling; unfiltered PR-check watches are product-CI waits owned by Taste |
+| AP13 | Product CI is every discovered host (GitHub Actions, CircleCI, Buildkite, GitLab CI, and similar). Taste observes native jobs when GitHub checks are incomplete; Brew confirms each host triggered or documented a not-applicable skip. An unexplained untriggered host prevents Brew `PASS`; a documented skip is terminal for Taste |
+| AP14 | Taste waits in-process with the provider's bounded native watch command (`gh pr checks --watch`, `gh run watch`, `circleci run watch`, `bk build watch`) in a loop until jobs are terminal or the wait times out. Outer loops honor Taste `PENDING` with the same hooks. Watch exit codes trigger a fresh classification rather than becoming stage verdicts directly |
 
 ## Architecture
 
@@ -78,7 +85,7 @@ This is a refactor of the existing strong workflow, not a parallel implementatio
 
 | Layer | Owns |
 | --- | --- |
-| Outer loop | when, who, next stage, persistence, waiting, retry, stop, escalation |
+| Outer loop | when, who, next stage, persistence, Taste `PENDING` reinvocation, retry, stop, escalation |
 | Lifecycle plugin | portable stage procedure, invariants, evidence, transitions |
 | Repository skills | commands, frameworks, package conventions, safety rules, gotchas |
 | Roast | requirement → method → evidence → verdict |
@@ -145,14 +152,25 @@ returns exact expected/actual evidence to Pick.
 ### Brew
 
 Requires Roast proof, runs repository-defined final checks/review, commits/pushes, applies
-the PR template, attaches evidence, records PR/current head, and exits. It does not wait
-for CI or execute Taste.
+the PR template, attaches evidence, confirms product CI triggered on every discovered
+host, and waits for async review bots (Bugbot, CodeQL, and similar) on the current head.
+Waits prefer provider CLI watch hooks or harness subscriptions and use bounded polling
+only as fallback. Brew records PR/current head and exits; it does not wait for ordinary
+product CI or execute Taste.
 
 ### Taste
 
-Reads current-head CI, mergeability, and unresolved review signals once. It classifies,
-performs one bounded set of actionable fixes, verifies/pushes if changed, emits
-`PASS`/`PENDING`/`BLOCKED`/`FAIL`, and exits. The outer loop schedules another invocation.
+Waits in-process if Bugbot, CodeQL, or similar review bots are still running, preferring
+provider CLI watch hooks or harness subscriptions, then waits in a loop for product CI
+using GitHub CLI (`gh pr checks --watch`, `gh run watch`) or CircleCI CLI
+(`circleci run watch`) until jobs on every discovered host are terminal or the wait
+times out. It then classifies mergeability and reviews, performs one bounded set of
+actionable fixes. Before any push it always pulls latest `master`, then spawns a fresh
+subagent with no parent conversation to run lint, typecheck, and locally affected tests
+in each affected package, then pushes and watches review bots and product CI. It may act
+once more after that watch. It emits
+`PASS`/`PENDING`/`BLOCKED`/`FAIL` and exits. The outer loop reinvokes after timeout or a
+second post-fix push.
 
 ## Supporting skills
 
@@ -168,8 +186,10 @@ code, tests, scripts, and analogous changes.
 ## Retry semantics and human gates
 
 Engineering retries are bounded and hypothesis-driven. Each attempt retains exact failure
-evidence and attempted approaches. Changing external state may be observed indefinitely
-by repeated fresh Taste invocations, but no lifecycle skill waits internally.
+evidence and attempted approaches. Product CI may be observed indefinitely by repeated
+fresh Taste invocations. Outer loops use provider-native watch hooks or harness
+subscriptions during each bounded wait and timers only as fallback. Brew and Taste wait
+internally only for async review bots.
 
 Human gates include product semantics, architecture/security/data ownership, destructive
 or irreversible operations, permissions, public compatibility, major scope expansion,

package/dist/docs/versioned/next/implementationPlans/ai-agents-and-failover.md

@@ -0,0 +1,237 @@
+# Implementation plan: AI agents and provider failover
+
+**Status:** Draft  
+**Branch:** `cursor/ai-agents-and-failover-ip-97fd`  
+**Owner:** unassigned  
+**Created:** 2026-08-24  
+**Package:** `@terreno/ai`  
+**Related:** Laravel AI SDK comparison (items 1 and 3): named Agent reuse + LanguageModel failover on 429/503  
+
+## Goal
+
+Add two additive library seams to `@terreno/ai` so app code can:
+
+1. Define a reusable **Agent** (`name`, `instructions`, `tools`, optional `schema`, optional `middleware`) that runs through existing `AIService` logging.
+2. Wrap one or more Vercel AI SDK `LanguageModel`s in **`createFailoverModel`** so 429/502/503/overloaded failures try the next model. Every `AIService` method inherits failover without per-method changes.
+
+Destination: a consuming app can write a typed agent, pass a failover chain as `model`, and prove with mocks that the second model serves after the first throws a failoverable error.
+
+## Non-Goals
+
+- Embeddings, pgvector/Atlas Vector, RAG, `SimilaritySearch` (comparison item 2).
+- Image generation, TTS, STT, reranking, provider file/vector stores.
+- New HTTP routes, `AiApp` options, or GPT chat rewrite.
+- Human-in-the-loop tool approval / resume.
+- First-class sub-agents (keep existing `parentRequestId` / `subRequestIds` only).
+- Queued generation, Echo-style broadcast, `Agent.fake()` Laravel helpers.
+- Changing `AIService` constructor (`model` stays a single `LanguageModel`).
+- Mid-stream failover after the client has received text deltas.
+
+## Decisions
+
+Grow recorded these as executable defaults from the comparison plus current `@terreno/ai` shape (`AIService` + injected `LanguageModel` in `ai/src/service/aiService.ts`). Change a row before Approve if Pick should do something else.
+
+| ID | Question | Decision |
+| --- | --- | --- |
+| D1 | Scope | Agent API + failover wrapper only. No embeddings, no multimodal generation, no new routes. |
+| D2 | Agent shape | Class `Agent` wrapping an `AIService` instance. Not a replacement for `AIService`. Laravel-style PHP agent classes are the DX target, not the type system. |
+| D3 | HTTP | No new routes in v1. Chat stays `addGptRoutes`. Apps call `agent.run()` from their own services/routes. |
+| D4 | Failover seam | `createFailoverModel({models, isFailoverable?})` returns a `LanguageModel`. Pass it as `AIService` `model`. Do not add `models[]` to the constructor. |
+| D5 | Failover triggers | Default: HTTP 429, 502, 503, 529; SDK/provider errors whose `statusCode` matches; messages matching rate-limit / overloaded / capacity. Not 400/401/403/404. Not structured-output parse failures (`NoObjectGeneratedError`). |
+| D6 | Same-model retry | Each listed model is tried once per call. No extra retries on the same model. |
+| D7 | Streaming | Fail over only if `doStream` **rejects before returning a stream**. After the stream exists, errors propagate. No replay of partial output. |
+| D8 | Logging | Successful `AIRequest.aiModel` is the model that served. `metadata.failover` records `{attempts: [{modelId, error?}], servedModelId}`. Failures still never throw from logging. |
+| D9 | Instructions | Agent `instructions` are prompts. Named constants (app `prompts.ts` or `ai/src/service/prompts.ts`). `ai-prompt-governance` applies. |
+| D10 | Schema + tools | v1 allows tools on text/chat runs. `schema` uses `generateJsonObject` and **does not** combine with tools in the same `run`. Streaming `runStream` is text-only (no schema). |
+| D11 | Middleware | Array of `(input, next) => Promise<output>` around `run` / `runStream` only. Not Express middleware. |
+| D12 | Example app | Optional tracer in `example-backend` if two providers are already configured; otherwise tests-only tracer is enough. |
+| D13 | Compatibility | Additive exports only. Existing `new AIService({model})` and `AiApp` stay valid. |
+
+## Architecture
+
+```
+App
+  Agent({instructions, tools?, schema?, middleware?}, aiService)
+    → AIService.generateText | generateChatStream | generateJsonObject
+        → LanguageModel (optionally createFailoverModel)
+            → primary.doGenerate / doStream
+            → on failoverable error → next model
+        → AIRequest.logRequest (served model id + failover metadata)
+```
+
+`AIService` stays the only path that talks to the Vercel SDK for logged calls. Agent does not call `generateText` / `streamText` from `ai` directly.
+
+Failover is a `LanguageModel` Proxy (same idea as `withStrippedJsonFencesModel` in `aiService.ts`): intercept `doGenerate` and `doStream`, preserve other properties from the **primary** model (`specificationVersion`, `provider`, `supportedUrls`).
+
+`modelId` on the wrapper: `failover(<primaryId>)` for identification. `AIService` logging must read **served** id via a small well-known slot on the wrapper (for example `lastServedModelId`) so explorer rows are not all `failover(...)`.
+
+### Agent API (proposed)
+
+```typescript
+interface AgentContext {
+  userId?: mongoose.Types.ObjectId;
+}
+
+interface AgentRunOptions extends AgentContext {
+  prompt: string;
+  messages?: Array<{content: string; role: "user" | "assistant" | "system"}>;
+  temperature?: number;
+}
+
+interface AgentMiddleware<OUTPUT = string> {
+  (
+    input: AgentRunOptions,
+    next: (input: AgentRunOptions) => Promise<OUTPUT>
+  ): Promise<OUTPUT>;
+}
+
+interface AgentConfig<OUTPUT = string> {
+  name: string;
+  instructions: string | ((ctx: AgentContext) => string | Promise<string>);
+  tools?: ToolSet | ((ctx: AgentContext) => ToolSet | Promise<ToolSet>);
+  schema?: import("ai").FlexibleSchema<OUTPUT>;
+  middleware?: Array<AgentMiddleware<OUTPUT>>;
+  temperature?: number;
+  maxSteps?: number;
+  requestType?: string;
+}
+
+class Agent<OUTPUT = string> {
+  constructor(config: AgentConfig<OUTPUT>, service: AIService);
+  run(options: AgentRunOptions): Promise<OUTPUT | string>;
+  runStream(options: AgentRunOptions): AsyncGenerator<string>;
+}
+```
+
+Dispatch:
+
+| Config | Implementation |
+| --- | --- |
+| `schema` set | `AIService.generateJsonObject` with `systemPrompt` = resolved instructions. Ignore tools. |
+| `tools` set, no schema | Collect `generateChatStream` with `stopWhen: stepCountIs(maxSteps ?? 5)` (same default as `AiApp.maxSteps`). |
+| neither | `AIService.generateText` with `systemPrompt` = instructions. |
+
+`requestType` defaults to `"agent"` (extend `AIRequestType` union / explorer filters). Store `metadata.agentName`.
+
+Factory export `defineAgent(config)` that returns `(service) => new Agent(config, service)` is optional sugar; Pick may ship class-only if that is smaller.
+
+### Failover API (proposed)
+
+```typescript
+interface CreateFailoverModelOptions {
+  models: LanguageModel[];
+  isFailoverable?: (error: unknown) => boolean;
+}
+
+createFailoverModel(options: CreateFailoverModelOptions): LanguageModel;
+isFailoverableError(error: unknown): boolean;
+```
+
+- `models.length < 1` throws at construction (early return / guard).
+- `isFailoverable` defaults to `isFailoverableError`.
+- On failover: `logger.warn` with `fromModelId`, `toModelId`, `error` (no secrets).
+- If every model fails: throw the **last** error (do not wrap in a generic message that hides the provider error).
+- Structured-json path: `withStrippedJsonFencesModel(createFailoverModel(...))` still works because failover is a LanguageModel. Order: app wraps failover first, then `AIService` applies fence stripping on that wrapper for JSON methods.
+
+### `getModelId` / logging
+
+Update `getModelId` (or logging helpers) so if `model` has `lastServedModelId: string`, log that. Wrapper sets it on success. Tests assert `AIRequest.aiModel` equals the backup id after a primary 429.
+
+## Models
+
+No new Mongoose models. No schema migration.
+
+`AIRequest.metadata` (already Mixed) gains optional:
+
+```typescript
+interface FailoverLogMetadata {
+  attempts: Array<{modelId: string; error?: string}>;
+  servedModelId: string;
+}
+
+interface AgentLogMetadata {
+  agentName: string;
+}
+```
+
+`requestType` may be `"agent"` in addition to current defaults. Update admin explorer filters in `ai/src/routes/aiRequestsExplorer.ts`.
+
+## APIs
+
+No REST/OpenAPI changes.
+
+Public package exports from `ai/src/index.ts`:
+
+- `Agent`, type `AgentConfig`, type `AgentMiddleware`, type `AgentRunOptions`
+- `createFailoverModel`, `isFailoverableError`, type `CreateFailoverModelOptions`
+
+## Notifications
+
+None.
+
+## UI
+
+None. Admin explorer already shows `requestType` / `aiModel` / `metadata`; document the new metadata shape in reference docs only.
+
+## Phases
+
+1. **Failover LanguageModel** — `createFailoverModel` + tests (tracer).
+2. **Logging served model** — `lastServedModelId` into `AIRequest`.
+3. **Agent** — class + dispatch + middleware + tests.
+4. **Docs + agent rules** — reference, how-to, `.cursor/rules/ai`, prompt-governance mention.
+5. **Optional example-backend** — one agent if dual providers exist without new env requirements.
+
+## Feature Flags & Migrations
+
+None. Additive API. No feature flag.
+
+## Activity Log & User Updates
+
+`AIRequest` remains the audit log. No user-facing activity feed.
+
+## Not Included / Future Work
+
+- RAG / embeddings (comparison item 2).
+- Agent-as-tool / sub-agents.
+- Human tool approval.
+- `AiApp` `agent` option mounting a dedicated route.
+- Failover on mid-stream errors.
+- Combining structured schema with tool loops in one `run`.
+
+## Files to Create / Modify
+
+| File | Change |
+| --- | --- |
+| `ai/src/service/failoverModel.ts` | `createFailoverModel`, `isFailoverableError` |
+| `ai/src/service/failoverModel.test.ts` | Mock `doGenerate` / `doStream`; 429 then success; non-failoverable does not switch; empty list throws; stream reject-before-return vs after-return |
+| `ai/src/agent/agent.ts` | `Agent` class |
+| `ai/src/agent/agent.test.ts` | Instructions sent as system; schema path; tools path; middleware order |
+| `ai/src/service/aiService.ts` | Read `lastServedModelId` when logging; optional `requestType` passthrough only if needed (prefer Agent calling existing methods + metadata) |
+| `ai/src/types/index.ts` | Types; `"agent"` request type |
+| `ai/src/routes/aiRequestsExplorer.ts` | Filter includes `agent` |
+| `ai/src/index.ts` | Exports |
+| `docs/reference/ai.md` | Agent + failover sections |
+| `docs/how-to/define-an-ai-agent.md` | New how-to |
+| `docs/how-to/configure-ai-failover.md` | New how-to |
+| `docs/how-to/README.md` | Links |
+| `.cursor/rules/ai/00-ai.mdc` (source of truth for rules sync) | Public API notes |
+| `skills/ai-prompt-governance/SKILL.md` | Agent instructions = named constants |
+| `ai/README.md` | Short mention + link to reference |
+| `docs/tasks/ai-agents-and-failover.md` | This plan's task list |
+| `example-backend/src/api/ai.ts` | Optional Phase 5 only |
+
+## Task List
+
+[`docs/tasks/ai-agents-and-failover.md`](../tasks/ai-agents-and-failover.md)
+
+## Acceptance Criteria
+
+- [ ] `createFailoverModel` with two mocks: first `doGenerate` throws failoverable 429, second returns text; `AIService.generateText` returns the second text; `AIRequest.aiModel` is the second `modelId`; `metadata.failover.attempts` has length 2.
+- [ ] First mock throws 400; second is never called; error propagates.
+- [ ] `doStream` that **returns** a stream then errors does not call the next model.
+- [ ] `Agent` with named instruction constant: mock receives that string as `system` (or equivalent SDK field); `AIRequest` has `requestType: "agent"` and `metadata.agentName`.
+- [ ] `Agent` with `schema` returns a typed object via `generateJsonObject` (existing JSON normalization still applies).
+- [ ] Middleware runs in order; a middleware that returns without `next` short-circuits (no model call).
+- [ ] `docs/reference/ai.md` documents both APIs with one minimal example each.
+- [ ] `bun test` in `ai/` passes; `bun run compile` for `ai` succeeds.
+- [ ] No new Express routes; existing GPT tests still pass.

package/dist/docs/versioned/next/implementationPlans/ai-dev-loop-boost.md

@@ -1,6 +1,6 @@
 # Implementation Plan: The AI Development Loop (Boost)
 
-**Status:** Draft — key decisions recorded (2026-07-29)
+**Status:** Approved — key decisions recorded (2026-07-29)
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1014
 **Priority:** High
 **Effort:** Big batch