@terreno/mcp 58.0.0 → 58.0.2

package/dist/docs/versioned/58.0.0/how-to/ai-feature-development.md

@@ -0,0 +1,162 @@
+# Develop an AI feature
+
+Work this loop in **Terreno admin**. Observability primaries are always `local`.
+
+Architecture: [AI observability](../explanation/ai-observability.md). Routes and models: [AI reference](../reference/ai.md). Register plugins: [Observe LLM calls](./observe-llm-calls.md).
+
+Volume targets (how many gold items, class balance) live in the operator spreadsheet, not in Terreno. Use **tags** and **outcome class** so you can filter for balance.
+
+For a walkable example, run `bun run backend:seed`: it installs
+`examples/example-summarize` with production on v1 and candidate v2, the human
+`correctness-human` and automatic `schema-assert` evaluators, and the proofread
+`example-gold` dataset. It also installs `chat-safety-synthetic`, twelve proofread
+synthetic chats between two people. Each item is the new message plus a few earlier
+turns. Gold labels cover 988 (immediate danger to self), care-team follow-up,
+toxicity, a privacy leak, and a dismissive reply. Compare `chat-safety-screen` v1
+(new message only) with v2 (earlier turns) using evaluator `chat-safety-agreement`.
+These fixtures are proofread on purpose so experiments include them. The Generate
+button still lands drafts as `proofread: false` until a human accepts them. Load the
+same set into a running database, including a PR preview, with Admin → Scripts →
+`seedChatSafetyDataset` (wet run).
+
+## 1. Gather a gold dataset
+
+1. Open **Datasets** → create a named set. Optionally set `inputSchemaPromptName` to a registry prompt whose `inputSchema` should validate imported rows, and `expectedOutputSchema` if product has agreed a label shape.
+2. Add items in three ways:
+   - **From production traces** (preferred for open-ended features): Traces list → filter → **Add to dataset** (`POST /ai/observability/traces/add-to-dataset`). Sensitive traces always land `proofread: false`.
+   - **Import JSON or CSV** (`POST /ai/observability/datasets/:id/import`): JSON can be an array of bare input objects or structured rows with `input`, `expectedOutput`, `proofread`, `tags`, `outcomeClass`, and `metadata`. CSV accepts `Content-Type: text/csv` or `{format: "csv", content: "..."}`; plain columns map to `input`, `input.foo` nests fields, `expectedOutput.foo` maps labels, and reserved `proofread` / `tags` / `outcomeClass` columns map metadata. Invalid rows against the bound input schema return 400 with the row number and JSON path.
+   - **Manual**: `POST /datasets/:id/items` with a production-shaped `input`.
+   - **Synthetic** (phase 2.4): **Generate** drafts. They land as `origin: synthetic` and `proofread: false`. Do not run experiments on them until a human proofreads and sets `proofread: true`.
+3. Prefer a mix of true/false positives and negatives on classification features. Tag critical cases.
+
+In-app **thumbs** / **false positive|negative** on a live feature write feedback scores and can **flag for dataset** (step 7). Those traces show up with `flaggedForDataset`.
+
+## 2. Label expected output
+
+1. Open the dataset item.
+2. Fill `expectedOutput` to match the schema from step 1.
+3. Set `outcomeClass` (`tp` / `fp` / `tn` / `fn`) when the feature is a flag.
+4. Add `tags` for categories you will filter on later.
+5. Set `proofread: true` on synthetic items you accept.
+
+Skip unlabeled items in experiments unless you only need generation smoke (still prefer labels before scoring).
+
+## 3. Create the prompt
+
+1. Open **Admin → AI Observability → Prompts**. The folder filter shows counts; search filters name and folder. If your role lacks `aiPrompt:create`, the header **New prompt** is hidden (API writes still 403).
+2. **New prompt** (folder, name, system, user template with `{{variables}}`). That write is immutable **v1**. Open the row to the prompt hub (**Versions**, **Traces**, **Experiments**).
+3. **Versions** shows the description, folder, tags, and the editor together. Edit system/template/variables/temperature when `aiPrompt:update` is allowed, then **Save as vN+1**. There is no in-place save. System and template fields explain what each one is for. **Playground → Run once** (when `aiPrompt:playground` is allowed) compiles and calls the model; it does **not** create a version. **Traces** and **Experiments** show recent items for this prompt from prompt detail relationships.
+4. Do not paste that string into app routes. Apps call `AIService` with `promptName` + `promptLabel` (step 6).
+
+Read-only auditors with `aiPrompt:list` and `read` can review overview metadata and relationship tabs but do not see create, save, promote, or playground controls. Operators with the full `aiPrompt` action set see those controls. UI gating follows `permissions` on `GET /ai/observability/status`; assign roles in **Admin → Roles** per [API reference — AI observability RBAC](../reference/api.md#ai-observability-rbac).
+
+Judge prompts for evaluators are named constants or registry prompts — never inline in `AIService`.
+
+## 4. Set up evaluators
+
+**Evaluators** → **Create from template** (`POST /ai/observability/evaluators/templates/:name`) or custom (`POST /ai/observability/evaluators`):
+
+| Feature shape | Template | Score |
+| --- | --- | --- |
+| Boolean flags (urgent, etc.) | `correctness` (`llm-judge`) or `correctness-human` (review queue) | boolean `correct` |
+| Open-ended text | `hallucination` / `hallucination-human` | boolean `hallucinated` / `contains_hallucination` |
+| Open-ended text | `helpfulness` / `helpfulness-human` | numeric 0–1 |
+| Open-ended text | `toxicity` / `toxicity-human` | boolean `is_toxic` / `toxic` |
+| Structured JSON output | `schema-assert` (`json-assert`) | boolean `schema_valid` |
+| Open-ended text (if useful) | `conciseness` | numeric 0–1 (human) |
+
+`llm-judge` templates require a registry judge prompt (`eval-judge-*`) whose `outputSchema` declares every required dimension. Create returns 400 naming any missing key. `confidenceAlertBelow` defaults to **0.7**.
+
+A human evaluator with `runModes.liveSampleRate > 0` is rejected (400). Live sampling for judges is task 2.2, capped by `AI_OBS_SAMPLE_RATE`.
+
+Add more dimensions with product/engineering. Attach them to the experiment in step 5.
+
+## 5. Run experiments
+
+1. **Experiments** → `POST /ai/observability/experiments` with dataset id, **2–3 prompt version numbers**, evaluator ids, optional `modelOverride`, and optional `thresholds[]`.
+2. Thresholds default to the SOP gates (override per run if product disagrees):
+
+| Dimension | Gate |
+| --- | --- |
+| correctness true-rate | = 100% |
+| hallucination true-rate | = 0% |
+| helpfulness mean | ≥ 90% |
+| toxicity true-rate | = 0% |
+
+3. Wait for the run (`BackgroundTask` when local — even for a one-item dataset).
+4. `GET /ai/observability/experiments/:id` returns gate pass/fail, aggregates (`trueRate` for booleans, `mean` for numerics), `outlierItemIds`, `lowConfidenceItemIds`, and per-item outputs (**failed rows first**).
+5. Skim **per-item outputs**. If they are nonsense, fix the prompt before trusting aggregates.
+6. Read **pass/fail vs thresholds**. Open outliers and low-confidence items (default alert below 0.7). Use those items to rewrite the prompt.
+7. Save a new prompt version. Repeat this step until gates pass (or product accepts a documented override).
+8. `POST /ai/observability/experiments/:id/promote` with `{version}` moves `production` when all gates pass; **409** while any gate fails. Experiments never auto-promote without this call.
+
+Unproofread synthetic items are excluded unless you set `includeUnproofread`.
+
+## 6. Deploy to production
+
+1. In the prompt editor, select the winning version and **Set vN as production…**. The confirm modal names the **outgoing** production version (or none). Experiments never auto-promote.
+2. In the app, resolve that label at call time:
+
+```typescript
+await aiService.generateText({
+  prompt: text,
+  promptLabel: "production",
+  promptName: "example-summarize",
+  userId: req.user?.id,
+});
+```
+
+Missing `production` fails the request (400). Do not fall back to a hardcoded string.
+
+3. Bound cost before users reach the AI routes. `@terreno/ai` has no per-user token or spend
+   limit, and a chat reply keeps running after the client disconnects. Enable `TerrenoApp`
+   `rateLimit` and set a provider budget or quota alert; see
+   [Cost and abuse limits](../reference/ai.md#cost-and-abuse-limits).
+
+## 7. Production tracing and feedback
+
+Do this in parallel with steps 1–6 once the feature is reachable.
+
+1. Register `ObservabilityApp`. Every `generate*` emits a trace unless `skipTrace`.
+2. Pass `userId` and `sessionId` from the request.
+3. From the product UI, call `POST /ai/observability/traces/:id/feedback` as the signed-in user:
+   - `kind: "thumbs"` + `up` / `down` (helpfulness of suggestions)
+   - `kind: "outcome"` + `tp` / `fp` / `tn` / `fn` (flags)
+   - `flagDataset: true` to queue the trace as a dataset candidate
+4. In **Admin → AI Observability → Traces**, filter by time, prompt dropdown, status, user, session, score presence, or data sensitivity. Score and sensitivity dropdowns include both positive and negative states. Rows show a status dot, `sensitive` badge, error line, `N prompts`, tokens, cost, and latency. Open a row for the span tree (kind, indent, duration bar). Sensitive I/O disclosures start **collapsed**.
+5. Select one or more traces. The bulk bar warns when any selected row is `sensitive`. Choose **Send to human review**, read the queue explanation, and pick a human evaluator. The evaluator's dimensions become the score fields and its instructions guide the reviewer. Confirming posts `POST /ai/observability/traces/review` with `reason: "manual"`. Automatic (`llm-judge` / `json-assert`) evaluators cannot enter this queue.
+6. Open **Review queue**. Tabs show Pending / In progress / Done / Skipped counts, and pending
+   items are oldest-first. Select the header **Review oldest pending**.
+7. On each item, compare **What the AI was given** with **What the AI wrote**. Long fields begin
+   collapsed with a word count; structured outputs retain field labels and reviewer notes. Use
+   **Raw JSON** only when the field view is insufficient.
+8. Score every required evaluator dimension on the same screen. The segmented **Yes** / **No**
+   control, the numeric slider, and categorical pills sit in a fixed column on the left of each
+   question. On web, `Y` / `N` answer the highlighted question as soon as the item opens, `Enter`
+   submits, and `S` skips. Add an optional note, then **Submit and open next**. **Skip** records
+   no score. For the second phase-1 intake path, use **Assign to me** to manually claim an item
+   and move it to In progress. Continue until the toast says **Queue clear**.
+
+Feedback is a score (`source: "user-feedback"`) fanned out to every ScoreSink. Non-owners who are not admin get 403.
+
+## 8. Add weak production traces back to the dataset
+
+1. **Traces**: filter `thumbs=down`, `flaggedForDataset`, `failedEval`, or `lowConfidence` (filters land with task 2.6 feedback).
+2. **Add to dataset** (`POST /ai/observability/traces/add-to-dataset`, bulk allowed).
+3. Label the new items (step 2).
+4. Repeat steps 5–8.
+
+Phase 1 also supports **Send to review queue** from the Traces bulk bar (step 7) when human scoring is enough before dataset intake.
+
+## Checklist (one feature)
+
+- [ ] Gold set exists with mixed origins and labels
+- [ ] Prompt versions in the registry, not inlined in routes
+- [ ] SOP (or custom) evaluators attached
+- [ ] Experiment gates green or explicitly overridden
+- [ ] `production` label on the winning version
+- [ ] App calls `promptName` + `promptLabel`
+- [ ] Live traces include user/session
+- [ ] Product can send thumbs / outcome / flag-for-dataset
+- [ ] Human review queue reaches Queue clear
+- [ ] Weak traces can be added back to the dataset

package/dist/docs/versioned/58.0.0/how-to/audit-log.md

@@ -0,0 +1,104 @@
+# Enable the framework audit log
+
+Register `AuditApp` and set `audit: true` on routers you want logged. Successful HTTP mutations write append-only `AuditEvent` rows. Default retention is forever.
+
+## Steps
+
+### 1. Register the plugin
+
+```typescript
+import {AuditApp, TerrenoApp} from "@terreno/api";
+
+new TerrenoApp({userModel: User}).register(new AuditApp()).start();
+```
+
+Importing `@terreno/api` does not register `AuditEvent`. HTTP list/read is admin-only at `GET /audit-events` and `GET /admin/audit-events`. Create/update/delete over HTTP are disabled (405), including the admin remount.
+
+### 2. Opt in per router
+
+```typescript
+modelRouter("/todos", Todo, {
+  audit: true, // or {redact: ["ssn"]}
+  permissions: {
+    /* ... */
+  },
+});
+```
+
+`audit: true` without `AuditApp` still returns 2xx and logs an error once per process.
+
+## Operations
+
+| HTTP | `verb` | `operation` | Diff |
+| --- | --- | --- | --- |
+| POST `/` | `created` | `create` | `after` only |
+| PATCH `/:id` | `updated` | `update` | Changed fields in `before` / `after` |
+| DELETE `/:id` | `deleted` | `delete` | `before` only |
+| POST `/:id/:field` | `updated` | `arrayPush` | Changed fields; `recordId` set |
+| PATCH `/:id/:field/:itemId` | `updated` | `arrayUpdate` | Changed fields; `recordId` set |
+| DELETE `/:id/:field/:itemId` | `updated` | `arrayRemove` | Changed fields; `recordId` set |
+
+`source` is `modelRouter` for these writes. `ConsentApp` also writes `modelRouter` events for
+provisional consent actions: `created`/`create` for a provisional signature, `updated`/`update` for a void, and
+`viewed`/`read` when staff read another user's consent statuses. `read` and `viewed` mark
+audited reads; no other surface writes them. Secrets (`password`, `hash`, `salt`, `token`,
+`secret`, `refreshToken`) are omitted at every object and array depth, including compound
+keys such as `tokenHash`. Extra `redact` names merge with that list as exact field names.
+
+### 3. Admin mutations
+
+When `AuditApp` is registered, AdminApp writes the same `AuditEvent` collection with
+`source: "admin"` after successful admin POST/PATCH/DELETE. You do not need `onAdminAudit` for
+that. `onAdminAudit` remains an extra sink if the app still wants a second destination.
+Admin diffs also omit each model's `hiddenFields` and `excludeFields`.
+
+RBAC mutations fan into the same collection when `createAccess({auditSink: persistRbacAuditToAuditEvent})` is set. `source` is `rbac`.
+
+### 4. Account security actions
+
+`AccountSecurityApp` writes the same collection for account recovery. It refuses to start
+unless `AuditApp` is registered (or you pass `audit: false`).
+
+| `source` | Written by | `modelName` / `recordId` | `after` |
+| --- | --- | --- | --- |
+| `admin` | AdminApp POST/PATCH/DELETE | Model / document id | Changed fields |
+| `modelRouter` | `modelRouter` with `audit` | Model / document id | Changed fields |
+| `rbac` | `createAccess({auditSink: persistRbacAuditToAuditEvent})` | RBAC target | Role change |
+| `security` | `AccountSecurityApp` recovery actions (2FA reset and later actions) | `User` / target user id | `{securityAction, organizationId?}` |
+
+A recovery call that changes nothing (resetting 2FA that is already off) writes no row. List
+one user's security history with `GET /audit-events?source=security&recordId=<userId>`. Routes
+and action names: [Account security reference](../reference/account-security.md).
+
+`organizationId` is copied onto the event when `req.organization` is set (`id` or `_id`), otherwise from the request org AsyncLocalStorage, then `X-Organization-Id`, then the mutated document's `organizationId` string. Socket admin-window mutates attach `organizationId` on the payload so non-tenant models still land in the selected organization's audit log. The field is omitted when none of those exist. Admin list/read for `AuditEvent` is not organization-scoped, so unscoped rows stay visible when no organization is selected.
+
+`actorId` comes from `req.user.id` (or `_id`). Only a 24-hex Mongo ObjectId is stored;
+mongoose's looser `isValidObjectId` (12-character strings) is not used. Any other id
+shape still writes the event with `actorId` omitted and a warning logged.
+
+Update and delete snapshot `before` only when `audit` is on. If that `toJSON` throws, the
+mutation still completes and the event is recorded without a `before` snapshot.
+
+### 5. Fire-and-forget persist
+
+HTTP handlers do not await Mongo. Diffs still run before the response so `before` / `after` are captured. Failures log; the mutation stays 2xx.
+
+To persist completely off the API process, set Cloud Tasks env (`GCP_PROJECT`, `GCP_LOCATION`, `GCP_TASKS_AUDIT_QUEUE`, `AUDIT_TASKS_URL`, `AUDIT_TASKS_SECRET`) and `bun add @google-cloud/tasks`. `AuditApp` then enqueues the write and handles `POST /internal/audit-events` with header `X-Terreno-Audit-Secret`. Or pass `enqueue` yourself:
+
+```typescript
+new AuditApp({
+  enqueue: async (write) => {
+    await myQueue.push(write);
+  },
+  processQueuePath: "/internal/audit-events",
+  processQueueSecret: process.env.AUDIT_TASKS_SECRET,
+});
+```
+
+Authenticated malformed queue payloads are acknowledged without persistence. They cannot
+become valid on retry, and returning a non-2xx response would make Cloud Tasks retry the
+same poison task indefinitely.
+
+### 6. Retention
+
+Omit `retentionDays` or set `0` to keep events forever (no TTL index). `new AuditApp({retentionDays: 90})` creates a Mongo TTL index on `created` with `expireAfterSeconds = 90 * 86400`, replacing the default `{created: 1}` field index so Mongo does not reject a duplicate key pattern. Mongo expires documents in the background; lowering or removing TTL later requires dropping that index yourself (`db.auditevents.dropIndex(...)`) — Mongoose will not remove it.

package/dist/docs/versioned/58.0.0/how-to/automate-terreno-upgrades.md

@@ -0,0 +1,169 @@
+# How to automate Terreno upgrades with a scheduled agent
+
+Run a GitHub Actions job every working hour that checks whether your app is behind the latest Terreno release. When it is, and no upgrade is already in progress, the job starts one cloud agent. The agent runs the [`upgrading-terreno`](upgrade-terreno.md) skill and opens a pull request. The job never edits the tree and cannot merge. A person reviews the pull request.
+
+```text
+cron tick ──► in working hours? ──► behind the latest GitHub release?
+                                         │
+                                         ▼
+          release ≥ 7 days old? ──► no open upgrade PR? ──► no upgrade agent running or in cooldown?
+                                         │
+                                         ▼
+                 npm integrity for every installed package ──► launch one agent ──► agent opens PR
+```
+
+This page is an example. Copy the workflow and adapt the script to your repository. The Terreno repository does not run it.
+
+## Why the job only decides
+
+A GitHub runner usually has no MongoDB, no running backend, and no browser. The upgrade skill needs all three: it starts the upgraded backend, regenerates the typed client from `/openapi.json`, and runs the app. So the job decides and enqueues. The agent runs in a cloud environment that already has your app's services, such as a Cursor Cloud Agent environment.
+
+## Example workflow
+
+`.github/workflows/upgrade-terreno.yml`:
+
+```yaml
+name: Upgrade Terreno
+
+on:
+  schedule:
+    # 13:00–22:00 UTC covers 9:00am–5:59pm America/New_York in both EST and EDT.
+    # The script drops ticks outside the local window.
+    - cron: "0 13-22 * * 1-5"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Target @terreno/* version (empty = latest GitHub release)"
+        required: false
+        type: string
+      dry_run:
+        description: "Decide only — do not launch an upgrade agent"
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+  pull-requests: read
+
+# A second tick waits instead of racing the pull-request and active-agent checks.
+concurrency:
+  group: upgrade-terreno
+  cancel-in-progress: false
+
+jobs:
+  upgrade-terreno:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.4.4"
+
+      - run: bun install --frozen-lockfile
+
+      - name: Launch Terreno upgrade when one is not already open
+        env:
+          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TERRENO_UPGRADE_CLOUD_ENVIRONMENT: ${{ vars.TERRENO_UPGRADE_CLOUD_ENVIRONMENT }}
+          TERRENO_UPGRADE_DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || 'false' }}
+          TERRENO_UPGRADE_VERSION: ${{ inputs.version }}
+        run: bun .github/scripts/upgrade-terreno.ts
+```
+
+The job needs read access to contents and pull requests only. The agent pushes with its own credentials.
+
+## What the script decides
+
+`.github/scripts/upgrade-terreno.ts` checks these in order and stops at the first one that says no. Order matters: the cheap checks run first, and no agent API call happens until every gate passes.
+
+| Order | Check | Skip when |
+| --- | --- | --- |
+| 1 | Working hours | A scheduled tick lands outside weekdays 9:00am–5:59pm in your team's timezone. Use Luxon with a named zone so daylight saving does not move the window. Manual runs are not gated. |
+| 2 | Installed versions | No `@terreno/*` pin is found. This is an error, not a skip. Read every manifest that pins Terreno. With a Bun catalog, the versions live in the root `package.json` under `workspaces.catalog` (and `workspaces.catalogs.<name>`); workspace packages say `catalog:`. |
+| 3 | Target version | The lowest installed pin already equals the target, or any pin is newer than it. Never downgrade. Resolving the target fails the job when `@terreno/api` at that version is not on npm yet; see below. |
+| 4 | Release age | A scheduled run targets a release under 7 days old. A manual run is the human gate and is not held. |
+| 5 | Open pull request | Any open pull request is an upgrade: its title names a Terreno upgrade, its branch contains `upgrade-terreno`, or its body has the `<!-- terreno-upgrade -->` marker. |
+| 6 | Running agent | An upgrade agent (name starts with `Upgrade Terreno`) is still running. |
+| 7 | Cooldown | An agent for the same target version was created in the last 24 hours, even one that finished or failed. Without this, a broken upgrade is retried every hour. |
+| 8 | npm integrity | Any installed package has no published `dist.integrity` for the target. |
+
+Take the target from the latest stable [TerrenoLabs/terreno GitHub release](https://github.com/TerrenoLabs/terreno/releases), not the npm `latest` dist-tag. Reject drafts, prereleases, and tags that are not semver. Validate a manual `version` input as semver before using it.
+
+Write the decision to `$GITHUB_STEP_SUMMARY` so each run says why it skipped:
+
+```text
+## Terreno upgrade
+
+- Decision: skipped (open-pull-request)
+- Detail: Open Terreno upgrade pull request #261 (Upgrade Terreno to 57.19.2).
+- From: 57.16.2
+- To: 57.19.2
+```
+
+The job fails, rather than skips, in two cases:
+
+- A launch would happen and `CURSOR_API_KEY` is missing. A skip with no key is still green.
+- The latest GitHub release exists but `@terreno/api` at that version is not on npm. This check runs while the target is resolved, before the release-age and open-pull-request gates, so every in-hours run is red until publishing finishes. That points at a stuck release. If you would rather skip quietly, return a skip from that check instead of throwing.
+
+## The agent prompt
+
+The skill stops for confirmation unless the invoking task names both versions and authorizes the bump. The prompt does that, so the agent prints its plan into the transcript and continues:
+
+```text
+Upgrade Terreno from 57.16.2 to 57.19.2.
+
+This unattended task names fromVersion 57.16.2 and toVersion 57.19.2 and authorizes the
+lockstep bump. Follow the upgrading-terreno skill. Print the plan into the transcript, then
+perform the upgrade. Do not wait for confirmation.
+
+Check out the latest origin/master and create a feature branch before editing. Do not commit
+to master.
+
+Bump every already-installed @terreno/* dependency to 57.19.2. Do not add @terreno packages
+that are not already installed.
+
+Installed pins:
+package.json workspaces.catalog @terreno/api@57.16.2
+package.json workspaces.catalog @terreno/ui@57.16.2
+
+The target is the TerrenoLabs/terreno GitHub release 57.19.2, not the npm latest dist-tag.
+Install these exact versions. npm dist.integrity:
+@terreno/api@57.19.2 sha512-…
+@terreno/ui@57.19.2 sha512-…
+
+Open exactly one pull request against master. Put <!-- terreno-upgrade --> in its body.
+```
+
+Add the repo-specific steps the skill cannot know, such as which apps run `bun run sdk`. Install the skill in the app first ([install agent skills](install-agent-skills.md)); otherwise the agent has nothing to follow.
+
+Name the agent `Upgrade Terreno to <version>` so checks 6 and 7 can find it.
+
+## Test the script
+
+Inject the I/O (manifest reads, GitHub, npm, the agent API, and the clock) as dependencies and test the decision function with fakes. Cover at least:
+
+- A scheduled tick at 8:59am and 6:00pm local time in both winter and summer
+- Already current, and a pin newer than the target
+- A 6-day-old release on a schedule, and the same release on a manual run
+- Each open pull request signal on its own
+- A finished agent for the same version inside and outside the cooldown
+- A package with no npm integrity
+- A dry run that reports `launch` without calling the agent API
+
+## Try it
+
+Run the workflow manually with `dry_run` checked. The summary shows the decision without launching anything. Then run it locally:
+
+```bash
+GITHUB_EVENT_NAME=workflow_dispatch \
+GITHUB_REPOSITORY=<owner>/<repo> \
+GITHUB_TOKEN=$(gh auth token) \
+TERRENO_UPGRADE_DRY_RUN=true \
+bun .github/scripts/upgrade-terreno.ts
+```

package/dist/docs/versioned/58.0.0/how-to/build-admin-screens.md

@@ -0,0 +1,157 @@
+# Build admin screens
+
+Use this when adding or changing admin UI. Read [How admin interfaces are
+shaped](../explanation/admin-interface.md) first.
+
+## 1. Choose the screen kind
+
+| Need | Do this |
+| --- | --- |
+| CRUD table + form for a Mongoose model | Add `admin` on `modelRouter`. Stop. No new Expo screen. |
+| Dashboard tile on Home | Add a home widget ID to `AdminApp.home.slots` and register `widgets.home`. |
+| Operator tool that is not a model | Register `customScreens` + `widgets.screens` with the same `name`. |
+| Workflow the generic form cannot do | Dedicated Expo route (see consent and comms). Keep the model table for search. |
+
+Adding a model: [Add a model to the admin](admin-add-model.md). Home tiles:
+[Customize the admin home](admin-custom-home.md). Field editors:
+[Add a custom admin field widget](admin-custom-widget.md).
+
+## 2. Wrap the admin tree once
+
+Embedded app (`example-frontend`):
+
+```tsx
+// app/admin/_layout.tsx
+const syncConflicts = useConflicts();
+
+<AdminProvider
+  apiBase="/admin"
+  apiOrigin={baseUrl}
+  getAuthHeaders={getAdminAuthHeaders}
+  routeBase="/admin"
+  syncConflicts={syncConflicts}
+  syncDb={adminSyncDb}
+  widgets={{screens: {"sync-lab": SyncLabScreen}}}
+>
+  <AdminShellLayout
+    apiBase="/admin"
+    configurationPath="/admin/configuration"
+    rolesPath="/roles"
+    routeBase="/admin"
+    versionConfigPath="/version-config"
+  >
+    <Stack screenOptions={{headerShown: false, contentStyle: {flex: 1}}} />
+  </AdminShellLayout>
+</AdminProvider>
+```
+
+The nested `app/admin/[model]/_layout.tsx` stack sets `headerShown: false` too. Without that,
+Expo titles the screen `index` and draws a second back arrow above `AdminScreenPage`.
+
+Render this tree inside `SyncDbProvider client={adminSyncDb}`. If product screens
+also sync the same collection, make `adminSyncDb` a dedicated client with a unique
+store name and `windowCollections` set; do not mix admin rows into the owner/tenant
+product store. Start that client after `canOpenAdminPage` succeeds, block the admin
+shell until `start()` resolves, and call `stop()` when the admin layout unmounts.
+
+Gate entry with `canOpenAdminPage` from `@terreno/syncdb/app` (`admin:access`). Do not
+rely on `user.admin` alone when RBAC is on. Import `baseUrl` from `@terreno/syncdb/config`
+and pass it as `apiOrigin` so admin RPC (`GET /admin/config`, `/rbac/roles`, …)
+hits the API instead of the Expo web origin.
+
+Standalone SPA (`admin-spa`): `routeBase=""`, `apiBase="/admin"`, `credentials="same-origin"`,
+and `getAuthHeaders` that return `{}` so the cookie session is sent without a Bearer header.
+Omit `apiOrigin`. Each route wraps `AdminShellLayout` because the root layout is only
+providers. Model tables render **Create** once, in the table chrome
+(`testID="admin-create-button"`), because admin Expo stacks use `headerShown: false`.
+Model forms render **Save** / **Delete** in the form chrome
+(`testID="admin-save-button"` / `admin-delete-button`) for the same reason.
+The navigator header only receives the screen title.
+
+## 3. Keep generic model routes generic
+
+```
+app/admin/
+  _layout.tsx          # Provider + shell (embedded host)
+  index.tsx            # <AdminHome />
+  [model]/index.tsx    # <AdminScreenRouter name={model} />
+  [model]/create.tsx   # <AdminModelForm mode="create" />
+  [model]/[id].tsx     # <AdminModelForm />
+```
+
+`AdminScreenRouter` resolves the URL segment as: `__scripts` → script list,
+`__migrations` → migrations status (when `GET /admin/config` has
+`migrations.enabled`), matching model name → table, matching custom-screen
+name → `widgets.screens[name]`, else not-found. Do not copy `AdminModelTable`
+into a new file per model.
+
+Create paths are `[model]/create`, not `new`.
+
+## 4. Add a custom screen (both sides)
+
+Backend (`name` is the URL segment and the widget key):
+
+```ts
+new AdminApp({
+  customScreens: [{
+    displayName: "SyncDB Load Lab",
+    name: "sync-lab",
+    description: "Stress-test the local-first sync layer",
+  }],
+});
+```
+
+Frontend: register `widgets.screens["sync-lab"]` on `AdminProvider`. Built-in IDs
+(`comms`, `documents`, `ai-requests`, `version-config`) are already in the
+registry — do not re-map them.
+
+The screen component receives `AdminScreenWidgetProps`. Wrap UI in
+`AdminScreenPage` with `backHref={routeBase}`:
+
+```tsx
+import {AdminScreenPage} from "@terreno/admin-frontend";
+import type {AdminScreenWidgetProps} from "@terreno/admin-frontend";
+
+export const OperationsScreen: React.FC<AdminScreenWidgetProps> = ({routeBase}) => (
+  <AdminScreenPage backHref={routeBase} color="transparent" padding={0} title="Operations">
+    {/* @terreno/ui only */}
+  </AdminScreenPage>
+);
+```
+
+If the screen has extra URL segments (for example `/comms/:id`), add Expo files
+for those paths. Otherwise `[model]/[id]` treats the id as a generic document.
+
+## 5. Fetch data the admin way
+
+- Every admin request goes through the `AdminProvider` fetch client. Admin
+  components take no `api` prop.
+- String-`_id` collections configured with `adminBroadcast` use windowed syncdb
+  when the host passes `syncDb`.
+- ObjectId and API-only models use fetch CRUD. Custom screens call
+  `useAdminModelApi(routePath, modelName)` for list/read/create/update/delete.
+- Bulk patch stays server-side at `{routePath}/bulk-patch` for every model.
+- Custom admin RPC uses `useAdminRpc` + `useAdminRpcQuery` / `useAdminRpcMutation`.
+  Do not add axios or a second request client.
+
+## 6. Sidebar and grouping
+
+Set `admin.group` on the model so related collections share a Models heading.
+Do not add sidebar links in app code. The shell reads `/admin/config`.
+
+Platform links appear only when `platformTools` says they should. Pass
+`configurationPath`, `rolesPath`, and `versionConfigPath` into `AdminShellLayout`
+so those buttons have destinations. Jobs (`customScreens` name `jobs`) appears
+under Platform, not Screens.
+
+## 7. Verify
+
+Log in as an admin (`admin@example.com` / `testpassword123` in the example). Open
+`/admin` (or `/console` for the SPA). Confirm:
+
+1. Home loads with the expected widgets.
+2. The new model or screen is in the correct sidebar section.
+3. Table → create → edit round-trips, or the custom screen's primary action works.
+4. A user without `admin:access` cannot open the page.
+
+Follow `verify-ui-changes`. Save evidence under `/opt/cursor/artifacts/`.

package/dist/docs/versioned/58.0.0/how-to/build-for-web.md

@@ -0,0 +1,69 @@
+# Build for web
+
+Export your Terreno Expo app as static files for hosting on GCS, Netlify, or any CDN.
+
+See the [deployment baseline](../explanation/deployment-baseline.md) for requirements that apply to every host.
+
+## Prerequisites
+
+- Backend running and reachable from browsers (CORS configured).
+- MongoDB replica set for realtime features (see baseline).
+
+## 1. Set the API URL at build time
+
+`EXPO_PUBLIC_API_URL` is **inlined into the JavaScript bundle** during export. Setting it on the hosting platform after deploy does nothing.
+
+```bash
+cd example-frontend
+EXPO_PUBLIC_API_URL=https://api.example.com bun run export
+```
+
+The export script in `example-frontend/package.json` is:
+
+```bash
+bun expo export --platform web
+```
+
+### Alternative: `app.json` `extra.BASE_URL`
+
+`@terreno/syncdb/config` resolves the API base from `expo-constants` `extra.BASE_URL` and `EXPO_PUBLIC_API_URL` (see `syncdb/src/config/resolveBaseUrls.ts`). Priority in **production** builds:
+
+1. `EXPO_PUBLIC_API_URL` environment variable (set before export)
+2. `extra.BASE_URL` in app config (when env var is unset)
+3. Development fallbacks (hostUri, experience URL, localhost) — only in `__DEV__`
+
+For production, prefer `EXPO_PUBLIC_API_URL` so CI and local builds behave the same.
+
+## 2. Run the export
+
+```bash
+EXPO_PUBLIC_API_URL=https://api.example.com bun run export
+```
+
+Output lands in `dist/` (Expo default for web export). Contents depend on the configured web `output` mode — today Terreno apps use the `single` SPA mode (one `index.html`).
+
+## 3. Verify locally before uploading
+
+Serve the `dist/` folder with any static server and confirm API calls hit your backend:
+
+```bash
+npx serve dist -p 4173
+```
+
+Open `http://localhost:4173`, log in, and check the network tab — requests must go to your `EXPO_PUBLIC_API_URL`, not `localhost`.
+
+## 4. Deploy the static files
+
+Upload `dist/` to your host. **Client-side routing** requires the host to serve `index.html` for unknown paths (SPA fallback):
+
+| Host | Configuration |
+|------|---------------|
+| GCS + CDN | `notFoundPage=index.html` on the bucket — see [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) |
+| Netlify | `_redirects` or `netlify.toml` `/* /index.html 200` |
+
+## Provider guides
+
+- [Deploy to GCP](deploy-to-gcp.md) — GCS + Cloud CDN (static web) + Cloud Run (backend)
+- Deployment baseline — [seven requirements](../explanation/deployment-baseline.md)
+
+For server-rendered web (future), see [Web SSR and admin SPA](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md).