@terreno/mcp 57.20.0 → 57.22.0

package/dist/docs/versioned/57.21.0/user-guide/account/profile.md

@@ -0,0 +1,43 @@
+---
+title: Update your profile
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I change my name?
+  - How do I change my email address?
+  - How do I change my password?
+  - How do I turn on dark mode?
+screens: [example-frontend/app/(tabs)/profile.tsx]
+added: user-guide-backfill
+---
+
+# Update your profile
+
+## What it does
+
+The **Profile** tab shows your account details and lets you change your name, email,
+password, and how the app looks.
+
+## How to use it
+
+1. Open the **Profile** tab.
+2. Under **Account Details**, tap the edit control next to **Name**, **Email**, or
+   **New Password**.
+3. Enter the new value and tap **Save**. Tap **Cancel** to keep the old value.
+
+When you change **Email**, also enter your **Current password** in the field that appears.
+**Profile updated successfully!** confirms the change.
+
+To switch the app's colors, turn **Dark mode** on or off under **Appearance**.
+
+## Intended use
+
+Use **Profile** to keep your own account details current. Leave **New Password** blank to
+keep your current password. After changing your email, confirm the new address; see
+[Confirm your email address](verify-email.md).
+
+## Related
+
+- [Choose how you get notifications](notification-preferences.md)
+- [Sign in](sign-in.md)

package/dist/docs/versioned/57.21.0/user-guide/account/reset-password.md

@@ -0,0 +1,42 @@
+---
+title: Reset your password
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - I forgot my password. How do I reset it?
+  - How do I get a password reset email?
+  - My reset link says it is missing a token. What do I do?
+screens: [example-frontend/app/forgotPassword.tsx, example-frontend/app/resetPassword.tsx]
+added: user-guide-backfill
+---
+
+# Reset your password
+
+## What it does
+
+If you forget your password, the app emails you a link to choose a new one.
+
+## How to use it
+
+1. On **Welcome Back**, tap **Forgot password?**.
+2. On **Forgot password**, enter your **Email** and tap **Send reset link**.
+3. When **Check your email** appears, open the reset email and follow its link.
+4. On **Reset password**, enter a **New password** of at least six characters and tap
+   **Save new password**.
+5. When **Password updated** appears, tap **Back to login** and sign in with the new
+   password.
+
+## Intended use
+
+Use this when you cannot sign in because you forgot your password. The app shows the same
+**Check your email** message whether or not an account uses that address, so it never
+reveals who has an account. If the email does not arrive, check your spam folder. If the
+reset page says the link is missing a token, request a new email from **Forgot password**.
+
+To change a password you still know, use **New Password** on the **Profile** tab instead;
+see [Update your profile](profile.md).
+
+## Related
+
+- [Sign in](sign-in.md)

package/dist/docs/versioned/57.21.0/user-guide/account/sign-in.md

@@ -0,0 +1,41 @@
+---
+title: Sign in
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I sign in?
+  - How do I log in with Google, GitHub, or Apple?
+  - How do I log out?
+screens: [example-frontend/app/login.tsx, example-frontend/app/(tabs)/profile.tsx]
+added: user-guide-backfill
+---
+
+# Sign in
+
+## What it does
+
+Signing in opens your account on this device so you can see your todos, chats, and files.
+
+## How to use it
+
+1. On **Welcome Back**, enter your **Email** and **Password**.
+2. Tap **Log In**.
+
+You land on **Todos**. To sign in with another account provider, tap
+**Continue with Google**, **Continue with GitHub**, or **Continue with Apple** and finish
+signing in with that provider.
+
+To sign out, open the **Profile** tab and tap **Logout** under **Session**.
+
+## Intended use
+
+Use the same method you signed up with. If you forgot your password, tap
+**Forgot password?** on **Welcome Back**; see [Reset your password](reset-password.md).
+If sign-in fails, the screen shows **Sign in failed. Please try again.**; check your
+email and password, then try again.
+
+## Related
+
+- [Create an account](sign-up.md)
+- [Reset your password](reset-password.md)

