@terreno/mcp 57.20.0 → 58.0.0-beta.1

package/dist/docs/versioned/57.20.0/how-to/build-a-durable-workflow.md

@@ -0,0 +1,232 @@
+# Build a durable workflow
+
+Build a multi-step task that survives restarts, asks a person to sign off, and performs its
+side effect exactly once. The one worked example is the example backend's clinical tracer,
+`clinic.intakeSummary`: fetch a chart, summarize it with an agent, wait for a clinician,
+file a note. API: [AI harness reference](../reference/ai-harness.md). Why it is shaped this
+way: [Durable agent harness](../explanation/durable-agent-harness.md).
+
+| File | What it holds |
+| --- | --- |
+| `example-backend/src/harness/clinicalIntake.ts` | The task, the summarizer agent, the approvers |
+| `example-backend/src/harness/fakeEhr.ts` | The EHR client (`getChart`, `writeNote`) over `FakePatientChart` / `FakeClinicalNote` |
+| `example-backend/src/harness/clinicModels.ts` | Model resolver: Gemini when configured, else the demo model |
+| `example-backend/src/harness/clinicDemoModel.ts` | Deterministic local `LanguageModel` for dev and e2e |
+| `example-backend/src/harness/exampleHarness.ts` | `Harness.open` + runner, started in the API process |
+| `example-backend/src/harness/startClinicalIntake.ts` | Admin script that starts a run |
+
+## Try it (5 minutes)
+
+1. Start a replica-set `mongod`, the backend (`bun run backend:dev`), and the frontend
+   (`bun run frontend:web`). Steps: [Run tests locally](run-tests-locally.md).
+2. Seed: `bun run backend:seed`. It creates charts `p-1001`, `p-1002`, `p-1003`, the admin
+   `admin@example.com`, and the clinician `clinician@example.com` (password
+   `testpassword123`).
+3. Start a run: `cd example-backend && bun run script startClinicalIntake --wet --patientId p-1001`,
+   or run `startClinicalIntake` from the admin **Scripts** screen.
+4. Sign in as the admin and open **AI Harness → Approvals**
+   (`http://localhost:8082/admin/harness-approvals`). Open the item and approve it.
+5. Open **AI Observability → Traces**: the newest `clinic.intakeSummary@1` trace shows every
+   phase, the summarizer with its model call, and the sign-off.
+
+## 1. Define the task
+
+Split the work at every point where a crash would need a different answer. Each phase is a
+checkpoint; `replay` says what to do when a phase is cut off.
+
+| Phase | `replay` | Work | Why that policy |
+| --- | --- | --- | --- |
+| `fetch` | `safe` | `ehr.getChart(patientId)`; no chart fails the task | A read; running it twice is harmless |
+| `summarize` | `safe` | `rt.runAgent(summarizer, {input: chart, output: IntakeSummarySchema})` | A replay finds the same subagent turn; finished model calls are not repeated |
+| `review` | `safe` | `rt.approval("clinician-signoff", {...})`; branch on the decision | A replay finds the same approval row |
+| `write` | default (`never`) | `ehr.writeNote(..., {idempotencyKey: \`note-${task.id}\`})` | A write cut off mid-call needs a person to check the EHR |
+
+```typescript
+const intakeSummary = defineTask<IntakeSummaryInput, IntakeSummaryState, IntakeSummaryResult>({
+  name: "clinic.intakeSummary",
+  version: 1,
+  approvals: {"clinician-signoff": {approvers: [isAdminOrClinician]}},
+  initial: () => ({phase: "fetch", state: {}}),
+  retry: {maxAttempts: 3},
+  phases: {
+    fetch: {
+      replay: "safe",
+      run: async (task, rt) => {
+        const chart = await ehr.getChart(task.input.patientId);
+        if (!chart) {
+          await rt.commit({terminal: {status: "failed", error: `No chart for patient ${task.input.patientId}`}});
+          return;
+        }
+        await rt.commit({phase: "summarize", state: {chart}});
+      },
+    },
+    // summarize, review, write: see the sections below
+  },
+});
+```
+
+Keep `state` plain JSON: it is stored on every checkpoint. Bump `version` when phases or
+state change: [Ship a new task version](ship-a-new-task-version.md).
+
+## 2. Add the agent
+
+```typescript
+const summarizer = defineAgent({
+  name: "clinic.summarizer",
+  model, // {provider: "google", modelId: "gemini-2.5-flash"} or the demo model
+  fallbackModels,
+  instructions: CLINIC_SUMMARIZER_INSTRUCTIONS, // a named constant, never inline
+  tools: [],
+});
+
+summarize: {
+  replay: "safe",
+  run: async (task, rt) => {
+    const summary = await rt.runAgent<NoteContent>(summarizer, {
+      input: task.state.chart,
+      output: IntakeSummarySchema, // {summary, risk, sources}
+    });
+    await rt.commit({phase: "review", state: {...task.state, summary}});
+  },
+},
+```
+
+`Harness.open({models})` turns the agent's `{provider, modelId}` into a model. The example
+resolver (`resolveExampleModel`) maps:
+
+| Ref | Model |
+| --- | --- |
+| `google/*` | The server's Gemini / Vertex model (`GEMINI_API_KEY` or `GOOGLE_VERTEX_PROJECT`) |
+| `demo/clinic-summarizer-demo` | The demo model: derives the summary from the chart by fixed rules, prefixes it `[Demo model: no LLM was called]`, calls no network |
+
+The summarizer uses the demo model when no provider is configured or `CLINIC_DEMO_MODEL=true`,
+so dev and e2e runs need no API key. Its `LLM` spans are named `demo/clinic-summarizer-demo`.
+
+## 3. Ask for approval
+
+Declare approvers on the definition, keyed by the approval key. Approvers in one list are
+ANDed, so "admin **or** clinician" is one approver:
+
+```typescript
+const isAdminOrClinician = anyApprover(
+  Permissions.IsAdmin,
+  access.permission({clinicalIntake: ["signoff"]}) // RBAC: the `clinician` role grants it
+);
+
+review: {
+  replay: "safe",
+  run: async (task, rt) => {
+    const decision = await rt.approval("clinician-signoff", {
+      title: `Sign off intake summary for ${chart.name}`,
+      summary: signoffSummary(chart, summary), // markdown shown in the inbox
+      payload: {patientId: chart.patientId, ...summary},
+      timeout: {hours: 24},
+    });
+    if (!decision.approved) {
+      const reason = decision.expired
+        ? "Sign-off expired before anyone decided"
+        : (decision.reason ?? "Rejected");
+      await rt.commit({terminal: {status: "completed", result: {status: "rejected", reason}}});
+      return;
+    }
+    await rt.commit({phase: "write", state: {...task.state, signedOffBy: decision.decidedBy}});
+  },
+},
+```
+
+The example adds the `clinicalIntake.signoff` statement and a `clinician` role
+(`example-backend/src/access.ts`, `rbacRoles.ts`). Admins decide in the admin inbox.
+Clinicians without admin access decide over HTTP (`GET /harness/approvals`,
+`POST /harness/approvals/:id/approve`) or in a `HarnessApprovalInbox` mounted outside the
+admin shell ([admin-frontend](../reference/admin-frontend.md#ai-harness-approvals-inbox)).
+
+## 4. Perform the side effect once
+
+Leave the side-effecting phase at the default `replay: "never"` and pass an idempotency key
+the EHR enforces:
+
+```typescript
+write: {
+  run: async (task, rt) => {
+    rt.signal.throwIfAborted();
+    const note = await ehr.writeNote(task.input.patientId, task.state.summary, {
+      idempotencyKey: `note-${task.id}`,
+      signedOffBy: task.state.signedOffBy,
+      taskId: task.id,
+    });
+    await rt.commit({terminal: {status: "completed", result: {status: "filed", noteId: String(note._id)}}});
+  },
+},
+```
+
+`FakeClinicalNote.idempotencyKey` is unique, so even a retried write returns the first note.
+
+## 5. Register and run
+
+```typescript
+const harness = await Harness.open({
+  models: resolveExampleModel,
+  registry: [intakeSummary, summarizer],
+  runner: new InProcessRunner(exampleRunnerOptions()),
+});
+terraApp.register(new HarnessApp({harness})); // before AdminApp: adds the approvals inbox
+await harness.start();                         // after listen: the runner claims work
+
+await harness.createTask(intakeSummary, {patientId}, {requestId: `intake-${patientId}`});
+```
+
+`requestId` makes starting idempotent: the script returns the first run for a repeated key
+(pass `--requestId` to start another). Every process that runs or decides tasks registers
+the same definitions.
+
+## 6. Observe
+
+| Where | What you see |
+| --- | --- |
+| **AI Harness → Approvals** | The pending sign-off: title, markdown summary, payload |
+| **AI Observability → Traces** (`/admin/ai-trace-detail?id=<traceId>`) | The span waterfall |
+| `GET /ai/observability/traces/:traceId` | The same tree as JSON (admin) |
+| `GET /harness/tasks/:id/events` | Live `task.status` and `approval.*` events (SSE) |
+
+`HarnessTask.traceId` links a run to its trace. A completed run's tree:
+
+```
+CHAIN clinic.intakeSummary@1
+├── CHAIN fetch
+├── CHAIN summarize                          (waiting on the summarizer)
+├── AGENT clinic.summarizer
+│   ├── CHAIN request
+│   └── LLM   demo/clinic-summarizer-demo
+├── CHAIN summarize                          (summary committed)
+├── CHAIN review                             (waiting on sign-off)
+├── CHAIN wait:terreno.approval:clinician-signoff:<step>:0
+├── CHAIN approval:clinician-signoff         (decision, decidedBy)
+├── CHAIN review
+└── CHAIN write
+```
+
+## 7. Recover an interrupted run
+
+| Cut off during | What happens | You do |
+| --- | --- | --- |
+| `fetch`, `summarize`, `review` | After the lease expires (`HARNESS_LEASE_SECONDS`, default 30), the next runner replays the phase. A cut-off model request is re-requested; an error `request` span records the interruption. | Nothing |
+| `write` | The task goes `interrupted`. | Check the EHR for `note-<taskId>`, then `POST /harness/tasks/:id/resolveInterrupted` with `{action: "retry" \| "complete" \| "abort", reason}` |
+
+The proof is `example-backend/src/harness/clinicalIntake.crash.test.ts`. It starts the real
+API process (`bun run src/index.ts`) against a replica set with
+`CLINIC_DEMO_MODEL_DELAY_MS=600000`, starts a run, waits until the summarizer's model
+request is in flight, sends `SIGKILL`, starts a fresh process, approves, and asserts:
+the run ends `filed`, exactly one `FakeClinicalNote` exists, and the trace has one `LLM`
+span plus an interruption span naming the dead process's lease. Run it with
+`cd example-backend && bun test src/harness/clinicalIntake.crash.test.ts` (about 50 s).
+The Playwright spec `example-frontend/e2e/harness-intake.spec.ts` covers approve-in-inbox →
+`filed` → span tree in the Traces screen.
+
+## Configuration
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `GEMINI_API_KEY` / `GOOGLE_VERTEX_PROJECT` | unset | When set, the summarizer uses `google/gemini-2.5-flash` (fallback `gemini-2.5-flash-lite`) |
+| `CLINIC_DEMO_MODEL` | unset | `true` forces the demo model even with a provider |
+| `CLINIC_DEMO_MODEL_DELAY_MS` | `0` | Demo model waits this long per request (crash drills) |
+| `HARNESS_LEASE_SECONDS` | `30` | Owner and task lease; heartbeat is a third of it. Short values speed up crash recovery in tests |

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

@@ -0,0 +1,152 @@
+# 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
+  api={api}
+  apiBase="/admin"
+  apiOrigin={baseUrl}
+  getAuthHeaders={getAdminAuthHeaders}
+  routeBase="/admin"
+  syncConflicts={syncConflicts}
+  syncDb={adminSyncDb}
+  widgets={{screens: {"sync-lab": SyncLabScreen}}}
+>
+  <AdminShellLayout
+    api={api}
+    apiBase="/admin"
+    configurationPath="/admin/configuration"
+    rolesPath="/roles"
+    routeBase="/admin"
+    versionConfigPath="/version-config"
+  >
+    <Stack screenOptions={{headerShown: false, contentStyle: {flex: 1}}} />
+  </AdminShellLayout>
+</AdminProvider>
+```
+
+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/rtk` (`admin:access`). Do not
+rely on `user.admin` alone when RBAC is on. Import `baseUrl` from `@terreno/rtk`
+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
+
+- String-`_id` collections configured with `adminBroadcast` use windowed syncdb
+  when the host passes `syncDb` plus fetch auth.
+- ObjectId model CRUD and API-only hosts keep `useAdminApi`.
+- Bulk patch remains server-side: native admin fetch for windowed hosts, RTK fallback otherwise.
+- Admin RPC uses the host-bound native fetch client. Do not add axios.
+
+## 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/57.20.0/how-to/build-list-detail-screens.md

@@ -0,0 +1,160 @@
+# Build a list/detail screen
+
+Put the list and its detail route in one route group, and make `ListDetailLayout` the group's
+layout. On a phone the list pushes the detail. On a tablet or a wide browser the list stays in a
+left pane and the detail opens beside it. The URL always names the open item.
+
+```text
+app/mail/
+  _layout.tsx   ListDetailLayout
+  index.tsx     ListDetailIndex
+  [id].tsx      the detail screen
+```
+
+```tsx
+// app/mail/_layout.tsx
+import {ListDetailLayout, Text} from "@terreno/ui";
+import type React from "react";
+
+import {MailList} from "@/components/MailList";
+
+// A deep link to /mail/3 on a phone still has the list to go back to.
+export const unstable_settings = {initialRouteName: "index"};
+
+const MailLayout: React.FC = () => (
+  <ListDetailLayout
+    detailHref={(id) => `/mail/${id}`}
+    emptyDetail={<Text>Select a message</Text>}
+    indexHref="/mail"
+    list={<MailList />}
+    screenOptions={{title: "Inbox"}}
+  />
+);
+export default MailLayout;
+```
+
+```tsx
+// app/mail/index.tsx
+import {ListDetailIndex} from "@terreno/ui";
+import type React from "react";
+
+const MailIndex: React.FC = () => <ListDetailIndex />;
+export default MailIndex;
+```
+
+```tsx
+// app/mail/[id].tsx
+import {Page, Text} from "@terreno/ui";
+import {useLocalSearchParams} from "expo-router";
+import type React from "react";
+
+const MailMessage: React.FC = () => {
+  const {id} = useLocalSearchParams<{id: string}>();
+  return (
+    <Page>
+      <Text>Message {id}</Text>
+    </Page>
+  );
+};
+export default MailMessage;
+```
+
+## Select rows from the list
+
+Read the open item and open others with `useListDetail()`. Mark the open row as selected so
+screen readers announce it. On web a clickable `Box` row sends this as `aria-current="true"`.
+
+```tsx
+import {Box, Text, useListDetail} from "@terreno/ui";
+import type React from "react";
+
+export const MailRow: React.FC<{id: string; subject: string}> = ({id, subject}) => {
+  const {select, selectedId} = useListDetail();
+  const isSelected = id === selectedId;
+  return (
+    <Box
+      accessibilityHint="Opens the message"
+      accessibilityLabel={subject}
+      accessibilityState={{selected: isSelected}}
+      color={isSelected ? "primary" : "base"}
+      onClick={() => select(id)}
+      padding={3}
+      testID={`mail-row-${id}`}
+    >
+      <Text color={isSelected ? "inverted" : "primary"}>{subject}</Text>
+    </Box>
+  );
+};
+```
+
+| Call | Stacked (phone) | Split (tablet, wide web) |
+| --- | --- | --- |
+| `select(id)`, nothing open | Pushes `detailHref(id)` | Pushes `detailHref(id)` |
+| `select(id)`, another item open | Pushes `detailHref(id)` | Replaces the open detail |
+| `select(selectedId)` | Pushes again | Does nothing |
+| `clear()` | `router.dismissTo(indexHref)`: pops back to the list inside this group | Same |
+| `clear()`, nothing open | Does nothing | Does nothing |
+
+Because split mode replaces the open detail, the stack is never deeper than the list plus one
+detail, so back returns to the list after a rotation too. When split, the header's back button
+(`list-detail-leave`) leaves the whole group instead, since the list is already on screen.
+
+When another screen opens a detail directly, push it with `withAnchor` so the list sits below it
+and back lands on the list instead of leaving the group:
+
+```tsx
+router.push("/mail/3", {withAnchor: true});
+<Link href="/mail/3" withAnchor>Open message</Link>
+```
+
+`selectedId` is the `paramName` param (default `id`) of the route directly below `indexHref`
+whose segment is `detailRoute` (default `[id]`). An `id` from a parent dynamic segment, such as
+`/orgs/[id]/mail`, never counts.
+
+## Publish the detail URL
+
+A static web export (`web.output: "static"`) writes an HTML file only for paths
+`generateStaticParams` returns. Without it, opening `/mail/3` directly is a 404 on a host that
+does not rewrite unknown paths.
+
+```tsx
+// app/mail/[id].tsx
+export const generateStaticParams = (): {id: string}[] =>
+  messages.map((message) => ({id: message.id}));
+```
+
+Ids that are not known at build time need the host fallback from
+[Build for web](build-for-web.md): Netlify `_redirects` with `/* /index.html 200`, or the Vercel
+rewrite in [Deploy to Vercel](deploy-to-vercel.md). The demo inbox exports one page per fixture
+message at `/demo/list-detail/:id` and `/demo/sidebar-navigation/mail/:id`. The Netlify demo
+deploy also writes that fallback, so an id outside the fixtures still opens the missing-message
+screen.
+
+## Keep list state across the breakpoint
+
+The open item survives a rotation or a browser resize. The `list` element does not: it moves
+between the index screen and the left pane, so it remounts. Keep filters, search text, and other
+list state in the route (`router.setParams`) or a store.
+
+## Nest it inside a sidebar
+
+`ListDetailLayout` measures its own width, so it splits correctly inside `SidebarNavigation` or
+an admin rail. Make the group a screen of the sidebar navigator:
+
+```text
+app/workspace/
+  _layout.tsx         SidebarNavigation with <SidebarNavigation.Screen name="mail" />
+  mail/_layout.tsx    ListDetailLayout with indexHref="/workspace/mail"
+  mail/index.tsx
+  mail/[id].tsx
+```
+
+## Choose SplitPage instead
+
+Use `SplitPage` when the list and detail do not have their own routes, such as a picker inside a
+modal. `SplitPage` keeps the selection in component state, so it has no URL, deep links, or back
+navigation for the open item.
+
+## Reference
+
+Props, defaults, and testIDs: [`ListDetailLayout`](../reference/ui.md#listdetaillayout).

package/dist/docs/versioned/57.20.0/how-to/call-external-apis.md

@@ -0,0 +1,101 @@
+# Call external APIs
+
+How to talk to third-party HTTP APIs (payment processors, health integrations, meeting providers, etc.) from a `@terreno/api` backend using the shared HTTP client utilities, instead of hand-rolling axios setup, token caching, retry, and error handling per integration.
+
+## When to use each piece
+
+| You are... | Use |
+|---|---|
+| Calling a third-party REST API that needs a bearer token, OAuth2 client-credentials, or API-key auth | `createAuthenticatedClient` |
+| Calling an external service through its own SDK (Twilio, Google APIs, Stripe) | `withApiErrorHandling` around the SDK calls — the SDK owns transport, you standardize failures |
+| Logging or classifying a caught error from any external call | `normalizeApiError` |
+| Surfacing an external failure to your API's consumers from a route handler | `withApiErrorHandling` with `rethrowAs: "apiError"` |
+| Making internal requests to your own `@terreno/api` backend | None of these — use `@terreno/rtk` on the frontend or direct function calls on the backend |
+
+**Rule of thumb:** any file that would otherwise contain `axios.create(...)` plus a token variable plus a `try/catch → axios.isAxiosError → log → throw` block should use these utilities instead.
+
+## Create a client
+
+```typescript
+import {createAuthenticatedClient} from "@terreno/api";
+
+const widgetApi = createAuthenticatedClient({
+  apiName: "widgetService", // used in logs and normalized errors; defaults to baseURL
+  auth: {
+    credentials: {clientId: process.env.WIDGET_CLIENT_ID!, clientSecret: process.env.WIDGET_CLIENT_SECRET!},
+    refreshOn401: true,
+    tokenUrl: "https://api.widgets.example/oauth/token",
+    type: "oauth2",
+  },
+  baseURL: "https://api.widgets.example/v2",
+});
+
+const response = await widgetApi.axios.get("/widgets/123");
+```
+
+Auth strategies:
+
+- `{type: "bearer", getToken}` — you supply an async token fetcher; the client caches the result until `invalidateToken()` is called.
+- `{type: "oauth2", tokenUrl, credentials, refreshOn401}` — the client performs the client-credentials grant itself (HTTP Basic auth, form-encoded). With `refreshOn401: true`, a 401 response invalidates the cached token and retries the request exactly once with a fresh one.
+- `{type: "apiKey", header, getKey}` — the key is sent on the header you name.
+
+Tokens are fetched lazily and concurrent first requests share a single fetch. Create the client once per service at module scope — not per request — so the token cache is actually shared.
+
+## What you get for free
+
+- **Retry with backoff** for transient failures (429 rate limits, 5xx, network errors), honoring `Retry-After`, capped by `maxDelayMs`. Defaults: 3 total attempts, 250ms base delay, 30s delay ceiling — override via the `retry` option.
+- **Idempotency safety**: only GET/HEAD/OPTIONS are retried by default. Retrying a failed POST can duplicate side effects (a payment, a prescription, a meeting). If a specific POST/PUT/DELETE is genuinely safe to repeat, opt it in per request:
+
+  ```typescript
+  import {markRetryUnsafe} from "@terreno/api";
+
+  // Safe to repeat: the upstream endpoint is idempotent on externalId.
+  await widgetApi.axios.post("/widgets", {externalId, name}, markRetryUnsafe());
+  ```
+
+  The request body must be replayable — JSON is fine; streams/FormData are consumed on first send.
+- **Quiet transport logging**: the client logs retries and token refreshes at debug level only and always rejects with the original axios error. Error-level logging belongs to the call site (next section) so composed usage logs each failure exactly once.
+
+## Handle failures at the call site
+
+Wrap calls with `withApiErrorHandling` to normalize, log once, and rethrow:
+
+```typescript
+import {withApiErrorHandling} from "@terreno/api";
+
+export const getWidget = async (id: string): Promise<Widget> => {
+  const response = await withApiErrorHandling(() => widgetApi.axios.get(`/widgets/${id}`), {
+    apiName: "widgetService",
+    operation: "getWidget",
+  });
+  return response.data;
+};
+```
+
+- Default (`rethrowAs: "raw"`): logs the normalized shape (status code, classification, extracted messages) and rethrows the original error for callers that need it.
+- `rethrowAs: "apiError"`: throws a terreno `APIError` (stable title, per-occurrence `detail`) so route handlers surface a clean JSONAPI error instead of a raw axios failure. In this mode the `APIError` constructor does the logging.
+
+For SDK-based integrations where `createAuthenticatedClient` doesn't apply, `withApiErrorHandling` still works — `normalizeApiError` classifies non-axios errors as `"unknown"` while preserving the message.
+
+## Sensitive response data
+
+`normalizeApiError` never logs raw payload bodies: it extracts only recognized message fields (`{message}`, JSONAPI `{errors: [{title, detail}]}`, plain strings truncated to 500 chars). If the upstream service puts sensitive data *inside* those message fields, supply a `redactError` hook (available on both `createAuthenticatedClient` and `withApiErrorHandling`):
+
+```typescript
+redactError: (normalized) => ({
+  ...normalized,
+  messages: normalized.messages.map((message) => message.replace(PATIENT_ID_PATTERN, "[redacted]")),
+}),
+```
+
+Note the hook's output classification also feeds the client's retry decision — redact messages, don't rewrite classifications, unless changing retry behavior is intended.
+
+## When not to use this
+
+- **Your own backend's routes** — use the generated `@terreno/rtk` SDK (frontend) or call the function directly (backend).
+- **SDK-managed transport** (Twilio, googleapis) — don't fight the SDK's HTTP layer; adopt only `normalizeApiError`/`withApiErrorHandling` for consistent failure handling.
+- **Webhook notifiers** — `sendToSlack`/`sendToGoogleChat`/`sendToZoom` post to a fixed webhook. Slack channel creation, invites, and bot posts use `createSlackPrivateChannel`, `inviteSlackUsersToChannel`, and `postSlackMessage` with `SLACK_BOT_TOKEN`. See [Webhooks & Notifications](../reference/api.md#webhooks--notifications).
+
+## Related
+
+- [@terreno/api reference — HTTP Client](../reference/api.md#http-client)