@terreno/mcp 57.11.0 → 57.12.0

package/dist/docs/upgrades/57.12.0.md

@@ -0,0 +1,89 @@
+# Upgrading to 57.12.0
+
+**Action required:** Yes
+**Affected packages:** @terreno/ai
+
+## Summary
+
+Harness tasks can record a trace scope, tags, and prompt versions, and `@terreno/ai` publishes official subpath exports. The chat `Project` model registers on first use instead of at import, and harness task HTTP responses no longer include the lease fencing token.
+
+## Breaking changes
+
+### `Project` is no longer registered on import
+
+**What changed**
+
+Importing `@terreno/ai` does not register mongoose model `Project`. The exported `Project` is a lazy proxy. The first property access, `new Project(...)`, or `getProjectModel()` registers the model. Statics and `instanceof Project` still work. These do not:
+
+- `Project === mongoose.models.Project` (and `Project === mongoose.model("Project")`)
+- `Object.keys(Project)` (always empty)
+- reading `Project.prototype` (throws)
+
+`new AiApp()` still mounts `/gpt/projects` and registers the model when those routes load. `new AiApp({projects: false})` skips those routes.
+
+**Why**
+
+An app that imports `@terreno/ai` and owns its own model named `Project` was hitting a mongoose overwrite error at import time.
+
+**Migration**
+
+```typescript
+// Before
+import {Project} from "@terreno/ai";
+
+const project = await Project.findExactlyOne({_id: id});
+if (mongoose.models.Project === Project) {
+  // identity check
+}
+
+// After
+import {getProjectModel} from "@terreno/ai";
+
+const Project = getProjectModel();
+const project = await Project.findExactlyOne({_id: id});
+```
+
+To keep a separate app model named `Project`, do not call `getProjectModel()` or touch the `Project` export, and skip the AI project routes:
+
+```typescript
+new AiApp({aiService, projects: false});
+```
+
+### Harness task HTTP responses omit `lease`
+
+**What changed**
+
+`GET /harness/tasks/:id` no longer includes `lease`. The OpenAPI schema for that response omits it too. Collection list is disabled (`list: []`, 405). The token is still stored on the task document for runners.
+
+**Why**
+
+`lease.token` is the fencing token that decides which runner may commit. It is not a client field.
+
+**Migration**
+
+```typescript
+// Before
+const token = task.lease?.token;
+
+// After
+// Do not read lease from the HTTP task. Runners load it on the server.
+```
+
+Regenerate the OpenAPI SDK after upgrading `@terreno/ai` so generated task types drop `lease`.
+
+## Deprecations
+
+`Project` from `@terreno/ai` still works for `find`, `create`, `new`, and `instanceof`. It is deprecated. Call `getProjectModel()` and use that model. A later major can remove the proxy.
+
+## New capabilities
+
+- `harness.createTask(def, input, {trace: {scope, tags}, prompts})` writes a scope (tenant, workspace), tags, and prompt versions onto the task's `ObsTrace`. Child tasks and subagents share that trace. The admin trace list filters with `?scope=`.
+- `rt.runAgent` accepts `prompts` and a registry `PromptVersionRef` as `instructions`. It runs `body` and records the version on the trace.
+- Subpath exports: `@terreno/ai/admin`, `@terreno/ai/harness/agentLoop`, `@terreno/ai/harness/commit`, `@terreno/ai/harness/events`, `@terreno/ai/harness/internalRuntime`, `@terreno/ai/observability/observabilityApp`, `@terreno/ai/observability/localPlugin`, `@terreno/ai/observability/promptStore`.
+
+## Verification
+
+- Code that imported `Project` from `@terreno/ai`: switch identity checks and `mongoose.models.Project` reads to `getProjectModel()`.
+- An app that owns a model named `Project`: pass `projects: false` and do not call `getProjectModel()`.
+- Harness clients: confirm `GET /harness/tasks/:id` JSON has no `lease`, then regenerate the SDK.
+- `bun run compile` and `bun run lint` at the app root.

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

@@ -49,9 +49,10 @@ Maintains centralized agent guidance and generates the matching configuration fo
 
 Rulesync generates native hooks from `.rulesync/hooks.json`. Biome checks changed files
 after edits and staged files before commits. At agent stop,
-`.rulesync/hooks/quality-check.sh` runs lint, TypeScript compilation, Knip, and
-dependency-cruiser. It keeps stdout machine-readable for each host and prevents
-retry-triggered Stop hooks from rerunning the commands.
+`.rulesync/hooks/quality-check.sh` runs `bun install --frozen-lockfile` when
+`node_modules/typescript` or any workspace package link is missing, then runs lint,
+TypeScript compilation, Knip, and dependency-cruiser. It keeps stdout machine-readable
+for each host and prevents retry-triggered Stop hooks from rerunning the commands.
 
 Existing findings are ratcheted so the checks reject new debt without requiring unrelated
 cleanup. See [Static analysis](static-analysis.md).

package/dist/docs/versioned/next/explanation/roadmap-process.md