package/dist/docs/versioned/57.21.0/user-guide/account/sign-up.md

@@ -0,0 +1,40 @@
+---
+title: Create an account
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I create an account?
+  - How do I sign up?
+  - Can I sign up with Google, GitHub, or Apple?
+screens: [example-frontend/app/signup.tsx, example-frontend/app/login.tsx]
+added: user-guide-backfill
+---
+
+# Create an account
+
+## What it does
+
+Creating an account gives you your own todos, chats, files, and settings. You can sign up
+with an email address and password, or with a Google, GitHub, or Apple account.
+
+## How to use it
+
+1. On **Welcome Back**, tap **Need an account? Sign Up**.
+2. On **Create Account**, enter your **Name**, **Email**, and **Password**. The password
+   requirements under the field turn on as you meet them.
+3. Tap **Sign Up**.
+
+You land on **Todos**, signed in. To use another account provider instead, tap
+**Continue with Google**, **Continue with GitHub**, or **Continue with Apple** on
+**Create Account** and finish signing in with that provider.
+
+## Intended use
+
+Create one account per person. If you already have an account, tap
+**Already have an account? Log in** instead. After signing up, confirm your email address
+so you can recover the account later; see [Confirm your email address](verify-email.md).
+
+## Related
+
+- [Sign in](sign-in.md)

package/dist/docs/versioned/57.21.0/user-guide/account/verify-email.md

@@ -0,0 +1,37 @@
+---
+title: Confirm your email address
+area: account
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I verify my email?
+  - How do I resend the verification email?
+  - Why does my profile say to verify my email?
+screens: [example-frontend/app/verifyEmail.tsx, example-frontend/app/(tabs)/profile.tsx]
+added: user-guide-backfill
+---
+
+# Confirm your email address
+
+## What it does
+
+Confirming your email address proves the address is yours, so you can recover the account
+if you lose your password.
+
+## How to use it
+
+1. Open the verification email and follow its link.
+2. On the page that opens, tap **Confirm email**.
+
+To get a new verification email, open the **Profile** tab. Under the banner
+**Verify your email to keep this account recoverable.**, tap **Resend**.
+
+## Intended use
+
+Confirm the address once after you sign up, and again after you change your email. The
+banner on **Profile** disappears once the address is confirmed. If the page says the link
+is missing a token, send a new email from **Profile** and use the newest link.
+
+## Related
+
+- [Update your profile](profile.md)

package/dist/docs/versioned/57.21.0/user-guide/admin/manage-records.md