@@ -402,7 +402,7 @@ do not claim completion until done.
 | Workflow | Trigger | Purpose |
 | -------- | ------- | ------- |
 | [`.github/workflows/triage.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown + `type:*` from Kind when present; `area:*` / `type:*` labels the issue was opened with win, so `roadmap:sync` issues are not asked for an area |
-| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when it changes |
+| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when roadmap content changes. A new **Last updated** timestamp alone does not open a pull request |
 | [`.github/workflows/roadmap-sync.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-sync.yml) | Taxonomy files change on `master` + manual | Apply labels and reconcile the board's fields and items |
 | [`.github/workflows/roadmap-reconcile.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, add an entry for every new IP, open its tracking issue, push to the board, regenerate `ROADMAP.md` |
 All three share the `roadmap` concurrency group. They write the same board, and interleaving
@@ -495,4 +495,6 @@ GITHUB_TOKEN=$(gh auth token) TERRENO_PROJECT_NUMBER=... bun run roadmap:generat
 ```
 
 The generator exits non-zero when the project cannot be read, so a bad project number or a
-token without `read:project` fails loudly instead of writing an empty `ROADMAP.md`.
+token without `read:project` fails loudly instead of writing an empty `ROADMAP.md`. When the
+rendered list matches the file already on disk, it keeps that file's **Last updated** stamp
+and does not write. The daily workflow then sees a clean diff and does not open a pull request.

package/dist/docs/versioned/next/how-to/circleci.md

@@ -254,8 +254,12 @@ the review script so a PR cannot rewrite the reviewer.
 Netlify and GCP jobs **validate their context as the first step** and fail,
 before checkout or `bun install`, listing the missing variables. Preview jobs
 halt earlier on fork PRs, where CircleCI withholds contexts. Docker Layer
-Caching is off (200 credits per job). The docs Netlify target disables
-Docusaurus minification so the build stays within the 8 GB `large` executor.
+Caching is off (200 credits per job). The docs Netlify target builds only the
+current docs tree, disables Docusaurus minification, and pins SSG to one worker
+thread so the build peaks near 3 GB and fits the 4 GB `medium` executor.
+Released versions are not rebuilt: `archive-docs-version` (in `publish-release`,
+`X.Y.0` tags only) builds each one once and uploads it to its GitHub release, and
+`deploy-docs` unpacks those archives under `/<version>/`. See `website/README.md`.
 
 `terreno-gcp` uses CircleCI OIDC (`CIRCLE_OIDC_TOKEN_V2`), never a JSON service
 account key. Set `circleci_org_id`, `circleci_project_id`, and

package/dist/docs/versioned/next/how-to/github-actions-ci.md

@@ -7,24 +7,23 @@ describes how they behaved if one is ever re-enabled.
 
 ## Docs site (`docs-deploy.yml`)
 
-`Build docs site` is often the longest PR job because Docusaurus compiles every
-versioned tree under `website/versioned_docs/` and TypeDoc regenerates API
-pages.
+`Build docs site` is often the longest PR job because TypeDoc regenerates API
+pages. The site builds only the current docs tree; `website/versioned_docs/` is
+markdown for the MCP server.
 
 PR builds set `DOCS_PREVIEW=true` and pass `--no-minify`. Both PR and
 `master` use Docusaurus Faster (Rspack/SWC via `@docusaurus/faster`).
 
 | Behavior | PR preview | `master` production |
 | --- | --- | --- |
-| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted (`disableVersioning`) | Built |
+| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted | Prebuilt archives unpacked under `/<version>/` |
 | JS minify | Off | On |
 | Local search index | Skipped | Built |
 | Generated API + component MDX | Restored from cache when `api`/`rtk`/`ui` hashes match | Same cache, then full generate on miss |
 | TypeDoc workspace `tsc` | Once per generate (api+rtk deps share a process) | Same |
 | Rspack cache (`node_modules/.cache/rspack`) | Restored per `pull_request` vs `push` | Separate production key |
 
-Production still builds every version. Do not rely on `/57.1.0/…` URLs in a
-PR deploy preview.
+Do not rely on `/57.1.0/…` URLs in a PR deploy preview.
 
 ## Other high-cost jobs
 

package/dist/docs/versioned/next/reference/ai-harness.md

@@ -142,7 +142,7 @@ The `task` view passed to `run`: `{id, name, version, input, state, phase, attem
 | `Harness.open({registry, runner?, models?, env?, priceMap?, streaming?, testHooks?})` | Checks requirements, rejects a duplicate `name@version` or agent name, ensures collections and indexes exist. `runner` defaults to `new InProcessRunner()`. See [open options](#open-options). |
 | `start()` | Throws, claiming nothing, when any non-terminal task uses a `name@version` missing from the registry (see [Versioning](#versioning)). Then starts the runner. Throws when already started. The runner recovers expired tasks once it owns execution. |
 | `stop()` | Stops claiming work, waits (without a time limit) for every phase in flight while still renewing the owner lease, then releases it. No-op when not started. |
-| `createTask(definition, input, {requestId?, userId?})` | Inserts a `pending` task, its `ObsTrace`, and its root span in one transaction. Wakes the runner. The definition must be in the registry. |
+| `createTask(definition, input, {requestId?, userId?, trace?, prompts?})` | Inserts a `pending` task, its `ObsTrace`, and its root span in one transaction. Wakes the runner. The definition must be in the registry. See [Trace scope and prompt versions](#trace-scope-and-prompt-versions). |
 | `resolveInterrupted(id, {action, reason, result?, userId?})` | Resolve an `interrupted` task. See [resolveInterrupted](#resolveinterrupted). |
 | `abort(id, {reason, userId?})` | Abort a task and every non-terminal task it owns, bottom-up. See [abort](#abort). |
 | `decideApproval(approvalId, {approved, reason?, userId?})` | Approve or reject a pending approval without checking approvers. See [Approvals](#approvals). |
@@ -158,6 +158,30 @@ create with the same id returns the first task and leaves no extra trace. Reusin
 `requestId` for a different task name, or with a different `userId` (including none versus
 some), throws. A soft-deleted task still owns its `requestId`.
 
+### Trace scope and prompt versions
+
+A task's `ObsTrace` is its run record. `createTask` can label it:
+
+```typescript
+const prompt = await promptRegistry.get({label: "production", name: "intake-summary"});
+await harness.createTask(intakeSummary, {patientId}, {
+  prompts: prompt ? [prompt] : [],
+  trace: {scope: String(workspaceId), tags: ["nightly"]},
+  userId,
+});
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `trace.scope` | `string` | App-defined scope, such as a tenant or workspace id. Stored as `ObsTrace.scope`, indexed with `created` for per-scope metering (sum `LLM` span `usage.costUsd` by scope and month). Blank throws `harness-invalid-request`. |
+| `trace.tags` | `string[]` | App-defined labels, stored once each as `ObsTrace.tags`. A blank tag throws `harness-invalid-request`. |
+| `prompts` | `{name, version, label?}[]` | Prompt versions the task uses, stored once each on `ObsTrace.prompts`. A `PromptVersionRef` from `promptRegistry.get` fits as-is; its `body` is not stored. A ref without a name, with a non-string `label`, or without a positive integer `version` throws `harness-invalid-request`. |
+
+Child tasks and subagents write into the root task's trace, so they share its scope and
+tags. `rt.runAgent` adds its own prompt versions to the same trace (see
+[Subagents](#subagents-rtrunagent)). The admin trace list filters by `scope` and by
+prompt.
+
 ### open options
 
 | Option | Type | Description |
@@ -306,7 +330,7 @@ where `lease` is `{owner, duration, heartbeat}` (Luxon `Duration`s). With `maxPh
 | `rt.signal` | `AbortSignal`. Aborts when the task is aborted (at once in this process, within one heartbeat elsewhere), or when this run loses its lease. Pass it to cancellable calls. |
 | `rt.createTask(definition, input, {background?, key?})` | Create a child task. Returns its id. See [Child tasks and waitForTasks](#child-tasks-and-waitfortasks). |
 | `rt.waitForTasks(ids, {policy?})` | Return child outcomes once they settle; until then the task waits. See [Child tasks and waitForTasks](#child-tasks-and-waitfortasks). |
-| `rt.runAgent(agent, {input, output?, instructions?})` | Run a registered agent as a subagent and return its answer; until it finishes the task waits. See [Subagents (rt.runAgent)](#subagents-rtrunagent). |
+| `rt.runAgent(agent, {input, output?, instructions?, prompts?})` | Run a registered agent as a subagent and return its answer; until it finishes the task waits. See [Subagents (rt.runAgent)](#subagents-rtrunagent). |
 | `rt.memo(key)` / `rt.memo(key, value)` | Read, or first-write, a durable value scoped to this task. See [Memos](#memos). |
 | `rt.waitFor(event, {timeout?})` | Return the payload of the next `event` sent to this task, or `undefined` once `timeout` passes; until then the task waits. See [Events, waits, and sleep](#events-waits-and-sleep). |
 | `rt.sleep(duration)` | Return once `duration` has passed; until then the task waits. See [Events, waits, and sleep](#events-waits-and-sleep). |
@@ -817,7 +841,9 @@ is not offered to sections, `beforeModelRequest`, or `afterTool` (the tool alrea
 `basePath` defaults to `/harness`; it must start with `/` and not end with `/`.
 `heartbeatInterval` (default `{seconds: 15}`, must be positive) paces SSE heartbeats.
 Conversation, task, and approval routes are `modelRouter`s with instance actions, so they
-appear in `/openapi.json` (tag `harness`). The two SSE routes are plain Express routes
+appear in `/openapi.json`. Each route and its mutations use that collection's tag
+(`harnessconversations`, `harnesstasks`, `harnessapprovals`), so a generated client
+invalidates the list it just changed. The two SSE routes are plain Express routes
 (the listed exception to modelRouter actions) and are not in the OpenAPI spec.
 
 ### Conversation routes
@@ -840,7 +866,7 @@ appear in `/openapi.json` (tag `harness`). The two SSE routes are plain Express
 
 | Method | Path | Permissions | Behavior |
 | --- | --- | --- | --- |
-| GET | `/harness/tasks/:id` | Owner (`userId`) or admin | One task. Others: 403. |
+| GET | `/harness/tasks/:id` | Owner (`userId`) or admin | One task, without `lease` (the fencing token stays on the server). Others: 403. |
 | POST | `/harness/tasks/:id/abort` | Owner or admin | Body `{reason}` (required, non-blank). Runs `harness.abort` with the caller as `userId`; returns the aborted task. |
 | POST | `/harness/tasks/:id/resolveInterrupted` | Admin | Body `{action: "retry" \| "abort" \| "complete", reason, result?}`. Runs `harness.resolveInterrupted` with the caller as `userId`; returns the task. |
 | GET | `/harness/tasks/:id/events` | Owner or admin | SSE for the task and its descendants. See [Event stream (SSE)](#event-stream-sse). |
@@ -1320,7 +1346,8 @@ summarize: {
 | --- | --- | --- | --- |
 | `input` | `unknown` | Yes | The subagent's user message. A string is sent as-is (blank is rejected); anything else as `JSON.stringify(input)`. |
 | `output` | zod schema | No | Structured output. Defaults to the agent's own `output`. |
-| `instructions` | `string` | No | Replaces the agent's instructions for this subagent conversation only. |
+| `instructions` | `string` or `PromptVersionRef` | No | Replaces the agent's instructions for this subagent conversation only. A registry prompt (`promptRegistry.get`) runs with its `body`, and its `{name, version, label}` is added to the trace's `prompts`. |
+| `prompts` | `{name, version, label?}[]` | No | More prompt versions this subagent used, added to the trace's `prompts`. Each version is recorded once per trace. An invalid ref, or an `instructions` prompt without a string `body`, fails the phase with a definition error. |
 
 Returns the final assistant text, or, with a schema, the object the schema parsed. The
 generic `rt.runAgent<T>(...)` types the result when the schema comes from the agent.
@@ -1331,6 +1358,7 @@ What one call does:
    (`ownership: {kind: "task", id: <caller>}`, `status: "busy"`, agent snapshot with
    `instructions` and `outputSchema`), its user message (`seq` 1), and the turn task
    (`ownership: {kind: "task", id: <caller>}`) with an `AGENT` span named after the agent.
+   Prompt versions from `instructions` and `prompts` are added to the trace's `prompts`.
 2. Waits with `rt.waitForTasks([turn])`: the caller commits `waiting` and the phase stops.
 3. When the turn settles the caller wakes and the phase re-runs from its checkpoint. The
    same call finds the same turn and conversation (step 1 writes nothing) and returns.

package/dist/docs/versioned/next/reference/ai.md

@@ -91,7 +91,7 @@ src/
 - **Plugins:** `AiApp`, `LangfuseApp`
 - **Service:** `AIService`, `TemperaturePresets`, `FileStorageService`, `MCPService`,
   `getMCPTools`
-- **Models:** `AIRequest`, `GptHistory`, `FileAttachment`, `Project`
+- **Models:** `AIRequest`, `GptHistory`, `FileAttachment`, `Project` (lazy; prefer `getProjectModel()`)
 - **Routes:** `addGptRoutes`, `addGptHistoryRoutes`, `addAiRequestsExplorerRoutes`, `addFileRoutes`, `addProjectRoutes`, `addMcpRoutes`
 - **Structured output:** `parseAiJson`, `normalizeLlmJsonTextForStructuredOutput`, re-exported `Output`, `jsonSchema`, `JSONValue`, `FlexibleSchema` from `ai`
 - **Langfuse:** `initLangfuseClient`, `getLangfuseClient`, `shutdownLangfuseClient`, `compilePrompt`, `createPrompt`, `getPrompt`, `createTelemetryConfig`, `preparePromptForAI`, `initTracing`, `shutdownTracing`, `LangfuseCache`, cache helpers
@@ -249,7 +249,8 @@ Metadata for files stored in GCS.
 
 ### Project
 
-GPT project with persistent context and memories.
+GPT project with persistent context and memories. Registered lazily: `getProjectModel()`
+(or any use of the deprecated `Project` export) registers it.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -440,6 +441,7 @@ new AiApp({
 | `maxSteps` | Max tool-calling steps (default 5) |
 | `titleModelId` | Cheaper model for conversation title generation |
 | `openApiOptions` | Passed to route OpenAPI builders |
+| `projects` | Default `true`. `false` skips the `/gpt/projects` routes, so `AiApp` never registers the `Project` model |
 
 ## LangfuseApp plugin
 
@@ -508,7 +510,7 @@ server `AIService` when configured, otherwise a request-scoped service built fro
 | `ObsPrompt` | Named prompt (`name` unique) with `folder` and `tags[]` |
 | `ObsPromptVersion` | Immutable `vN` body, `variables[]`, schemas, `sensitive` (default false), `config` |
 | `ObsPromptLabel` | Movable labels; unique `(promptId, label)` |
-| `ObsTrace` | Root trace: user, session, status, `errorSummary`, `sensitive`, `prompts[]`, usage |
+| `ObsTrace` | Root trace: user, session, status, `errorSummary`, `sensitive`, `prompts[]`, `scope`, `tags[]`, usage |
 | `ObsSpan` | Nested span with `kind`, `status`, optional `error`, offsets, usage |
 | `ObsScore` | Scores on a trace/span; many per trace, **no unique index** |
 | `ObsEvaluator` | Evaluator: `type` (`human` \| `llm-judge` \| `json-assert`), `target`, `dimensions[]`, `runModes`, `instructions`, `judgePromptName` (judge), `assertion` (json-assert), `confidenceAlertBelow` (default 0.7) |
@@ -560,7 +562,7 @@ When `prompts.primary` is `local`, `ObservabilityApp.register` mounts admin-only
 
 | Method | Path | Behavior |
 | --- | --- | --- |
-| GET | `/ai/observability/traces` | Admin list. Query `from`, `to`, `prompt`, `status`, `userId`, `sessionId`, `hasScore`, `sensitive`, `flaggedForDataset`, `page`, `limit`. Body is `{data, page, limit, more, total}` so pagination survives RTK `{data}` unwrap. Each row includes `spanCount` and `scoreCount`. `prompts.length` is the `N prompts` count |
+| GET | `/ai/observability/traces` | Admin list. Query `from`, `to`, `prompt`, `status`, `userId`, `sessionId`, `scope`, `hasScore`, `sensitive`, `flaggedForDataset`, `page`, `limit`. Body is `{data, page, limit, more, total}` so pagination survives RTK `{data}` unwrap. Each row includes `spanCount` and `scoreCount`. `prompts.length` is the `N prompts` count |
 | GET | `/ai/observability/traces/:id` | Span tree (kind, offsets, durations, I/O, cost) plus scores. `errorSummary` is the first span with `status: "error"` |
 | POST | `/ai/observability/traces/:id/scores` | Persist a score and fan out to every `ScoreSink` |
 | POST | `/ai/observability/traces/test-multi-stage` | Admin-only smoke workflow, registered only with the local trace sink. Uses `ObservabilityApp.aiService`, or `requestAiServiceFactory({apiKey})` when the server service is absent (`apiKey` comes from `x-ai-api-key`); answers **503** with the same missing-key title as playground when neither exists. Body `{input?: string}` (defaults to a built-in sample). Runs two `AIService.generateJsonObject` calls with `skipTrace: true` and named JSON output schemas (`obs-test-multi-stage-call-1` / `call-2`), a deterministic local `text-metrics` `TOOL` stage, then a final `generateJsonObject` synthesis against `obs-test-multi-stage-final`; exports exactly one parent trace with ordered child spans `LLM`, `LLM`, `TOOL`, `LLM` under a `CHAIN` root. LLM span input includes `outputSchema`. Returns `{traceId, output, stages[]}` where `output` is the final schema object (`sentence`, `phrase`, `keywords`, `metrics`). Child LLM failures export an error trace then rethrow |
@@ -638,6 +640,33 @@ Low-level exports (also used by `addGptRoutes` when `langfuseSystemPromptName` i
 
 Subpath imports for tree-shaking: `@terreno/ai/langfuseClient`, `@terreno/ai/langfuseApp`.
 
+## Subpath exports
+
+Import these instead of `dist/` paths. Deep `dist/` imports break when a bundler (such as
+Vercel's) inlines them and their bare `@terreno/api` imports no longer resolve. Each
+subpath shares module instances with `@terreno/ai/harness`.
+
+| Subpath | Exports |
+| --- | --- |
+| `@terreno/ai/harness` | Harness public API; see [AI harness reference](ai-harness.md) |
+| `@terreno/ai/harness/jobsRunner` | `JobsRunner` |
+| `@terreno/ai/harness/agentLoop` | `createAgentTasks` and the agent turn internals |
+| `@terreno/ai/harness/commit` | `createTaskRecords`, `HarnessModels`, and other commit helpers, for custom commits that write domain records inside a task's fenced commit |
+| `@terreno/ai/harness/events` | `insertMessages`, `resolveStreamingOptions` |
+| `@terreno/ai/harness/internalRuntime` | `internalRuntime` |
+| `@terreno/ai/admin` | `AIAdminApp` |
+| `@terreno/ai/observability/observabilityApp` | `ObservabilityApp` |
+| `@terreno/ai/observability/localPlugin` | `createLocalObservabilityPlugin`, `createLocalObservabilityBundle` |
+| `@terreno/ai/observability/promptStore` | `LocalPromptStore` |
+
+The internals subpaths follow the harness's own changes; they carry no compatibility
+promise beyond the release they ship in.
+
+The root `@terreno/ai` entry registers the `Project` model on first use
+(`getProjectModel()` or the `Project` export), not on import. `AiApp` uses it for
+`/gpt/projects` by default; an app that owns a model named `Project` passes
+`new AiApp({projects: false})` and does not call `addProjectRoutes`.
+
 ## FileStorageService
 
 Google Cloud Storage helper for uploads referenced by `addFileRoutes`.

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

@@ -725,8 +725,16 @@ Master-detail layout. Pass `listViewData` plus `renderListViewItem` for the list
 screens the detail replaces the list until the user goes back.
 
 `desktopChildrenMinWidth` opts into a minimum pixel width for each desktop child when there
-are one or two children. `childColumnRounding` sets the border radius on each detail child
-column container (defaults to `md`, 4px); the list column is excluded. `narrowViewportChildLabels`
+are one or two children. `childColumnRounding` sets the border radius on each desktop detail
+pane (defaults to `md`, 4px); the list column is excluded. The pane clips to that radius. The
+column inside it scrolls: content taller than the pane scrolls in the column, and a child with
+`height: "100%"` fills the visible pane so a scroll view inside that child scrolls on its own.
+On a narrow web viewport the pager page is height-bounded to that same visible pane. Its rounded
+corners still clip, and a `height: "100%"` child scrolls inside the page. On the labeled pager,
+previous and next sit in fixed left and right slots in a row under the column. A missing direction
+leaves that slot empty, so the other arrow stays put. The column height is the measured pane minus
+top spacing, the navigation row, bottom spacing, and `bottomNavBarHeight`.
+`narrowViewportChildLabels`
 opts into a labeled full-width pager on the narrow viewport. `narrowBelowWidth` uses that
 viewport when the window is at or below the given pixel width; when omitted, the narrow
 viewport follows `isNarrowViewport()`. These props are web only; the native `SplitPage`

package/package.json

@@ -11,8 +11,8 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "57.11.0",
-    "@terreno/blocks": "57.11.0",
+    "@terreno/api": "57.12.0",
+    "@terreno/blocks": "57.12.0",
     "express": "^5.2.1",
     "luxon": "^3.7.2",
     "minisearch": "^7.2.0",
@@ -105,5 +105,5 @@
     "test:coverage": "bun run ../scripts/check-coverage.ts"
   },
   "type": "module",
-  "version": "57.11.0"
+  "version": "57.12.0"
 }

package/src/docs/upgrades/57.12.0.md

@@ -0,0 +1,89 @@
+# Upgrading to 57.12.0
+
+**Action required:** Yes
+**Affected packages:** @terreno/ai
+
+## Summary
+
+Harness tasks can record a trace scope, tags, and prompt versions, and `@terreno/ai` publishes official subpath exports. The chat `Project` model registers on first use instead of at import, and harness task HTTP responses no longer include the lease fencing token.
+
+## Breaking changes
+
+### `Project` is no longer registered on import
+
+**What changed**
+
+Importing `@terreno/ai` does not register mongoose model `Project`. The exported `Project` is a lazy proxy. The first property access, `new Project(...)`, or `getProjectModel()` registers the model. Statics and `instanceof Project` still work. These do not:
+
+- `Project === mongoose.models.Project` (and `Project === mongoose.model("Project")`)
+- `Object.keys(Project)` (always empty)
+- reading `Project.prototype` (throws)
+
+`new AiApp()` still mounts `/gpt/projects` and registers the model when those routes load. `new AiApp({projects: false})` skips those routes.
+
+**Why**
+
+An app that imports `@terreno/ai` and owns its own model named `Project` was hitting a mongoose overwrite error at import time.
+
+**Migration**
+
+```typescript
+// Before
+import {Project} from "@terreno/ai";
+
+const project = await Project.findExactlyOne({_id: id});
+if (mongoose.models.Project === Project) {
+  // identity check
+}
+
+// After
+import {getProjectModel} from "@terreno/ai";
+
+const Project = getProjectModel();
+const project = await Project.findExactlyOne({_id: id});
+```
+
+To keep a separate app model named `Project`, do not call `getProjectModel()` or touch the `Project` export, and skip the AI project routes:
+
+```typescript
+new AiApp({aiService, projects: false});
+```
+
+### Harness task HTTP responses omit `lease`
+
+**What changed**
+
+`GET /harness/tasks/:id` no longer includes `lease`. The OpenAPI schema for that response omits it too. Collection list is disabled (`list: []`, 405). The token is still stored on the task document for runners.
+
+**Why**
+
+`lease.token` is the fencing token that decides which runner may commit. It is not a client field.
+
+**Migration**
+
+```typescript
+// Before
+const token = task.lease?.token;
+
+// After
+// Do not read lease from the HTTP task. Runners load it on the server.
+```
+
+Regenerate the OpenAPI SDK after upgrading `@terreno/ai` so generated task types drop `lease`.
+
+## Deprecations
+
+`Project` from `@terreno/ai` still works for `find`, `create`, `new`, and `instanceof`. It is deprecated. Call `getProjectModel()` and use that model. A later major can remove the proxy.
+
+## New capabilities
+
+- `harness.createTask(def, input, {trace: {scope, tags}, prompts})` writes a scope (tenant, workspace), tags, and prompt versions onto the task's `ObsTrace`. Child tasks and subagents share that trace. The admin trace list filters with `?scope=`.
+- `rt.runAgent` accepts `prompts` and a registry `PromptVersionRef` as `instructions`. It runs `body` and records the version on the trace.
+- Subpath exports: `@terreno/ai/admin`, `@terreno/ai/harness/agentLoop`, `@terreno/ai/harness/commit`, `@terreno/ai/harness/events`, `@terreno/ai/harness/internalRuntime`, `@terreno/ai/observability/observabilityApp`, `@terreno/ai/observability/localPlugin`, `@terreno/ai/observability/promptStore`.
+
+## Verification
+
+- Code that imported `Project` from `@terreno/ai`: switch identity checks and `mongoose.models.Project` reads to `getProjectModel()`.
+- An app that owns a model named `Project`: pass `projects: false` and do not call `getProjectModel()`.
+- Harness clients: confirm `GET /harness/tasks/:id` JSON has no `lease`, then regenerate the SDK.
+- `bun run compile` and `bun run lint` at the app root.

package/src/docs/versioned/next/explanation/ai-workflows.md

@@ -49,9 +49,10 @@ Maintains centralized agent guidance and generates the matching configuration fo
 
 Rulesync generates native hooks from `.rulesync/hooks.json`. Biome checks changed files
 after edits and staged files before commits. At agent stop,
-`.rulesync/hooks/quality-check.sh` runs lint, TypeScript compilation, Knip, and
-dependency-cruiser. It keeps stdout machine-readable for each host and prevents
-retry-triggered Stop hooks from rerunning the commands.
+`.rulesync/hooks/quality-check.sh` runs `bun install --frozen-lockfile` when
+`node_modules/typescript` or any workspace package link is missing, then runs lint,
+TypeScript compilation, Knip, and dependency-cruiser. It keeps stdout machine-readable
+for each host and prevents retry-triggered Stop hooks from rerunning the commands.
 
 Existing findings are ratcheted so the checks reject new debt without requiring unrelated
 cleanup. See [Static analysis](static-analysis.md).

package/src/docs/versioned/next/explanation/roadmap-process.md

@@ -402,7 +402,7 @@ do not claim completion until done.
 | Workflow | Trigger | Purpose |
 | -------- | ------- | ------- |
 | [`.github/workflows/triage.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown + `type:*` from Kind when present; `area:*` / `type:*` labels the issue was opened with win, so `roadmap:sync` issues are not asked for an area |
-| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when it changes |
+| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when roadmap content changes. A new **Last updated** timestamp alone does not open a pull request |
 | [`.github/workflows/roadmap-sync.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-sync.yml) | Taxonomy files change on `master` + manual | Apply labels and reconcile the board's fields and items |
 | [`.github/workflows/roadmap-reconcile.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, add an entry for every new IP, open its tracking issue, push to the board, regenerate `ROADMAP.md` |
 All three share the `roadmap` concurrency group. They write the same board, and interleaving
@@ -495,4 +495,6 @@ GITHUB_TOKEN=$(gh auth token) TERRENO_PROJECT_NUMBER=... bun run roadmap:generat
 ```
 
 The generator exits non-zero when the project cannot be read, so a bad project number or a
-token without `read:project` fails loudly instead of writing an empty `ROADMAP.md`.
+token without `read:project` fails loudly instead of writing an empty `ROADMAP.md`. When the
+rendered list matches the file already on disk, it keeps that file's **Last updated** stamp
+and does not write. The daily workflow then sees a clean diff and does not open a pull request.

package/src/docs/versioned/next/how-to/circleci.md

@@ -254,8 +254,12 @@ the review script so a PR cannot rewrite the reviewer.
 Netlify and GCP jobs **validate their context as the first step** and fail,
 before checkout or `bun install`, listing the missing variables. Preview jobs
 halt earlier on fork PRs, where CircleCI withholds contexts. Docker Layer
-Caching is off (200 credits per job). The docs Netlify target disables
-Docusaurus minification so the build stays within the 8 GB `large` executor.
+Caching is off (200 credits per job). The docs Netlify target builds only the
+current docs tree, disables Docusaurus minification, and pins SSG to one worker
+thread so the build peaks near 3 GB and fits the 4 GB `medium` executor.
+Released versions are not rebuilt: `archive-docs-version` (in `publish-release`,
+`X.Y.0` tags only) builds each one once and uploads it to its GitHub release, and
+`deploy-docs` unpacks those archives under `/<version>/`. See `website/README.md`.
 
 `terreno-gcp` uses CircleCI OIDC (`CIRCLE_OIDC_TOKEN_V2`), never a JSON service
 account key. Set `circleci_org_id`, `circleci_project_id`, and

package/src/docs/versioned/next/how-to/github-actions-ci.md

@@ -7,24 +7,23 @@ describes how they behaved if one is ever re-enabled.
 
 ## Docs site (`docs-deploy.yml`)
 
-`Build docs site` is often the longest PR job because Docusaurus compiles every
-versioned tree under `website/versioned_docs/` and TypeDoc regenerates API
-pages.
+`Build docs site` is often the longest PR job because TypeDoc regenerates API
+pages. The site builds only the current docs tree; `website/versioned_docs/` is
+markdown for the MCP server.
 
 PR builds set `DOCS_PREVIEW=true` and pass `--no-minify`. Both PR and
 `master` use Docusaurus Faster (Rspack/SWC via `@docusaurus/faster`).
 
 | Behavior | PR preview | `master` production |
 | --- | --- | --- |
-| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted (`disableVersioning`) | Built |
+| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted | Prebuilt archives unpacked under `/<version>/` |
 | JS minify | Off | On |
 | Local search index | Skipped | Built |
 | Generated API + component MDX | Restored from cache when `api`/`rtk`/`ui` hashes match | Same cache, then full generate on miss |
 | TypeDoc workspace `tsc` | Once per generate (api+rtk deps share a process) | Same |
 | Rspack cache (`node_modules/.cache/rspack`) | Restored per `pull_request` vs `push` | Separate production key |
 
-Production still builds every version. Do not rely on `/57.1.0/…` URLs in a
-PR deploy preview.
+Do not rely on `/57.1.0/…` URLs in a PR deploy preview.
 
 ## Other high-cost jobs
 

package/src/docs/versioned/next/reference/ai-harness.md

@@ -142,7 +142,7 @@ The `task` view passed to `run`: `{id, name, version, input, state, phase, attem
 | `Harness.open({registry, runner?, models?, env?, priceMap?, streaming?, testHooks?})` | Checks requirements, rejects a duplicate `name@version` or agent name, ensures collections and indexes exist. `runner` defaults to `new InProcessRunner()`. See [open options](#open-options). |
 | `start()` | Throws, claiming nothing, when any non-terminal task uses a `name@version` missing from the registry (see [Versioning](#versioning)). Then starts the runner. Throws when already started. The runner recovers expired tasks once it owns execution. |
 | `stop()` | Stops claiming work, waits (without a time limit) for every phase in flight while still renewing the owner lease, then releases it. No-op when not started. |
-| `createTask(definition, input, {requestId?, userId?})` | Inserts a `pending` task, its `ObsTrace`, and its root span in one transaction. Wakes the runner. The definition must be in the registry. |
+| `createTask(definition, input, {requestId?, userId?, trace?, prompts?})` | Inserts a `pending` task, its `ObsTrace`, and its root span in one transaction. Wakes the runner. The definition must be in the registry. See [Trace scope and prompt versions](#trace-scope-and-prompt-versions). |
 | `resolveInterrupted(id, {action, reason, result?, userId?})` | Resolve an `interrupted` task. See [resolveInterrupted](#resolveinterrupted). |
 | `abort(id, {reason, userId?})` | Abort a task and every non-terminal task it owns, bottom-up. See [abort](#abort). |
 | `decideApproval(approvalId, {approved, reason?, userId?})` | Approve or reject a pending approval without checking approvers. See [Approvals](#approvals). |
@@ -158,6 +158,30 @@ create with the same id returns the first task and leaves no extra trace. Reusin
 `requestId` for a different task name, or with a different `userId` (including none versus
 some), throws. A soft-deleted task still owns its `requestId`.
 
+### Trace scope and prompt versions
+
+A task's `ObsTrace` is its run record. `createTask` can label it:
+
+```typescript
+const prompt = await promptRegistry.get({label: "production", name: "intake-summary"});
+await harness.createTask(intakeSummary, {patientId}, {
+  prompts: prompt ? [prompt] : [],
+  trace: {scope: String(workspaceId), tags: ["nightly"]},
+  userId,
+});
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `trace.scope` | `string` | App-defined scope, such as a tenant or workspace id. Stored as `ObsTrace.scope`, indexed with `created` for per-scope metering (sum `LLM` span `usage.costUsd` by scope and month). Blank throws `harness-invalid-request`. |
+| `trace.tags` | `string[]` | App-defined labels, stored once each as `ObsTrace.tags`. A blank tag throws `harness-invalid-request`. |
+| `prompts` | `{name, version, label?}[]` | Prompt versions the task uses, stored once each on `ObsTrace.prompts`. A `PromptVersionRef` from `promptRegistry.get` fits as-is; its `body` is not stored. A ref without a name, with a non-string `label`, or without a positive integer `version` throws `harness-invalid-request`. |
+
+Child tasks and subagents write into the root task's trace, so they share its scope and
+tags. `rt.runAgent` adds its own prompt versions to the same trace (see
+[Subagents](#subagents-rtrunagent)). The admin trace list filters by `scope` and by
+prompt.
+
 ### open options
 
 | Option | Type | Description |
@@ -306,7 +330,7 @@ where `lease` is `{owner, duration, heartbeat}` (Luxon `Duration`s). With `maxPh
 | `rt.signal` | `AbortSignal`. Aborts when the task is aborted (at once in this process, within one heartbeat elsewhere), or when this run loses its lease. Pass it to cancellable calls. |
 | `rt.createTask(definition, input, {background?, key?})` | Create a child task. Returns its id. See [Child tasks and waitForTasks](#child-tasks-and-waitfortasks). |
 | `rt.waitForTasks(ids, {policy?})` | Return child outcomes once they settle; until then the task waits. See [Child tasks and waitForTasks](#child-tasks-and-waitfortasks). |
-| `rt.runAgent(agent, {input, output?, instructions?})` | Run a registered agent as a subagent and return its answer; until it finishes the task waits. See [Subagents (rt.runAgent)](#subagents-rtrunagent). |
+| `rt.runAgent(agent, {input, output?, instructions?, prompts?})` | Run a registered agent as a subagent and return its answer; until it finishes the task waits. See [Subagents (rt.runAgent)](#subagents-rtrunagent). |
 | `rt.memo(key)` / `rt.memo(key, value)` | Read, or first-write, a durable value scoped to this task. See [Memos](#memos). |
 | `rt.waitFor(event, {timeout?})` | Return the payload of the next `event` sent to this task, or `undefined` once `timeout` passes; until then the task waits. See [Events, waits, and sleep](#events-waits-and-sleep). |
 | `rt.sleep(duration)` | Return once `duration` has passed; until then the task waits. See [Events, waits, and sleep](#events-waits-and-sleep). |
@@ -817,7 +841,9 @@ is not offered to sections, `beforeModelRequest`, or `afterTool` (the tool alrea
 `basePath` defaults to `/harness`; it must start with `/` and not end with `/`.
 `heartbeatInterval` (default `{seconds: 15}`, must be positive) paces SSE heartbeats.
 Conversation, task, and approval routes are `modelRouter`s with instance actions, so they
-appear in `/openapi.json` (tag `harness`). The two SSE routes are plain Express routes
+appear in `/openapi.json`. Each route and its mutations use that collection's tag
+(`harnessconversations`, `harnesstasks`, `harnessapprovals`), so a generated client
+invalidates the list it just changed. The two SSE routes are plain Express routes
 (the listed exception to modelRouter actions) and are not in the OpenAPI spec.
 
 ### Conversation routes
@@ -840,7 +866,7 @@ appear in `/openapi.json` (tag `harness`). The two SSE routes are plain Express
 
 | Method | Path | Permissions | Behavior |
 | --- | --- | --- | --- |
-| GET | `/harness/tasks/:id` | Owner (`userId`) or admin | One task. Others: 403. |
+| GET | `/harness/tasks/:id` | Owner (`userId`) or admin | One task, without `lease` (the fencing token stays on the server). Others: 403. |
 | POST | `/harness/tasks/:id/abort` | Owner or admin | Body `{reason}` (required, non-blank). Runs `harness.abort` with the caller as `userId`; returns the aborted task. |
 | POST | `/harness/tasks/:id/resolveInterrupted` | Admin | Body `{action: "retry" \| "abort" \| "complete", reason, result?}`. Runs `harness.resolveInterrupted` with the caller as `userId`; returns the task. |
 | GET | `/harness/tasks/:id/events` | Owner or admin | SSE for the task and its descendants. See [Event stream (SSE)](#event-stream-sse). |
@@ -1320,7 +1346,8 @@ summarize: {
 | --- | --- | --- | --- |
 | `input` | `unknown` | Yes | The subagent's user message. A string is sent as-is (blank is rejected); anything else as `JSON.stringify(input)`. |
 | `output` | zod schema | No | Structured output. Defaults to the agent's own `output`. |
-| `instructions` | `string` | No | Replaces the agent's instructions for this subagent conversation only. |
+| `instructions` | `string` or `PromptVersionRef` | No | Replaces the agent's instructions for this subagent conversation only. A registry prompt (`promptRegistry.get`) runs with its `body`, and its `{name, version, label}` is added to the trace's `prompts`. |
+| `prompts` | `{name, version, label?}[]` | No | More prompt versions this subagent used, added to the trace's `prompts`. Each version is recorded once per trace. An invalid ref, or an `instructions` prompt without a string `body`, fails the phase with a definition error. |
 
 Returns the final assistant text, or, with a schema, the object the schema parsed. The
 generic `rt.runAgent<T>(...)` types the result when the schema comes from the agent.
@@ -1331,6 +1358,7 @@ What one call does:
    (`ownership: {kind: "task", id: <caller>}`, `status: "busy"`, agent snapshot with
    `instructions` and `outputSchema`), its user message (`seq` 1), and the turn task
    (`ownership: {kind: "task", id: <caller>}`) with an `AGENT` span named after the agent.
+   Prompt versions from `instructions` and `prompts` are added to the trace's `prompts`.
 2. Waits with `rt.waitForTasks([turn])`: the caller commits `waiting` and the phase stops.
 3. When the turn settles the caller wakes and the phase re-runs from its checkpoint. The
    same call finds the same turn and conversation (step 1 writes nothing) and returns.

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

@@ -91,7 +91,7 @@ src/
 - **Plugins:** `AiApp`, `LangfuseApp`
 - **Service:** `AIService`, `TemperaturePresets`, `FileStorageService`, `MCPService`,
   `getMCPTools`
-- **Models:** `AIRequest`, `GptHistory`, `FileAttachment`, `Project`
+- **Models:** `AIRequest`, `GptHistory`, `FileAttachment`, `Project` (lazy; prefer `getProjectModel()`)
 - **Routes:** `addGptRoutes`, `addGptHistoryRoutes`, `addAiRequestsExplorerRoutes`, `addFileRoutes`, `addProjectRoutes`, `addMcpRoutes`
 - **Structured output:** `parseAiJson`, `normalizeLlmJsonTextForStructuredOutput`, re-exported `Output`, `jsonSchema`, `JSONValue`, `FlexibleSchema` from `ai`
 - **Langfuse:** `initLangfuseClient`, `getLangfuseClient`, `shutdownLangfuseClient`, `compilePrompt`, `createPrompt`, `getPrompt`, `createTelemetryConfig`, `preparePromptForAI`, `initTracing`, `shutdownTracing`, `LangfuseCache`, cache helpers
@@ -249,7 +249,8 @@ Metadata for files stored in GCS.
 
 ### Project
 
-GPT project with persistent context and memories.
+GPT project with persistent context and memories. Registered lazily: `getProjectModel()`
+(or any use of the deprecated `Project` export) registers it.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -440,6 +441,7 @@ new AiApp({
 | `maxSteps` | Max tool-calling steps (default 5) |
 | `titleModelId` | Cheaper model for conversation title generation |
 | `openApiOptions` | Passed to route OpenAPI builders |
+| `projects` | Default `true`. `false` skips the `/gpt/projects` routes, so `AiApp` never registers the `Project` model |
 
 ## LangfuseApp plugin
 
@@ -508,7 +510,7 @@ server `AIService` when configured, otherwise a request-scoped service built fro
 | `ObsPrompt` | Named prompt (`name` unique) with `folder` and `tags[]` |
 | `ObsPromptVersion` | Immutable `vN` body, `variables[]`, schemas, `sensitive` (default false), `config` |
 | `ObsPromptLabel` | Movable labels; unique `(promptId, label)` |
-| `ObsTrace` | Root trace: user, session, status, `errorSummary`, `sensitive`, `prompts[]`, usage |
+| `ObsTrace` | Root trace: user, session, status, `errorSummary`, `sensitive`, `prompts[]`, `scope`, `tags[]`, usage |
 | `ObsSpan` | Nested span with `kind`, `status`, optional `error`, offsets, usage |
 | `ObsScore` | Scores on a trace/span; many per trace, **no unique index** |
 | `ObsEvaluator` | Evaluator: `type` (`human` \| `llm-judge` \| `json-assert`), `target`, `dimensions[]`, `runModes`, `instructions`, `judgePromptName` (judge), `assertion` (json-assert), `confidenceAlertBelow` (default 0.7) |
@@ -560,7 +562,7 @@ When `prompts.primary` is `local`, `ObservabilityApp.register` mounts admin-only
 
 | Method | Path | Behavior |
 | --- | --- | --- |
-| GET | `/ai/observability/traces` | Admin list. Query `from`, `to`, `prompt`, `status`, `userId`, `sessionId`, `hasScore`, `sensitive`, `flaggedForDataset`, `page`, `limit`. Body is `{data, page, limit, more, total}` so pagination survives RTK `{data}` unwrap. Each row includes `spanCount` and `scoreCount`. `prompts.length` is the `N prompts` count |
+| GET | `/ai/observability/traces` | Admin list. Query `from`, `to`, `prompt`, `status`, `userId`, `sessionId`, `scope`, `hasScore`, `sensitive`, `flaggedForDataset`, `page`, `limit`. Body is `{data, page, limit, more, total}` so pagination survives RTK `{data}` unwrap. Each row includes `spanCount` and `scoreCount`. `prompts.length` is the `N prompts` count |
 | GET | `/ai/observability/traces/:id` | Span tree (kind, offsets, durations, I/O, cost) plus scores. `errorSummary` is the first span with `status: "error"` |
 | POST | `/ai/observability/traces/:id/scores` | Persist a score and fan out to every `ScoreSink` |
 | POST | `/ai/observability/traces/test-multi-stage` | Admin-only smoke workflow, registered only with the local trace sink. Uses `ObservabilityApp.aiService`, or `requestAiServiceFactory({apiKey})` when the server service is absent (`apiKey` comes from `x-ai-api-key`); answers **503** with the same missing-key title as playground when neither exists. Body `{input?: string}` (defaults to a built-in sample). Runs two `AIService.generateJsonObject` calls with `skipTrace: true` and named JSON output schemas (`obs-test-multi-stage-call-1` / `call-2`), a deterministic local `text-metrics` `TOOL` stage, then a final `generateJsonObject` synthesis against `obs-test-multi-stage-final`; exports exactly one parent trace with ordered child spans `LLM`, `LLM`, `TOOL`, `LLM` under a `CHAIN` root. LLM span input includes `outputSchema`. Returns `{traceId, output, stages[]}` where `output` is the final schema object (`sentence`, `phrase`, `keywords`, `metrics`). Child LLM failures export an error trace then rethrow |
@@ -638,6 +640,33 @@ Low-level exports (also used by `addGptRoutes` when `langfuseSystemPromptName` i
 
 Subpath imports for tree-shaking: `@terreno/ai/langfuseClient`, `@terreno/ai/langfuseApp`.
 
+## Subpath exports
+
+Import these instead of `dist/` paths. Deep `dist/` imports break when a bundler (such as
+Vercel's) inlines them and their bare `@terreno/api` imports no longer resolve. Each
+subpath shares module instances with `@terreno/ai/harness`.
+
+| Subpath | Exports |
+| --- | --- |
+| `@terreno/ai/harness` | Harness public API; see [AI harness reference](ai-harness.md) |
+| `@terreno/ai/harness/jobsRunner` | `JobsRunner` |
+| `@terreno/ai/harness/agentLoop` | `createAgentTasks` and the agent turn internals |
+| `@terreno/ai/harness/commit` | `createTaskRecords`, `HarnessModels`, and other commit helpers, for custom commits that write domain records inside a task's fenced commit |
+| `@terreno/ai/harness/events` | `insertMessages`, `resolveStreamingOptions` |
+| `@terreno/ai/harness/internalRuntime` | `internalRuntime` |
+| `@terreno/ai/admin` | `AIAdminApp` |
+| `@terreno/ai/observability/observabilityApp` | `ObservabilityApp` |
+| `@terreno/ai/observability/localPlugin` | `createLocalObservabilityPlugin`, `createLocalObservabilityBundle` |
+| `@terreno/ai/observability/promptStore` | `LocalPromptStore` |
+
+The internals subpaths follow the harness's own changes; they carry no compatibility
+promise beyond the release they ship in.
+
+The root `@terreno/ai` entry registers the `Project` model on first use
+(`getProjectModel()` or the `Project` export), not on import. `AiApp` uses it for
+`/gpt/projects` by default; an app that owns a model named `Project` passes
+`new AiApp({projects: false})` and does not call `addProjectRoutes`.
+
 ## FileStorageService
 
 Google Cloud Storage helper for uploads referenced by `addFileRoutes`.

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

@@ -725,8 +725,16 @@ Master-detail layout. Pass `listViewData` plus `renderListViewItem` for the list
 screens the detail replaces the list until the user goes back.
 
 `desktopChildrenMinWidth` opts into a minimum pixel width for each desktop child when there
-are one or two children. `childColumnRounding` sets the border radius on each detail child
-column container (defaults to `md`, 4px); the list column is excluded. `narrowViewportChildLabels`
+are one or two children. `childColumnRounding` sets the border radius on each desktop detail
+pane (defaults to `md`, 4px); the list column is excluded. The pane clips to that radius. The
+column inside it scrolls: content taller than the pane scrolls in the column, and a child with
+`height: "100%"` fills the visible pane so a scroll view inside that child scrolls on its own.
+On a narrow web viewport the pager page is height-bounded to that same visible pane. Its rounded
+corners still clip, and a `height: "100%"` child scrolls inside the page. On the labeled pager,
+previous and next sit in fixed left and right slots in a row under the column. A missing direction
+leaves that slot empty, so the other arrow stays put. The column height is the measured pane minus
+top spacing, the navigation row, bottom spacing, and `bottomNavBarHeight`.
+`narrowViewportChildLabels`
 opts into a labeled full-width pager on the narrow viewport. `narrowBelowWidth` uses that
 viewport when the window is at or below the given pixel width; when omitted, the narrow
 viewport follows `isNarrowViewport()`. These props are web only; the native `SplitPage`