@@ -0,0 +1,44 @@
+---
+title: Browse and edit records in the admin panel
+area: admin
+audience: admin
+platforms: [web, ios, android]
+questions:
+  - How do I open the admin panel?
+  - How do I find a user or a todo as an admin?
+  - How do I create, edit, or delete a record?
+screens:
+  - "example-frontend/app/(tabs)/profile.tsx"
+  - "example-frontend/app/admin/index.tsx"
+  - "example-frontend/app/admin/[model]/index.tsx"
+  - "example-frontend/app/admin/[model]/[id].tsx"
+added: user-guide-backfill
+---
+
+# Browse and edit records in the admin panel
+
+## What it does
+
+The admin panel lets administrators view and change the app's records, such as
+**Users** and **Todos**, in tables with search, sorting, and paging.
+
+## How to use it
+
+1. Open the **Profile** tab and, under **Developer**, tap **Admin Panel**.
+2. In the side menu, choose a section such as **Users** or **Todos**.
+3. Search or sort the table to find a record, then tap its row to open it.
+4. Change fields and tap **Save**.
+
+To add a record, open a section and tap **Create**, fill in the fields, and tap
+**Create**. To remove one, use its delete action and confirm
+**Are you sure you want to delete this item?**. Tap **Refresh** to reload the table.
+
+## Intended use
+
+The admin panel is for administrators maintaining the app's data. It only appears for
+accounts with admin access. Changes apply right away and affect every user, and deleted
+records cannot be restored from the panel.
+
+## Related
+
+- [Set a user's password](set-user-password.md)

package/dist/docs/versioned/57.21.0/user-guide/admin/set-user-password.md

@@ -0,0 +1,37 @@
+---
+title: Set a user's password
+area: admin
+audience: admin
+platforms: [web, ios, android]
+questions:
+  - How do I reset a user's password as an admin?
+  - A user is locked out. How do I give them a new password?
+screens:
+  - "example-frontend/app/admin/[model]/[id].tsx"
+added: user-guide-backfill
+---
+
+# Set a user's password
+
+## What it does
+
+An administrator can give a user a new password directly, without an email.
+
+## How to use it
+
+1. Open the admin panel and choose **Users**.
+2. Tap the user's row.
+3. Under **Set Password**, enter the **New Password** and the same value in
+   **Confirm Password**.
+4. Tap **Set Password**. **Password updated** confirms the change.
+
+## Intended use
+
+Use this when a user cannot reset their own password by email. The new password must be at
+least eight characters and takes effect immediately. Share it with the user through a
+private channel and ask them to change it from their **Profile**. When the user can reach
+their email, point them to **Forgot password?** instead.
+
+## Related
+
+- [Browse and edit records in the admin panel](manage-records.md)

package/dist/docs/versioned/57.21.0/user-guide/ai/chat.md

@@ -0,0 +1,40 @@
+---
+title: Chat with the AI assistant
+area: ai
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I ask the AI a question?
+  - How do I start a new chat?
+  - How do I delete or rename a chat?
+  - Can I attach a file to a chat?
+  - How do I rate an answer?
+screens: [example-frontend/app/(tabs)/ai.tsx]
+added: user-guide-backfill
+---
+
+# Chat with the AI assistant
+
+## What it does
+
+The **AI** tab is a chat with an AI assistant. It keeps each conversation under **Chats**
+so you can come back to it later.
+
+## How to use it
+
+1. Open the **AI** tab.
+2. Type in **Type a message...** and tap **Send**. The answer appears as it is written.
+3. To start a fresh conversation, tap **New chat** (the plus button next to **Chats**).
+4. To return to an earlier conversation, tap it under **Chats**.
+
+To rename a chat, edit its title in the list and save it. To delete one, use its delete
+button in the list. To rate an answer, tap **Thumbs up** or **Thumbs down** under it, and
+tap **Copy message** to copy its text. When the attach button shows next to the message
+box, use it to add files to your message.
+
+## Intended use
+
+Use the assistant for questions, drafting, and working with your todos and files. When it
+needs a choice or confirmation from you, it shows a card in the chat; answer it to let the
+assistant continue. Answers can be wrong, so check anything important. Do not share
+passwords or other secrets in a chat.

package/dist/docs/versioned/57.21.0/user-guide/documents/files.md

@@ -0,0 +1,37 @@
+---
+title: Store and organize files
+area: documents
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I upload a file?
+  - How do I create a folder?
+  - How do I download or delete a file?
+  - Where can I see the consent forms I agreed to?
+screens: [example-frontend/app/(tabs)/documents.tsx]
+added: user-guide-backfill
+---
+
+# Store and organize files
+
+## What it does
+
+The **Documents** tab holds your files in folders. Its **Consents** section lists the
+consent forms you have agreed to.
+
+## How to use it
+
+1. Open the **Documents** tab. **Files** is selected at the top.
+2. To add a file, tap **Upload file** and choose it.
+3. To make a folder, tap **New folder**, enter a **Folder Name**, and tap **Create**.
+4. Tap a folder to open it.
+5. To remove a file, tap **Delete** on its row. On the web, tap **Download** on a file's
+   row to save a copy.
+
+To review the consent forms you signed, tap **Consents** at the top.
+
+## Intended use
+
+Use **Files** for your own documents. **Upload file** only shows when uploads are turned
+on for your account, and **Download** is available on the web. Deleting a file removes it
+for good.

package/dist/docs/versioned/57.21.0/user-guide/todos/manage-todos.md

@@ -0,0 +1,37 @@
+---
+title: Add, complete, rename, and delete todos
+area: todos
+audience: user
+platforms: [web, ios, android]
+questions:
+  - How do I add a todo?
+  - How do I mark a todo as done?
+  - How do I rename a todo?
+  - How do I delete a todo?
+  - Do my todos work offline?
+screens: [example-frontend/app/(tabs)/index.tsx]
+added: user-guide-backfill
+---
+
+# Add, complete, rename, and delete todos
+
+## What it does
+
+**My Todos** keeps your personal list of things to do. Open todos appear under **To Do**,
+and finished ones move to **Completed**. A count under the title shows how many remain.
+
+## How to use it
+
+1. Open the **Todos** tab.
+2. Type in **New Todo** and tap **Add Todo**. The todo appears at the top of **To Do**.
+3. Tap the checkbox next to a todo to mark it done. Tap it again to move it back to
+   **To Do**.
+4. To rename a todo, tap its title or the edit button next to it, type the new title, and
+   press Enter or tap away from the field.
+5. To delete a todo, tap the trash button next to it.
+
+## Intended use
+
+Use todos for your own tasks; other people cannot see them. Changes show at once, even
+without a connection, and sync when the device is back online. A deleted todo cannot be
+restored.

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

@@ -57,6 +57,18 @@ Canonical copy, language rules, and the Django/Rails comparison:
 
 **Migrating from RTK?** See [How to migrate from @terreno/rtk to @terreno/syncdb](how-to/migrate-rtk-to-syncdb.md).
 
+## Testing
+
+- [E2E testing guide](testing/e2e.md) — the test tiers, smoke conventions, Playwright and
+  Maestro specs, and one page per package on how it is e2e-tested
+- [Regression suites](regression/README.md) — the manual cases a person walks before a release,
+  one file per area
+
+## User guide
+
+- [User guide](user-guide/README.md) — one page per example-app feature, in end-user words,
+  for chat agents answering "how do I…" questions
+
 ## Quick links
 
 - [Getting started](tutorials/getting-started.md)

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

@@ -17,7 +17,7 @@ Understanding-oriented documentation: concepts, architecture, and context.
 - [Install agent skills](../how-to/install-agent-skills.md) — `npx skills add TerrenoLabs/terreno`
 - [AI development loop](ai-development-loop.md) — The five-stage Ask, Generate, Run, Observe, Fix loop, what the agent can and cannot see, and how it composes with expo-mcp, Playwright MCP, and Maestro
 - [Agent guidelines](agent-guidelines.md) — How hosted docs, per-package `.ai/` guidelines, and `.rulesync/` rules reach an agent, and how apps extend them
-- [AI observability](ai-observability.md) — Two planes (telemetry vs control), plugins vs LangfuseApp, SOP loop
+- [AI observability](ai-observability.md) — Two planes (telemetry vs control), plugins, SOP loop
 - [Durable agent harness](durable-agent-harness.md) — Phases, checkpoints, and why the audit span shares the checkpoint transaction
 - [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
 - [Agent UI Asks](agent-ui-asks.md) — Why agent questions are client-side tool calls, the pause and resume round trip, why cards carry exact answers, the watch paths, asks vs blocks

package/dist/docs/versioned/next/explanation/admin-interface.md

@@ -64,6 +64,9 @@ admin `Stack`); otherwise its default light screen containers cover the canvas.
 `padding={0}` so cards sit on that canvas. Custom screens wrap content in
 `AdminScreenPage`; the back arrow uses `router.push(routeBase)` rather than
 `router.back()` because sidebar clicks do not always leave history on web.
+Nested model stacks (`app/admin/[model]/_layout.tsx` and `admin-spa/app/[model]/_layout.tsx`)
+set `headerShown: false` so Expo does not title the screen `index` or add a second back arrow.
+Page components do not draw their own navigator arrows.
 
 ## Where code goes
 

package/dist/docs/versioned/next/explanation/agent-guidelines.md

@@ -9,7 +9,7 @@ and every other copy is generated from it.
 | Hosted MCP docs | `docs/`, `website/versioned_docs/`, `mcp-server/src/docs/resources/` | `terreno_search_docs`, `terreno_get_component_docs`, `terreno://docs/*` resources | Shipped |
 | Per-package guidelines | `<package>/.ai/guidelines/core.md` | Merged into the files `terreno_bootstrap_ai_rules` returns | Shipped |
 | App rule files | The app's `.rulesync/rules/` | Generated per editor by `rulesync generate` | Shipped |
-| Agent skills | `plugins/terreno-planning/skills/`, `plugins/terreno-scan/skills/`, `.rulesync/skills/` | `npx skills add TerrenoLabs/terreno` or a host plugin | Shipped |
+| Agent skills | `plugins/terreno-planning/skills/`, `plugins/terreno-loop/skills/`, `.rulesync/skills/` | `npx skills add TerrenoLabs/terreno` or a host plugin | Shipped |
 
 The runtime side of the loop, meaning what the agent can see in a running app, is covered
 in [AI development loop](ai-development-loop.md). This page covers only conventions.
@@ -108,7 +108,7 @@ In this repository:
 | --- | --- |
 | `.rulesync/rules/**` | `CLAUDE.md`, `.claude/rules/`, `AGENTS.md`, `.cursor/rules/`, `.github/copilot-instructions.md`, `.github/instructions/`, `.devin/rules/` |
 | `.rulesync/skills/`, `.rulesync/subagents/`, `.rulesync/hooks.json` | Per-host skill, subagent, and hook directories (`.claude/`, `.cursor/`, `.github/`, `.devin/`, `.agents/`) |
-| `plugins/terreno-planning/skills/`, `plugins/terreno-scan/skills/`, plus `.rulesync/skills/` | `skills/` (installable set), `plugins/terreno-claude/` and `plugins/terreno-scan-claude/` (Claude Code plugins) |
+| `plugins/terreno-planning/skills/`, `plugins/terreno-loop/skills/`, plus `.rulesync/skills/` | `skills/` (installable set), `plugins/terreno-claude/` and `plugins/terreno-loop-claude/` (Claude Code plugins) |
 
 `rulesync.jsonc` maps each target to its features. `bun run rules` regenerates the rulesync
 targets. `bun run skills:sync` regenerates `skills/` and the Claude plugin. The

package/dist/docs/versioned/next/explanation/ai-observability.md

@@ -1,26 +1,26 @@
 # AI observability
 
-Terreno ships Langfuse-like prompt versioning, nested traces, evaluators, datasets, experiments, and a local human review queue **inside `@terreno/ai`**, with operator UI in **`admin-frontend` only**.
+Terreno ships prompt versioning, nested traces, evaluators, datasets, experiments, and a local human review queue **inside `@terreno/ai`**, with operator UI in **`admin-frontend` only**.
 
-## Why not Langfuse-only
+## Why built in
 
-Apps must iterate prompts without a required vendor account. `LangfuseApp` stays a second plugin. Traces and scores **fan out** to every registered sink (local Mongo, Langfuse, OTLP/OpenInference). Prompts, datasets, experiments, and the review queue have **one writer** each (a primary). The review queue is **local-only**.
+Apps must iterate prompts without a required vendor account, so the prompt registry, traces, and review queue live in the app's own Mongo. Traces and scores **fan out** to every registered sink (local Mongo plus any extra `TraceSink` / `ScoreSink` plugin an app registers). Prompts, datasets, experiments, and the review queue have **one writer** each (a primary). The review queue is **local-only**.
 
 That split is the two planes:
 
 | Plane | Write | Admin read |
 | --- | --- | --- |
-| Telemetry (traces, scores) | All sinks, best-effort | Local if the local plugin is on, else Langfuse |
+| Telemetry (traces, scores) | All sinks, best-effort | Local |
 | Control (prompts, datasets, experiments, queue) | One primary per capability | That primary |
 
-`experiments.primary` must equal `datasets.primary`. Defaults are all `local`.
+`local` is the only control primary, and the default for all four. `experiments.primary` must equal `datasets.primary`.
 
 `ObservabilityApp` fails boot (constructor throws) when:
 
 | Error | Cause |
 | --- | --- |
 | `experiments.primary must equal datasets.primary` | Mixed dataset/experiment writers |
-| `reviewQueue.primary must be local` | `reviewQueue` set to `langfuse` |
+| `reviewQueue.primary must be local` | `reviewQueue` set to anything but `local` |
 | `<capability> primary "<id>" has no plugin` | No registered plugin with that `id`, capability, and store |
 
 Telemetry sinks still fan out even when a control primary is local-only.
@@ -28,8 +28,10 @@ Telemetry sinks still fan out even when a control primary is local-only.
 Admin chrome lives in `admin-frontend`. One sidebar group **AI Observability** holds Prompts,
 Traces, Evaluators, Datasets, Experiments, and Review (Review is omitted when the local plugin is
 off). Existing **AI Requests** stays under **Screens**. Every observability screen shows
-breadcrumbs `Admin / AI Observability / <Section> / <leaf>` and a status chip from
-`GET /ai/observability/status`. Prompt detail is a hub (Overview, Versions, Traces, Experiments);
+breadcrumbs (`Admin / AI Observability / <Section>` on lists, plus `/ <leaf>` on detail
+screens), a quiet status chip from `GET /ai/observability/status`, and one left-aligned page
+header with the screen's single primary action. Prompt detail is a hub (Versions, Traces, Experiments).
+Versions shows the description, folder, tags, and the version editor on one screen;
 versions are immutable in admin (`Save as vN+1`); apps never inline the string.
 
 ## Why this shape for product work
@@ -58,7 +60,7 @@ customized `admin` and `auditor` roles gain only missing observability actions o
 
 ## Prompt hub relationships (phase 4)
 
-Prompts may carry an optional domain-neutral `description` (folder semantics stay consumer-defined). `GET /ai/observability/prompts/:name` composes bounded recent **traces** and **experiments** for that prompt name so the admin hub does not scan full trace or experiment lists on the client. Trace evidence is version-aware: list filters accept `prompt` plus optional `promptVersion`, and relationship trace rows include the matching `promptVersion` from `ObsTrace.prompts[]`. The same optional positive integer `promptVersion` on prompt detail filters hub traces with `$elemMatch` on `prompts` (name and version). Omit it to keep the unfiltered prompt-name match. Invalid or non-positive versions return **400**. Experiment relationships filter server-side by `promptName` on `GET /ai/observability/experiments?promptName=…` (omit or pass an empty value for no filter). The experiment list endpoint returns summary rows without per-item hydration; use experiment detail for full item results. Reading relationships uses the same `aiPrompt:read` grant as prompt detail.
+Prompts may carry an optional domain-neutral `description` (folder semantics stay consumer-defined). `GET /ai/observability/prompts/:name` composes bounded recent **traces** and **experiments** for that prompt name so the admin hub does not scan full trace or experiment lists on the client. Trace evidence is version-aware: list filters accept `prompt` plus optional `promptVersion`, and relationship trace rows include the matching `promptVersion` from `ObsTrace.prompts[]`. The same optional positive integer `promptVersion` on prompt detail filters hub traces with `$elemMatch` on `prompts` (name and version). Omit it to keep the unfiltered prompt-name match. Invalid or non-positive versions return **400**. Experiment relationships filter server-side by `promptName` on `GET /ai/observability/experiments?promptName=…` (omit or pass an empty value for no filter). The experiment list endpoint returns summary rows without per-item hydration; use experiment detail for full item results. Reading relationships uses the same `aiPrompt:read` grant as prompt detail. Detail also returns `usedBy` (`items`, `limit`, `total`): other prompts whose saved text contains `{{> this name}}`, capped at 20 like the other relationships. The editor inserts that tag from the **Insert prompt reference** modal.
 
 ## Phase 1 reference loop
 
@@ -67,7 +69,7 @@ The example backend always registers the local plugin. Its idempotent seed creat
 `correctness-human` evaluator, the automatic `schema-assert` evaluator, and a two-item
 `example-gold` dataset. It also creates `chat-safety-synthetic`, a proofread set of
 two-person chats for routing, toxicity, privacy, and dismissive-reply experiments.
-This makes the review and experiment loops walkable without Langfuse:
+This makes the review and experiment loops walkable with no external service:
 resolve the production prompt → emit a trace → inspect spans and sensitive I/O → send the
 trace to Review → record a human score.
 
@@ -87,11 +89,35 @@ With the local plugin registered and primaries set to `local`, the control plane
 
 - **`llm-judge` and `json-assert` evaluators** — judges call `AIService.generateJsonObject` through a named registry prompt (`judgePromptName`); create/update rejects a judge when the prompt `outputSchema` omits a required dimension (the error names that key). `json-assert` supports path/constraint checks and a built-in mode that validates output against the prompt version `outputSchema`. Parse or generation failures record an error outcome instead of throwing to the caller. Custom creates score a full trace; generation span and dataset item targets are reserved. Seeded templates install `correctness` / `hallucination` / `helpfulness` / `toxicity` as `llm-judge`, `schema-assert` as `json-assert`, and `*-human` variants for the review queue.
 - **Human review evaluators** — sending traces to review requires a `human` evaluator. Its dimensions become the review item's score fields and its instructions tell the reviewer how to apply them. `llm-judge` and `json-assert` evaluators run automatically and are rejected from the human queue.
+- **Review batches and judge agreement** — a human evaluator with several yes/no dimensions (each with a reviewer `question`) acts as a question set. A batch fixes the traces people answer, so an operator can run any number of LLM judges over the same traces and see, per judge and per question, how often the judge gives the human answer. That number is what tells you a new judge can replace or extend human review; disagreements point at the prompt rule to fix.
 - **Datasets** — CRUD plus item provenance (`origin`, `proofread`, `sourceTraceId`, tags, outcome class). Import accepts **JSON** (bare objects or structured rows) and **CSV** (quoted fields; `input.*` / `expectedOutput.*` column prefixes). Rows validate against the bound prompt input schema when configured. Adding from a trace copies I/O; sensitive traces always land `proofread: false`. Deleting an item never mutates the trace.
-- **Experiments** — compare 2–3 prompt versions on a dataset with optional `modelOverride` (requires `aiServiceFactory` on `ObservabilityApp`), evaluator thresholds (defaulting to the SOP gates), **per-version gate tiles** (`gates[].version`), outlier/low-confidence item ids, and version-scoped promote (**409** when the selected version's gates fail). Unproofread items are excluded unless `includeUnproofread` is true. Local runs compile exact prompt versions and call `AIService.generateText` with compiled `prompt` + `systemPrompt` (no `promptName`/`promptLabel`). `ObservabilityApp` wires the local experiment runner from `aiService` at register time.
+- **Experiments** — compare 2–3 prompt versions on a dataset with optional `modelOverride` (requires `aiServiceFactory` on `ObservabilityApp`), evaluator thresholds (defaulting to the SOP gates), **per-version gate tiles** (`gates[].version`; the results screen groups them in one card per version and shows operators as ≥ ≤ > < =, never `gte`/`lte`), outlier/low-confidence item ids, and version-scoped promote (**409** when the selected version's gates fail). Unproofread items are excluded unless `includeUnproofread` is true. Local runs compile exact prompt versions and call `AIService.generateText` with compiled `prompt` + `systemPrompt` (no `promptName`/`promptLabel`). `ObservabilityApp` wires the local experiment runner from `aiService` at register time.
 
 Operator UI for datasets and experiments ships in tasks 2.7–2.9; routes and stores are live for API clients and tests today.
 
+## The eval pipeline: humans first, then calibrated judges
+
+Terreno's evaluation flow has four steps, and each step reuses the one before it:
+
+1. **Build a dataset** of traces (or hand-written items).
+2. **Humans answer a question set** — a `human` evaluator whose dimensions are usually yes/no
+   `question`s — for every dataset item, through review batches built from the dataset. Each
+   submitted answer is written back onto the dataset item (`humanAnswers`).
+3. **Calibrate the judge.** A judge calibration experiment (`kind: "judge"`) runs 2–3 versions of
+   an LLM judge's prompt over the human-answered items and ranks the versions by agreement with
+   the humans. Iterate on the judge prompt until a version clears the target (default 90%), then
+   promote it.
+4. **Compare product prompts** with ordinary prompt experiments, scored by a judge whose
+   calibration (latest agreement, and whether it is stale) shows on the evaluator.
+
+Human answers are expensive, so they are reused: a dataset judged once feeds any number of judge
+experiments. The rule that keeps reuse honest is the **question fingerprint** — a hash of each
+question's key, type, wording, and range. Answers stay *current* while the fingerprint matches;
+rewording a question makes them *stale*, the dataset shows them as stale, new review batches
+re-queue those items, and judge calibrations based on the old wording are flagged stale.
+Judges always see what reviewers saw (the source trace, else the item's input and expected
+output), so agreement measures the judge, not a difference in evidence.
+
 ## GPT tool spans and nested traces
 
 `/gpt/prompt` streams tool rounds to the client **and** records them in observability traces. Each provider `tool-call` / `tool-result` pair becomes a `TOOL` span (input args, cleaned output, timing, `parentSpanId` on the chain root). When tools run, the exported trace uses a `CHAIN` root wrapping those `TOOL` children instead of a lone `LLM` span. Plain `AIService.generate*` calls without tool children still log a single `LLM` root.

package/dist/docs/versioned/next/explanation/durable-agent-harness.md

@@ -69,7 +69,7 @@ transaction:
 
 Either all three land or none do. This is why `Harness.open` refuses to start without a
 replica set (transactions need one) or without the local observability models. Planned
-Langfuse and OTel exports will stay best-effort, after the transaction.
+exports to other trace sinks will stay best-effort, after the transaction.
 
 ```
 createTask ──tx──> HarnessTask(pending) + ObsTrace + root CHAIN span

package/dist/docs/versioned/next/explanation/loop-engineering.md

@@ -119,9 +119,9 @@ include:
 | --- | --- |
 | Backend/API/data | `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env`, `generate-sdk`, `terreno-data-fetching` |
 | UI/app | `terreno-ui`, `building-terreno-apps`, `verify-ui-changes` |
-| Testing | `terreno-test-setup`, `terreno-backend-tests`, `terreno-frontend-tests`, `terreno-mobile-tests` |
+| Testing | `terreno-test-setup`, `terreno-backend-tests`, `terreno-frontend-tests`, `terreno-mobile-tests`, `backfill-regression` |
 | AI/prompts | `ai-prompt-governance` — new features also follow [Develop an AI feature](../how-to/ai-feature-development.md) |
-| Docs/submission | `update-docs`, Brew, `fix-conflicts` |
+| Docs/submission | `update-docs`, `backfill-user-guide`, Brew, `fix-conflicts` |
 | GitHub issues | `create-github-issue`, `work-github-issues`, `implement-ready-for-dev` (Pick plan comment is the Roast contract; unattended Grow may also write an IP) |
 | Deployment/runtime | `deploy-gcp`, Expo deployment/workflow skills |