modelrig 0.9.0 → 0.11.0

package/docs/instrumentation.md

@@ -1,5 +1,7 @@
 # Artifact instrumentation (runs, steps, artifacts)
 
+**The question this page answers: how do I record what my pipeline actually did, run by run, step by step, without changing what it does?**
+
 ModelRig can record the **execution graph** of any pipeline your code runs — the
 run, its steps, and the artifacts each step produced (the prompt, the raw model
 text, the parsed output, the evidence it grounded on) — with lineage,
@@ -19,11 +21,13 @@ byte-for-byte as before.) `modelrig status` prints the current posture (on/off +
 second axis — the recommended, consent-gated [content custody](content-custody.md)
 path — never blurred with the telemetry axis here.
 
-> **Metadata + hashes only, this release.** The serialized value you save is
-> hashed (sha256) and the bytes are **discarded** — nothing but the metadata row
-> is persisted. Content custody (the blob path) ships in a later release; the
-> hash proves integrity today. A `zeroRetention` run refuses every artifact
-> fail-closed at the SDK gate.
+> **What `artifact.save` keeps.** This page is the metadata axis: every saved
+> artifact records a metadata row with a sha256 integrity hash, whatever your
+> content setting. Whether the serialized *bytes* are kept as well is your
+> organization's [content custody](content-custody.md) posture: new
+> organizations are created `managed` (bytes kept in your managed store); posture
+> `metadata` keeps hashes only and `off` captures nothing. A `zeroRetention` run
+> refuses every artifact fail-closed at the SDK gate.
 
 ## The namespace toggle
 
@@ -57,11 +61,11 @@ const rig = createRig(loadConfigFromEnv());
 
 // 1. Open a run context around the pipeline. episodeKey bridges grades;
 //    it is a grouping key, not a unique id — a natural choice is your own
-//    per-run attempt id.
+//    per-run attempt id. environment fills the Env column on /runs.
 const run = rig.artifacts.run.start({
   pipeline: "my-pipeline",
   episodeKey: runAttemptId,
-  environment: process.env.NODE_ENV,
+  environment: process.env.NODE_ENV,   // e.g. "production", "staging", "test"
 });
 try {
   for (const step of steps) {
@@ -111,6 +115,23 @@ right for one run at a time on a request/async path.
   and honest. Never route a stage through the rig just to mint a step row; the
   console renders "cost n/a" for un-routed steps rather than inventing a number.
 
+### Record a call your code made itself (`rig.recordCall`)
+
+_Needs `modelrig` 0.11.0 or newer._
+
+If a stage's model call has to stay a direct provider call, report it instead:
+`rig.recordCall({ provider, model, usage: { tokensIn, tokensOut, tokensCached }, servedTier, latencyMs, stepKey })`
+right after the call returns. Inside a run context it records a step row for
+that `stepKey` (stored as `ground-truth`, the only joined-inference value),
+joined to the recorded inference, so the step gets a cost instead of "cost n/a".
+The console shows that step and its call as **recorded · unverified**, never as
+measured:
+ModelRig neither dispatched nor validated the call, and the tokens are the ones
+you reported. It is synchronous and never throws (bad input warns and returns
+`inferenceId: null`); the returned `inferenceId` is gradeable with `rig.grade`.
+Full contract, usage convention and cost notes:
+[Not captured → record them](not-captured.md#calls-your-code-makes-itself-record-them).
+
 ## Tags, dimensions, and the graph
 
 ModelRig has **two** grouping mechanisms, and they compose:
@@ -137,22 +158,29 @@ process** (`required dimension "project" missing from run tags — costs … wil
 under-attributed on /costs`) — on the routed lane and the raw lane alike. It is a
 hygiene warning, never an error: the run proceeds.
 
-**Conventional tag keys** (documented, not enforced): `subject` (your
-end-customer — the tenant key), `feature`, `project` (flat grouping),
-`step` (names the step this call belongs to), and `run_id` (bridges a call to a
-run's `episodeKey`). `subject` is your end-customer's opaque id — it powers the
-per-customer tenant statements on `/tenants`; a tag named `client`/`tenant` is
-only a cost dimension. (Hash it yourself if it looks like PII — see
-[tenants.md](./tenants.md).) **Inside a `run.start` / `run.scope` context the SDK stamps
-both `run_id` and `step` for you** — `run_id` = the run's
-`episodeKey`, or its id when you gave none; `step` = the current step key (your
-explicit `stepKey`, else `tags.step`, else the auto `route#n` / `provider/model#n`
-key) — on every attempt row of both lanes, unless you passed your own value (yours
-always wins). Outside a run context nothing is stamped, so the row is
-byte-identical. This is why runs are the standard path: a `run.start` alone fills
-both `/runs` (the graph) and `/projects` (the tag tree), with no hand-written id.
-ModelRig owns `lane`, `zdr_enforced`, `rung`, and — on the hosted gateway —
-`key_ownership`; you cannot override those.
+### Reserved tag keys (the one list)
+
+Any other key is yours. These are reserved:
+
+| Key | Who sets it | What it means |
+|---|---|---|
+| `subject` | you | Your end-customer's **opaque** id. It powers the per-customer tenant statements on `/tenants`; hash it if it looks like PII ([tenants.md](./tenants.md)). A tag named `client` or `tenant` is only a cost dimension. |
+| `feature` | you | The product feature the call serves. |
+| `user` | you | The end user, as an opaque id. |
+| `session` | you | The conversation or session the call belongs to. |
+| `cost_center` | you | The team or budget to attribute spend to. |
+| `run_id` | **the SDK**, inside a run | The run's `episodeKey`, or its id when you gave none. **Don't set it yourself.** A value you pass overrides the stamp, so the call no longer joins its run on `/runs` and the console's Run ID group-by disagrees with `/runs`. Put your own attempt id in a key of your own, such as `pipeline_attempt_id`. |
+| `step` | **the SDK**, inside a run | The current step key: your explicit `stepKey`, else `tags.step`, else an auto `route#n` / `provider/model#n` key. Name steps with `stepKey`. |
+| `lane`, `zdr_enforced`, `rung`, `key_ownership` | ModelRig | Set by the SDK or the hosted gateway. You can't override them. |
+| `replay`, `replay_capture`, `variant`, `cutover` | ModelRig tooling | Set by bake-offs and replays. |
+
+The five keys you set are first-class group-bys in the cost and coverage views, so use them verbatim; `modelrig validate` warns about near-misses such as `costcenter` or `team`. `project` and `environment` are common conventions, not reserved.
+
+**Inside a `run.start` / `run.scope` context the SDK stamps `run_id` and `step`
+on every attempt row of both lanes.** Outside a run context nothing is stamped,
+so the row is byte-identical. This is why runs are the standard path: a
+`run.start` alone fills both `/runs` (the graph) and `/projects` (the tag tree),
+with no hand-written id.
 
 **How they compose.** Inside a `run.start` context, both `rig.run` and
 `rig.runRaw` record a **ground-truth step** and carry the run's `run_id` tag, so
@@ -234,8 +262,49 @@ Every entry point is fail-open: a telemetry-buffer write that fails is logged an
 dropped, never thrown into your code. Instrumentation that runs *after* an
 expensive model call must never be the thing that kills the run.
 
+## Which org am I exporting to?
+
+A valid key minted in the wrong org fails silently: every ingest call succeeds,
+and the runs land in someone else's console. So the first time a process flushes
+telemetry, the SDK asks `GET /v1/whoami` once and logs where it is exporting:
+
+```text
+[modelrig] exporting to org «Acme Analytics» (acme-analytics) as key «production exporter» rig_sk_…ab12
+```
+
+The call runs in the background. It never delays or drops a batch, and if it
+fails it says nothing (a rejected key already gets its own loud `AUTH FAILED`
+line). To have the SDK check the org for you, pass the slug you expect in code:
+
+| Config option | Type | Default | What it does |
+|---|---|---|---|
+| `expectOrg` | `string` (org slug) | absent | When the key resolves to a different org, logs `[modelrig] ORG MISMATCH: key resolves to «a», expectOrg is «b» — telemetry is landing in «a»` loudly on every flush once the org is known. It never throws and never drops telemetry: the rows still land in the key's org. |
+
+```ts
+const rig = createRig({ ...loadConfigFromEnv(), expectOrg: "acme-analytics" });
+```
+
+It is a code option, not an environment variable. To gate a deploy or CI step
+on the same check, run `modelrig doctor --expect-org acme-analytics`. It exits 1 and
+prints both slugs when the key belongs to a different org. More on keys,
+orgs and the console picker: [Orgs and keys](https://modelrig.dev/orgs-and-keys.html).
+
 ## See it
 
+Check first that the console is showing the org your key exports to:
+
+<!-- BLOCK:CONFIRM_ORG -->
+**Confirm the org before you trust an empty console.** Run `modelrig doctor` from the same environment your app runs in. It asks GET /v1/whoami which organization the key belongs to, and the name it prints must match the org badge in the console header. If it names a different organization, your data is landing there: switch the console to that organization, or mint a key in the one you meant (https://modelrig.dev/orgs-and-keys.html).
+
+```bash
+npx modelrig doctor
+# [modelrig] key rig_sk_…AbCd → org «Your Org» ✓  (ingest https://api.modelrig.ai, …)
+
+# No CLI in that environment? Ask the API directly:
+curl -H "Authorization: Bearer $MODELRIG_API_KEY" https://api.modelrig.ai/v1/whoami
+```
+<!-- /BLOCK:CONFIRM_ORG -->
+
 The console's **Runs** tab lists every instrumented run; `/runs/[id]` is the
 semantic chain (artifacts grouped by step, with hashes, costs, and grade
 badges) and `/artifacts/[id]` shows one artifact's lineage, versions, and
@@ -252,15 +321,15 @@ that decides how much confidence a swap proposal carries.
 
 ```ts
 // One call — the inference id rides on every RunResult:
-const result = await rig.run("example.support_summarize", { input, tags: { run_id } });
+const result = await rig.run("example.support_summarize", { input, tags: { subject } });
 rig.grade({ kind: "inference", id: result.meta.inferenceId }, { score: 1, kind: "human" });
 
-// A whole run (the subject id is your run_id tag):
-rig.grade({ kind: "run", id: run_id }, { score: 0.2, comment: "CAGR off by 10x", kind: "human" });
+// A whole run: the subject id is the run's run_id (its episodeKey, or its id).
+rig.grade({ kind: "run", id: runAttemptId }, { score: 0.2, comment: "CAGR off by 10x", kind: "human" });
 ```
 
 - **The subject** is `{ kind: "inference", id }` (`result.meta.inferenceId`),
-  `{ kind: "run", id }` (the run's `run_id`/`episodeKey` tag), or
+  `{ kind: "run", id }` (the run's `run_id` — its `episodeKey`, or its id), or
   `{ kind: "artifact", id }`. **`opts`** is `{ score, scale?, comment?, kind,
   source? }` — the `score` in `[0, 1]` is the primitive (up = 1, down = 0), and
   the pass/fail verdict is derived from it against the route threshold. A subject
@@ -274,8 +343,8 @@ rig.grade({ kind: "run", id: run_id }, { score: 0.2, comment: "CAGR off by 10x",
   network call and never a failure your code can see; the cloud mirror rides the
   telemetry exporter's normal cadence.
 - **Why it matters.** A route with **≥10 attached grades** reaches **Rung 1** on
-  `/coverage`; a route with no schema to conform to (a prose output) gains
-  proposal confidence only this way. Grades are also what let `/insights`
+  `/coverage`; a route with no schema to conform to (an `output: text` prose
+  route, or a schema-less JSON route) gains proposal confidence only this way. Grades are also what let `/insights`
   surface a task that is degrading.
 - **From a non-SDK surface** (an end user clicking thumbs-down in your web app),
   post the same fields to `POST /v1/grade` with a `rig_sk_` key carrying the
@@ -340,10 +409,3 @@ function recordStep(
 Call `recordStep(step, { … })` once per stage inside the `run.start` / `run.end`
 context above, and every entry point stays fail-open — a save that fails is
 logged and dropped, never thrown into your pipeline.
-
-> **In-repo example (reconstructed via onboarding-test run-2).** ModelRig's own
-> customer-zero pipeline (the InferWealth v3 report generator) was stripped back
-> to a clean slate to be re-onboarded through this exact doc. Its live seam is
-> reconstructed as part of onboarding-test run-2; until then, the snippet above
-> is the reference. Do not resurrect a deleted seam from git history — writing a
-> fresh one is the point.

package/docs/llms.txt

@@ -4,7 +4,7 @@
 > grounding, and caching measured empirically, with a capability-aware
 > gateway that routes by them. Registry data CC BY 4.0; code Apache-2.0.
 
-_This reference is as of modelrig v0.9.0 (the published npm package). Any surface below that a newer workspace adds is marked "unreleased — workspace only" until its release; nothing is so marked as of this version._
+_This reference is as of modelrig v0.11.0 (the published npm package). Any surface below that a newer workspace adds is marked "unreleased — workspace only" until its release; nothing is so marked as of this version._
 
 ## Docs
 
@@ -36,6 +36,12 @@ _This reference is as of modelrig v0.9.0 (the published npm package). Any surfac
 - [Template: call disposition QA](https://modelrig.dev/template-call-disposition-qa.html): A starting point for checking a call's logged disposition and scoring it against your QA scorecard from the transcript: a starter schema with a TODO disposition slot and a placeholder scorecard object, a starter grading guide that checks every judgment is grounded in the transcript, a golden checklist for disputed and sensitive calls, and an escalation starter. Transcript in — you bring your own transcription; no accuracy claims.
 - [Template: financial classification](https://modelrig.dev/template-financial-classification.html): A starting point for classifying a financial record into your categories and risk flags: a starter schema with TODO enum slots, a starter grading guide that checks the classification is grounded and the risk flag follows your rules, a golden checklist for edge-of-rule and sensitive records, and an escalation starter. Regulated data — the fit note quotes the published custody terms verbatim; no other compliance claim, no accuracy claims.
 - [Template: medical classification](https://modelrig.dev/template-medical-classification.html): A starting point for classifying a clinical document into your categories: a starter schema with a TODO category slot, a starter grading guide that keeps the output a classification rather than a clinical judgment, a golden checklist for cross-category and clinically significant documents, and an escalation starter. Regulated data — the fit note quotes the published custody terms verbatim; no other compliance claim, no accuracy claims.
+- [Managed serving](https://modelrig.dev/managed-serving.html): Serve a route's model on ModelRig's own credentials — destination: modelrig-served — paid from your prepaid balance at provider list cost plus the flat fee: declare the destination, enable managedServing in code, mint a serve-scoped key, opt the organization in, fund the balance; what each refusal teaches; the destination tag on the row; and the honest direct default that nothing here changes.
+- [Orgs and keys](https://modelrig.dev/orgs-and-keys.html): One key = one org: how to see which organization a key exports to (`modelrig doctor`, `GET /v1/whoami`, the console badge), how the console picks the org it shows (the picker, `409 org_required`, `401 session_expired`), why a valid key in the wrong org looks like an empty console, and `doctor --expect-org` / `createRig({ expectOrg })`.
+- [Choosing a lane](https://modelrig.dev/choosing-a-lane.html): Observe (wrap what you have in a run), the `rig.runRaw` seam (one adapter for a router you already own) or named routes (`rig.run`): when each fits, what you get, what you give up, what it costs — and why to start with observe.
+- [Not captured](https://modelrig.dev/not-captured.html): What ModelRig does not see — direct provider SDK calls, streams read outside the SDK, fallbacks after a fail-closed schema, calls outside a run, embeddings — and the console tells: `cost n/a` steps, a missing `inferenceId`, a run total below your provider bill.
+- [Deploying on hosted workers](https://modelrig.dev/deploying.html): Set MODELRIG_API_KEY on every process; Render's env-group vs service-override precedence; a change needs a finished redeploy and a new shell; rotate keys mint → set → redeploy → doctor → revoke; verify after every deploy with `doctor --expect-org`, then one run on /runs; notes for Vercel, Fly and Docker.
+- [Troubleshooting an empty console](https://modelrig.dev/troubleshooting.html): The "console is empty" decision tree: is the process exporting (doctor: AUTH FAILED / no export sink / org ✓), is it the org you are viewing, are the calls inside a run, is the missing call on a ModelRig lane, and does your install match the docs.
 - [Leaderboard](https://modelrig.dev/leaderboard.html): Models ranked by effective cost per 1,000 schema-conformant outputs, with declared-vs-probed discrepancy flags.
 
 ## Source
@@ -43,9 +49,77 @@ _This reference is as of modelrig v0.9.0 (the published npm package). Any surfac
 - [Public repo](https://github.com/modelrig/modelrig): probe suite, registry data, contribution kits.
 - [Registry JSON](https://github.com/modelrig/modelrig/blob/main/registry/registry.json): three layers per model (declared / probed / observed aggregates) with as_of stamps.
 
+## Start here: from zero to your first run on /runs
+
+_The default ingest host is https://api.modelrig.ai (override with `MODELRIG_INGEST_URL` only if you were given another). Choosing how your calls reach ModelRig: https://modelrig.dev/choosing-a-lane.html. Which org your data lands in: https://modelrig.dev/orgs-and-keys.html. Hosted workers: https://modelrig.dev/deploying.html. What is not captured: https://modelrig.dev/not-captured.html. Console empty: https://modelrig.dev/troubleshooting.html._
+
+**Mint a key in the org you want the data in.** Sign in at https://app.modelrig.ai, check the organization name in the header badge, and create a key on the API keys page. The `rig_sk_` secret is shown once. One key = one org: every row the key exports lands in the organization it was minted in, whichever organization you happen to be viewing in the console. Set it on every service, worker and cron that creates a rig; your provider keys stay where they are.
+
+```bash
+# Wherever your app reads configuration: .env.local, your platform's env vars, a secret manager. Never in code.
+MODELRIG_API_KEY=rig_sk_…
+```
+
+**Confirm the org before you trust an empty console.** Run `modelrig doctor` from the same environment your app runs in. It asks GET /v1/whoami which organization the key belongs to, and the name it prints must match the org badge in the console header. If it names a different organization, your data is landing there: switch the console to that organization, or mint a key in the one you meant (https://modelrig.dev/orgs-and-keys.html).
+
+```bash
+npx modelrig doctor
+# [modelrig] key rig_sk_…AbCd → org «Your Org» ✓  (ingest https://api.modelrig.ai, …)
+
+# No CLI in that environment? Ask the API directly:
+curl -H "Authorization: Bearer $MODELRIG_API_KEY" https://api.modelrig.ai/v1/whoami
+```
+
+**Wrap one pipeline execution in a run.** Every pipeline execution is a run. Wrap each execution in `run.scope` (or `run.start` / `run.end`), name one step per model call with `stepKey`, `artifact.save` the work products, and pass `environment` so the Env column on /runs is filled. Inside the run the SDK stamps `run_id` and `step` on every call. `run_id` is reserved: don't set it yourself.
+
+```ts
+import { createRig, loadConfigFromEnv } from "modelrig";
+
+const rig = createRig(loadConfigFromEnv());
+
+// Every pipeline execution is a run. Inside the scope the SDK records each
+// rig.run / rig.runRaw call as a step and stamps run_id and step on every row.
+// run_id is reserved: don't set it yourself (put your own attempt id in a tag of
+// your own, such as pipeline_attempt_id).
+await rig.artifacts.run.scope(
+  { pipeline: "support", episodeKey: ticketId, environment: process.env.NODE_ENV ?? "development" },
+  async () => {
+    const result = await rig.run("example.support_summarize", {
+      input: { ticket, product, priorContext },
+      tags: { subject: customer, feature: "summarize" },
+      stepKey: "summarize", // names this step on /runs
+    });
+    rig.artifacts.artifact.save(result.output, { name: "summary", type: "step_output", stepKey: "summarize" });
+  },
+);
+
+await rig.close(); // flushes the exporter — call once at shutdown
+```
+
+**What ModelRig does not see unless you record it.** ModelRig records the calls your code makes through the SDK (`rig.run`, `rig.runBundle`, `rig.runRaw`, `rig.runRawStream`) or the gateway, plus any call your code makes itself and reports with `rig.recordCall`. Nothing else is seen. Five things stay invisible or unattached unless you record them: (1) direct provider SDK calls, with or without a JSON schema; (2) streams you read from a provider client yourself; (3) a fallback your code makes after the raw lane refuses a `responseSchema` it cannot enforce (deepseek, deepinfra, fireworks and zai fail closed with `invariant_violation`); (4) calls made outside `run.scope` / `run.start`, which land on /inferences but on no run; (5) embeddings. A recorded call shows as "recorded · unverified": ModelRig neither dispatched nor validated it, and its tokens are the numbers you reported. Details and the console tells: https://modelrig.dev/not-captured.html.
+
+**The console is empty: five checks, in order.** If /runs (or /inferences) is empty for the org in the header badge, work these checks in order. The full tree is https://modelrig.dev/troubleshooting.html.
+
+```text
+1. npx modelrig doctor, from the environment your app runs in.
+   no export sink configured → this process does not see MODELRIG_API_KEY: set it, redeploy, open a new shell.
+   AUTH FAILED (401 / 403)   → the key is mistyped, revoked or not accepted: mint a key, set it, redeploy, open a new shell.
+2. The org doctor prints is not the org in the badge → wrong org: switch the console, or mint a key in the org you meant.
+3. /inferences has rows but /runs is empty → the calls are not inside run.scope / run.start.
+4. A run is missing a step or a cost → that call is not on a ModelRig lane (see not-captured).
+5. A doc describes something your install lacks → compare `npm ls modelrig` with the version stamp in modelrig.dev/llms.txt.
+```
+
+**After you change the key on a hosted worker.** A hosted process reads the environment it was started with. After you set or change MODELRIG_API_KEY, wait for the redeploy to finish, then open a new shell: a shell attached before the deploy still has the old environment. Confirm from inside it that the key resolves to the org you expect.
+
+```bash
+npx modelrig doctor --expect-org your-org-slug   # exits non-zero if the key belongs to another org
+```
+
 ## Capabilities (the full surface)
 
 - **Runs & projects** — the run → step → artifact graph at /runs, grouped by tag at /projects (the standard path above): https://modelrig.dev/instrumentation.html.
+- **Recorded calls (`rig.recordCall`, modelrig ≥ 0.11.0)** — a provider call your code makes itself (no lane fits) is reported after it returns: one row, priced at list for the served tier from the tokens you report, joined to the run/step, gradeable, badged "recorded · unverified" (ModelRig neither dispatched nor validated it), never in routed/conformance math: https://modelrig.dev/not-captured.html.
 - **Tenants & statements** — a `subject` tag or project-scoped key becomes a per-customer tenant with a derived statement (attempted, verified, billable, true cost; never content or another org's data): https://modelrig.dev/tenants.html.
 - **Published receipts** — a signed, login-free receipt of a bake-off or route at /r/<id>, verifiable by anyone at /v1/verify/<id>; internal names aliased, content never leaves: https://modelrig.dev/receipts.html.
 - **Analytics query API** — a self-describing, read-only query surface over your own telemetry (`GET /v1/analytics/meta`, `POST /v1/analytics/query`): an allowlisted SELECT-only grammar that returns metadata only (enums, numbers, hashes), never content: https://modelrig.dev/optimization-loop.html.
@@ -124,7 +198,6 @@ _The runtime routing model — the CANDIDATE ladder of one `rig.run` call, disti
 | id | capability | what is true today | tracking |
 |---|---|---|---|
 | B1 | Route-declared judge (hosted lane) | The SDK-lane `qualityGate` predicate (it rejects a schema-valid output as `quality_rejected`) ships; a route-DECLARED judge that runs on the hosted lane — a `judge:` block in the bundle with a rubric — is not built, and the bake-off-scoped `bakeoff.judge` (offline scoring) (which only measures value accuracy during a bake-off) is a separate SDK feature that never serves the hosted lane. | Route-declared judge — customer request on file (2026-08-21); follows the SDK predicate |
-| B2 | Structure on the raw lane | `runRaw` never validates or repairs; `responseFormat: "json_object"` shapes MIME, not schema, so `meta.validated` stays false — structure on the raw lane is ruled out by design, and the path is to graduate that step to a route. | ruled schema-free on the raw lane; re-request on file |
 | B6 | Run-level idempotency / dedupe key | Two identical `rig.run` calls dispatch twice; the only idempotency is the exporter's watermark. | — |
 
 ### Deferred
@@ -144,6 +217,7 @@ _The runtime routing model — the CANDIDATE ladder of one `rig.run` call, disti
 
 | id | capability | what is true today | tracking |
 |---|---|---|---|
+| B2 | Repair on the raw lane | `runRaw` validates a declared `responseSchema` (the provider's native structured-output directive plus a client-side Ajv check; a miss is a billed, terminal `content_invalid`) but never repairs, never retries, and never falls through — `meta.validated` stays false because no ladder stands behind the check, `responseFormat: "json_object"` shapes MIME only, and a schema miss you want recovered means graduating that step to a route. | [route-bundles](https://modelrig.dev/route-bundles.html) — raw-lane responseSchema (validate, never repair) |
 | B7 | Automatic model swap | No automated change to what serves a route happens without a bake-off and human approval (`modelrig swap execute <id> --approve`); you (or your agent) can change it directly at any time — instant, versioned, reversible. | [optimization-loop](https://modelrig.dev/optimization-loop.html) — human-approved swaps only |
 | B8 | Provider cache resource lifecycle | ModelRig passes your cache handle through and prices the hits; it never creates, refreshes, or deletes the resource — your heartbeat does. | [caching-lifecycle](https://modelrig.dev/caching-lifecycle.html) — who owns what |
 | B9 | Tool execution | ModelRig normalizes the tool-call protocol and returns `meta.toolCalls`; the caller runs the tool. | [route-bundles](https://modelrig.dev/route-bundles.html) — tools are normalized, never executed |
@@ -151,43 +225,48 @@ _The runtime routing model — the CANDIDATE ladder of one `rig.run` call, disti
 
 ## Build a route bundle correctly (for coding agents)
 
-A route bundle is one YAML file: `route`, `version`, `candidates`, `schema` (a JSON Schema file path or null), `prompt` (a system template path + declared `variables`), and `policy`. Five constraints decide whether it works — the first four fail loudly at load, the last fails SILENTLY:
+A route bundle is one YAML file: `route`, `version`, `candidates`, `schema` (a JSON Schema file path or null), `prompt` (a system template path + declared `variables`), `policy`, and optionally `output` (`json`, the default, or `text` for prose) and a per-call `prompt.user` template. Seven constraints decide whether it works — the first five fail loudly at load, the sixth is a documented delivery rule, the last fails SILENTLY:
 
 - Schema and prompt files must EXIST at the paths the bundle names; paths resolve relative to the bundle file. A bundle referencing a missing schema fails at load, not at run.
+- A route that returns PROSE or MARKDOWN (an editorial pass, a memo, a report) must declare `output: text` — the response is then returned verbatim as a string, never JSON-parsed, no repair rung. The default (`output: json`, even with `schema: null`) still requires parseable JSON and rejects prose as `content_invalid` with a fixHint naming this key. `output: text` cannot combine with `schema:`, `require: schema_conformant`, or `repair:` (load errors). The one declared prose check is `output: { kind: text, min_chars: N }`. See https://modelrig.dev/route-bundles.html#prose-and-markdown-output-output-text.
 - Every `{{variable}}` the prompt (or `grounding.query`) uses must be declared in `prompt.variables`. Undeclared references fail at load time.
+- A route that will be called with a GEMINI CACHE HANDLE (`rig.run(…, { cache: { key, provider: "gemini" } })`) must put the per-call delta in a `prompt.user` template (the user turn) and the shared prefix in the cache resource: Gemini forbids a system instruction next to `cachedContent`, so with a handle everything the route rendered is delivered AS THE USER TURN (never dropped; `meta.prompt_delivery` = `user+cache`). `prompt.system` may be omitted when `prompt.user` is declared; both share `prompt.variables`. The loader warns on a `cache:` route with a Gemini candidate, a non-empty `prompt.system` and no `prompt.user`. See https://modelrig.dev/caching-lifecycle.html#a-cache-handle-changes-where-the-template-is-delivered.
 - Candidates come from the PROBED registry above, never from memory — declared capability and probed behaviour differ, which is ModelRig's entire thesis.
 - `json: native` is a CLAIM ABOUT THE MODEL, not a preference: set it only for a model whose registry entry shows probed native strict enforcement (`structured_native`). Otherwise omit it and let the emulation ladder handle structure — a wrong `json: native` loads fine and then behaves unlike the code it replaced.
 - `MODELRIG_API_KEY` is OPTIONAL for LOCAL route-running: everything runs locally without it, and it only decides where telemetry lands (the ModelRig console). But observing your runs IN that console requires a free account + key — for that it is not optional.
 - `MODELRIG_API_KEY` gates the exporter PER PROCESS — set it on EVERY service, worker, and cron that constructs a rig; a process without it buffers to its own local SQLite and ships nothing. A multi-service deployment that sets the key on only the web tier silently loses every row a worker or cron produced.
-- Every pipeline execution is a RUN — the standard path, not an appendix: wrap it in `rig.artifacts.run.start` / `run.scope`, name one `step()` per model-call family, `artifact.save` the work products, and tag `subject` / `feature`. Acceptance is the run appearing on /runs with its steps. Inside a run context, BOTH `rig.run` and `rig.runRaw` record a ground-truth STEP (the per-run tree at /runs/[id]); name it with `stepKey` on either lane (explicit > `tags.step` > an auto `route#n` / `provider/model#n` key). An `artifact.save` with no `stepKey` joins the ambient (most recent) step. TAGS are the flat filter/rollup (/costs); the GRAPH is the per-run tree — they compose, and inside a run context the SDK stamps `tags.run_id` (the run's episodeKey, else its id) on every row of both lanes unless you passed your own — and stamps `tags.step` (the current step key) the same way (a value you pass always wins). The raw lane records steps since modelrig 0.5.0 (before that, a run that wrapped raw calls got an empty tree); raw steps are metadata only (no artifact content on the raw lane).
+- Every pipeline execution is a RUN — the standard path, not an appendix: wrap it in `rig.artifacts.run.start` / `run.scope`, name one `step()` per model-call family, `artifact.save` the work products, and tag `subject` / `feature`. Acceptance is the run appearing on /runs with its steps. Inside a run context, BOTH `rig.run` and `rig.runRaw` record a ground-truth STEP (the per-run tree at /runs/[id]); name it with `stepKey` on either lane (explicit > `tags.step` > an auto `route#n` / `provider/model#n` key). An `artifact.save` with no `stepKey` joins the ambient (most recent) step. TAGS are the flat filter/rollup (/costs); the GRAPH is the per-run tree — they compose, and inside a run context the SDK stamps `tags.run_id` (the run's episodeKey, else its id) and `tags.step` (the current step key) on every row of both lanes. `run_id` is RESERVED: don't set it yourself (a value you pass would override the stamp and split the run's rows from /runs) — put your own attempt id in a tag of your own, such as `pipeline_attempt_id`. Name the step with `stepKey`. The raw lane records steps since modelrig 0.5.0 (before that, a run that wrapped raw calls got an empty tree); raw steps are metadata only (no artifact content on the raw lane).
 
 ## Caching — pass your handle, own the TTL heartbeat
 
 - If the code you are migrating already caches with a provider (Gemini `cachedContents`, Anthropic `cache_control`, an OpenAI `prompt_cache_key`), carry it through the route — dropping it is a silent cost regression. A customer handle rides one optional field: `rig.run(task, { input, cache: { key, provider } })` (or `rig.runRaw({ …, apiKey, cache: { key } })` — runRaw is BYOK, pass your provider key); `provider` is required and the handle is applied only to that provider's candidates.
 - CRITICAL for long jobs: an explicit cache (Gemini `cachedContents`) has a TTL, and a multi-hour pipeline outlives it. ModelRig passes your handle through and prices the hits, but it NEVER creates, refreshes, or deletes the resource — your code must run the TTL heartbeat (refresh or recreate), by design. See [Caching lifecycle](https://modelrig.dev/caching-lifecycle.html) for the three regimes, what invalidates a cache, and prefix hygiene.
 - Route-level automatic caching is separate: set `cache: auto` on the route and ModelRig stamps the per-provider directive; a miss-streak detector exists but is UNWIRED (not yet connected to the monitor), so nothing yet alerts on a route that stopped caching. That handles Anthropic markers and prefix caching — the customer handle above is only for provider-native EXPLICIT resources you own.
-- The Lane-B `rig.runRaw` seam also forwards `grounding: { mode: "native" }` (native provider web grounding), `serviceTier: standard|flex|priority`, `reasoning: { level: minimal|low|medium|high }`, and `responseFormat: "json_object"`. Each is additive (absent ⇒ byte-identical); a directive a provider cannot honor FAILS CLOSED (`invariant_violation`, pre-dispatch), never a silent drop — which provider honors which knob is the matrix below. A grounded raw step that also passes `cache.key` must have the `googleSearch` tool baked into the cache resource at creation.
+- The Lane-B `rig.runRaw` seam also forwards `grounding: { mode: "native" }` (native provider web grounding), `serviceTier: standard|flex|priority`, `reasoning: { level: minimal|low|medium|high }`, `responseFormat: "json_object"` (mime-shaping only), and `responseSchema: <JSON Schema object>` (the provider's NATIVE structured-output directive PLUS a client-side Ajv check — a miss is a billed, terminal `content_invalid`, never repaired or retried; `meta.schema_sha` on the row; declare one of responseFormat/responseSchema). Each is additive (absent ⇒ byte-identical); a directive a provider cannot honor FAILS CLOSED (`invariant_violation`, pre-dispatch), never a silent drop — which provider honors which knob is the matrix below. A grounded raw step that also passes `cache.key` must have the `googleSearch` tool baked into the cache resource at creation; a schema composes with the handle.
 
 ## Raw-lane provider × knob support (rig.runRaw)
 
-_Since 0.4.0: `reasoning` beyond gemini, `responseFormat`, and the DeepInfra/Fireworks `prompt_cache_key` mapping (grok native grounding is fail-closed: xAI retired Live Search; tracked as CE-9b). The openai/grok prompt-cache hints were already true on 0.3.0._
+_Since 0.4.0: `reasoning` beyond gemini, `responseFormat`, and the DeepInfra/Fireworks `prompt_cache_key` mapping. **RELEASED:** native `web_search` grounding on openai AND grok via the Responses API — each cleared its own live recency+citations+price gate on 2026-09-09 (openai $0.01/call surcharge; grok $0.005 per CALL — $5/1k calls, a per-call model, retrieved content billed separately as input tokens; grok replaces the retired xAI Live Search surface, and its gate run scored 15/15 recency, 100% citation presence, avg 3.80 cites/response). The openai/grok prompt-cache hints were already true on 0.3.0._
 
 The raw lane forwards these provider knobs; a knob a provider cannot honor FAILS CLOSED pre-dispatch (`invariant_violation`) — discoverable here, never a silent drop:
 
-| Provider | grounding | reasoning | responseFormat | cache | serviceTier |
-|---|---|---|---|---|---|
-| `gemini` | native — Google Search (`googleSearch` tool) | `level` → `thinkingConfig.thinkingLevel`, thinking-capable models only (see `GEMINI_THINKING_CAPABLE_MODELS`) | `responseMimeType: application/json` (mime-shaping only — no schema, `validated` stays false) | `cache.key` = a `cachedContent` resource handle (customer-owned lifecycle) | `flex` / `standard` / `priority` honored |
-| `openai` | fail-closed | `level` → `reasoning_effort` (1:1); a non-reasoning model's rejection is classified teachably | `response_format: { type: json_object }` | `cache.key` → `prompt_cache_key`; `ttlSeconds ≥ 86400` → `prompt_cache_retention: 24h` | `flex` (allowlist) / `priority`; flex→standard is a customer-side degrade (§3.2) |
-| `deepseek` | fail-closed | no effort control — reasoning is model selection (`deepseek-reasoner`) | `response_format: { type: json_object }` — the prompt must contain the word "JSON" (caller's responsibility on the raw lane) | automatic prefix cache — the key is not used | no tiers — always `standard` |
-| `anthropic` | fail-closed | extended thinking is not wired on the raw lane (future work) | fail-closed — no json_object equivalent (structured output is a forced tool call) | prefix caching via `cache_control` markers — the key is not used | no tiers — always `standard` |
-| `grok` | fail-closed — xAI retired Live Search (HTTP 410, 2026-08-21); native `web_search` needs the Responses API, tracked as CE-9b | coarsened (disclosed): `minimal,low → "low"`; `medium,high → "high"` → `reasoning_effort` | `response_format: { type: json_object }` | `cache.key` → `prompt_cache_key` (routing hint) | no tiers — always `standard` |
-| `deepinfra` | fail-closed | `level` → `reasoning_effort` (1:1); a non-reasoning model's rejection is classified teachably | `response_format: { type: json_object }` | `cache.key` → `prompt_cache_key` (routing hint) | no tiers — always `standard` |
-| `fireworks` | fail-closed | `level` → `reasoning_effort` (1:1); a non-reasoning model's rejection is classified teachably | `response_format: { type: json_object }` | `cache.key` → `prompt_cache_key` (routing hint; caching is automatic host-side) | no tiers — always `standard` |
+| Provider | grounding | reasoning | responseFormat | responseSchema | cache | serviceTier | destination |
+|---|---|---|---|---|---|---|---|
+| `gemini` | native — Google Search (`googleSearch` tool) | `level` → `thinkingConfig.thinkingLevel`, thinking-capable models only (see `GEMINI_THINKING_CAPABLE_MODELS`) | `responseMimeType: application/json` (mime-shaping only — no schema, `validated` stays false) | `responseJsonSchema` + `responseMimeType: application/json` (native); output Ajv-checked, a miss is `content_invalid` | `cache.key` = a `cachedContent` resource handle (customer-owned lifecycle) | `flex` / `standard` / `priority` honored | `direct` only — vendor key (BYOK / configured) |
+| `openai` | native — `web_search` tool (Responses API) — released (live gate passed 2026-09-09) | `level` → `reasoning_effort` (1:1); a non-reasoning model's rejection is classified teachably | `response_format: { type: json_object }` | `response_format: { type: json_schema, strict: true }` (native; strict needs an object root — a non-object root is warned pre-dispatch); output Ajv-checked | `cache.key` → `prompt_cache_key`; `ttlSeconds ≥ 86400` → `prompt_cache_retention: 24h` | `flex` (allowlist) / `priority`; flex→standard is a customer-side degrade (§3.2) | `direct` only — vendor key (BYOK / configured) |
+| `deepseek` | fail-closed | no effort control — reasoning is model selection (`deepseek-reasoner`) | `response_format: { type: json_object }` — the prompt must contain the word "JSON" (caller's responsibility on the raw lane) | fail-closed — json_object only; a schema would be silently dropped | automatic prefix cache — the key is not used | no tiers — always `standard` | `direct` only — vendor key (BYOK / configured) |
+| `anthropic` | fail-closed | extended thinking is not wired on the raw lane (future work) | fail-closed — no json_object equivalent (structured output is a forced tool call) | forced tool call carrying the schema as `input_schema` (strict-first via the structured-outputs beta, advisory on a strict compile rejection); output Ajv-checked | prefix caching via `cache_control` markers — the key is not used | no tiers — always `standard` | `direct` only — vendor key (BYOK / configured) |
+| `grok` | native — `web_search` tool (xAI Agent Tools / Responses API); replaces retired Live Search — released (live gate passed 2026-09-09) | coarsened (disclosed): `minimal,low → "low"`; `medium,high → "high"` → `reasoning_effort` | `response_format: { type: json_object }` | `response_format: { type: json_schema, strict: true }` (native); output Ajv-checked | `cache.key` → `prompt_cache_key` (routing hint) | no tiers — always `standard` | `direct` only — vendor key (BYOK / configured) |
+| `deepinfra` | fail-closed | `level` → `reasoning_effort` (1:1); a non-reasoning model's rejection is classified teachably | `response_format: { type: json_object }` | fail-closed — the raw compat profile has no probed `structured_native`; the schema would degrade to json_object + a prompt guard | `cache.key` → `prompt_cache_key` (routing hint) | no tiers — always `standard` | `direct` · `modelrig-served` — ModelRig-owned key (managed serving RELEASED — GA, gated by `config.managedServing`, default off) |
+| `fireworks` | fail-closed | `level` → `reasoning_effort` (1:1); a non-reasoning model's rejection is classified teachably | `response_format: { type: json_object }` | fail-closed — the raw compat profile has no probed `structured_native`; the schema would degrade to json_object + a prompt guard | `cache.key` → `prompt_cache_key` (routing hint; caching is automatic host-side) | no tiers — always `standard` | `direct` · `modelrig-served` — ModelRig-owned key (managed serving RELEASED — GA, gated by `config.managedServing`, default off) |
+| `zai` | fail-closed — native GLM web_search wired in B4b | `level` → `reasoning_effort` (1:1); a non-reasoning model's rejection is classified teachably | response_format json_object | fail-closed — the raw compat profile has no probed `structured_native`; the schema would degrade to json_object + a prompt guard | `cache.key` → `prompt_cache_key` (routing hint) | no tiers — always `standard` | `direct` only — vendor key (BYOK / configured) |
 
 **Fail-closed is discoverable, not a surprise.** A knob a provider cannot honor throws `RigFailureError` `invariant_violation` PRE-DISPATCH (no meter, no provider call, no telemetry row) — read this table before you call, not after.
 **reasoning has NO per-model allowlist outside gemini.** openai/deepinfra/fireworks forward `level` verbatim and let the provider enforce; a rejection surfaces as a classified failure that names the fix. grok coarsens (disclosed above). deepseek reasoning is model selection (`deepseek-reasoner`); anthropic extended thinking is unwired.
 **responseFormat is mime-shaping, not schema enforcement.** `json_object` forces syntactic JSON only — the raw lane still never validates or repairs, and `meta.validated` stays `false` (F4).
+**responseSchema validates, never repairs.** A JSON Schema on `rig.runRaw` is forwarded as the provider's NATIVE structured-output directive AND checked client-side by the same Ajv the routed lane uses: a miss is thrown as `content_invalid` (a billed row with that class, `fixHint` naming the first errors) — the raw lane never repairs, never retries, never falls through, and `meta.validated` stays `false` (no ladder stands behind it). The row's `meta.schema_sha` is the sha256 of the canonical (sorted-key) schema JSON, so declared-vs-served drift is queryable. Declare ONE of `responseFormat` / `responseSchema`, not both.
 **§3.2 flex degrade is customer-side.** ModelRig does not replicate the gemini direct-path infra-retry wrapper on the raw lane; under `flex` a capacity rejection surfaces classified (`capacity_shed`) for your own `→ standard` retry ladder — a NAMED difference for your migration record, not a silent one.
+**`destination` (managed serving) is RELEASED (GA).** The serving-destination column names which providers *can* be `modelrig-served` (reached on ModelRig's own key) vs `direct` only. Managed serving is gated behind a config flag (`config.managedServing`, default off, set in code — not an env var); it defaults off, so until you enable it every call is `direct` (ABSENT ⇒ byte-identical).
 
 ## Raw-lane defaults (rig.runRaw)
 
@@ -196,13 +275,14 @@ What `rig.runRaw` sends when you omit a knob. `timeoutMs` is tier-aware since 0.
 | Knob | Default | Note |
 |---|---|---|
 | `timeoutMs` | 300 s (standard, priority) · 900 s (flex) | tier-aware wall-clock deadline; an explicit `timeoutMs` always wins, and a `timeout` failure carries a `fixHint` naming the tier + budget |
-| `serviceTier` | standard | forwarded to the adapter; `meta.servedTier` reports what actually served. On `flex`, set `timeoutMs` in minutes (default 900 s) |
+| `serviceTier` | standard | forwarded to the adapter; `meta.servedTier` reports what actually served, and the cost row is priced at the SERVED tier (gemini flex = 0.5× input + output, cache read NOT discounted; priority = 1.8×). On `flex`, set `timeoutMs` in minutes (default 900 s) |
 | `temperature` | adapter default — not sent | absent ⇒ no `temperature` on the request (byte-identical dispatch) |
 | `topP` | adapter default — not sent | absent ⇒ no `topP` on the request (byte-identical dispatch) |
 | `maxOutputTokens` | adapter default — not sent | absent ⇒ no output-token cap on the request (byte-identical dispatch) |
 | `grounding` | absent ⇒ byte-identical | native provider grounding; provider support per the raw-lane knob matrix |
 | `reasoning` | absent ⇒ byte-identical | reasoning/thinking effort; provider support per the raw-lane knob matrix |
 | `responseFormat` | absent ⇒ byte-identical | syntactic-JSON forcing (mime-shaping only); provider support per the raw-lane knob matrix |
+| `responseSchema` | absent ⇒ byte-identical (no schema sent, no validation) | JSON Schema forwarded natively AND Ajv-checked client-side — a miss is a billed, terminal `content_invalid` (never repaired); `meta.schema_sha` on the row; provider support per the raw-lane knob matrix |
 | `cache` | none | customer cache handle passed through verbatim when supplied; ModelRig never creates, refreshes, or deletes the resource |
 | `tags` | none | `lane=raw` and `rung=primary` are stamped by the SDK and cannot be overridden by a caller tag |
 | `tools / toolChoice` | none | absent ⇒ no tools declared; on the raw lane a grounding-originated `functionCall` part is NOT a tool-call turn |

package/docs/managed-serving.md

@@ -0,0 +1,150 @@
+# Managed serving — `destination: modelrig-served`
+
+Serve a route's model on ModelRig's own credentials instead of yours. One less
+provider key to hold; the same route bundle, the same validate → repair →
+fall-through pipeline, the same per-call telemetry — served through the hosted
+gateway and paid from your organization's prepaid balance.
+
+**The honest default is `direct`.** A route or run that declares no
+`destination` is served exactly as today: your own provider key, ModelRig not in
+the credential path, byte-identical behaviour. Nothing in this page changes a
+route you have not opted in.
+
+Requires `modelrig` **0.10.0 or newer** — the first published version that
+carries the hosted serving transport. On an older package a `modelrig-served`
+run is served through the local seam on whichever key the adapter already holds,
+so upgrade before you rely on the keyless path.
+
+## What "served" means
+
+| | `destination: direct` (default) | `destination: modelrig-served` |
+|---|---|---|
+| Who calls the provider | your process, with your key | the hosted gateway, with ModelRig's key |
+| What your process sends | the provider request | your `rig_sk_` key + the route slug + input — **never a provider key** |
+| What you pay | your provider bill | provider list cost plus the flat fee, drawn from your prepaid balance at serve time |
+| Telemetry row | written locally, exported if configured | written server-side (server-measured cost); `meta.inferenceId` points at it |
+| Tag on the row | `destination: direct` | `destination: modelrig-served` |
+
+Which providers *can* be served is a fact in the capability table — the
+`destination` column in [Route bundles → provider × knob support](route-bundles.md#raw-lane-provider--knob-support-rigrunraw)
+(and in `llms.txt`). A provider whose cell reads `direct` only cannot be
+`modelrig-served`; declaring it fails closed before any call.
+
+## Five steps
+
+### 1. Declare the destination on the route (or the run)
+
+```yaml
+# modelrig/routes/example.support_summarize.yaml
+route: example.support_summarize
+version: 3
+destination: modelrig-served       # absent ⇒ direct (byte-identical)
+candidates:
+  - { provider: <a served-capable provider>, model: <model> }
+# …schema, prompt, policy unchanged
+```
+
+A per-run override wins over the route:
+
+```ts
+await rig.run("example.support_summarize", {
+  input: { ticket },
+  destination: "modelrig-served",   // this run only
+});
+```
+
+Precedence: `RunOptions.destination` → route `destination` → `direct`.
+
+### 2. Enable managed serving in code
+
+```ts
+import { createRig, loadConfigFromEnv } from "modelrig";
+
+const rig = createRig({ ...loadConfigFromEnv(), managedServing: true });
+```
+
+`managedServing` is a **config field set in code, never an environment
+variable**. It defaults to `false`: with it off, a `modelrig-served` route
+throws a teaching `invariant_violation` *before* any provider call rather than
+silently serving `direct`. This is the per-process switch; the per-organization
+switch is step 4.
+
+### 3. Mint a key with the `serve` scope
+
+Managed serving spends money, so it is a **deliberate** grant: in the console
+(Keys → new key) tick `serve`, and set that key as `MODELRIG_API_KEY` in the
+process that runs the rig. The SDK sends this `rig_sk_` key as the only
+credential on a served call. A key without `serve` is refused with a 403 that
+names the scope.
+
+### 4. Turn managed serving on for your organization
+
+An **owner** flips it in the console — **Account settings → Managed serving**
+(off for every new organization). Or from a coding agent / script, through the
+settings API with an `org-settings`-scoped key:
+
+```http
+PATCH /v1/orgs/<your-org-id>/settings
+{ "managed_serving_enabled": true }
+```
+
+The server's owner-only gate decides; a member or admin is refused, and the
+setting applies to the **next** served call — no redeploy.
+
+### 5. Fund the prepaid balance
+
+Served calls are debited at serve time: the server-measured provider cost plus
+the flat fee, as two ledger entries anchored to the inference id (idempotent —
+a retry never charges twice). Before dispatch the gateway checks that a
+conservative reservation is available; otherwise it refuses with a 402 and
+nothing is served. Top up in the console (Billing). A `direct` route never
+needs a balance.
+
+## What the refusals teach
+
+Every refusal is a `RigFailureError` of class `invariant_violation` — terminal,
+pre-dispatch where possible, and never a silent fall back to `direct`. The
+`fixHint` on the error is the text below.
+
+| Status | Means | `fixHint` says |
+|---|---|---|
+| (local, before any call) | `managedServing` is off | "managed serving is not enabled — set `managedServing: true` in your rig config … otherwise remove `destination` or set it to `direct`." |
+| (local, before any call) | the resolved candidate cannot be served | "provider … cannot be modelrig-served; served providers: …. Declare a served-capable candidate, or set `destination: direct`." |
+| **401** | the `rig_sk_` key was rejected | "the `rig_sk_` control-plane key (MODELRIG_API_KEY) was not accepted. Check the key and that it belongs to the org you expect, then retry." |
+| **402** | no / insufficient prepaid balance | "your organization has no prepaid managed-serving balance. Top up your balance in the console, or serve this route with `destination: direct` (your own provider key)." Server side: "each managed call draws the server-measured provider cost + 2% fee. Add funds (at least … must be available to start a call), then retry." |
+| **403** | the key lacks `serve`, **or** the organization has not turned managed serving on | "this organization/key is not entitled to managed serving. Enable managed serving for your org in the console, or serve this route with `destination: direct`." Server side the two cases are distinct: "this key does not carry the `serve` scope" vs "this organization is not provisioned for managed serving — an OWNER … turns it on (Account settings → Managed serving)". |
+| **404** | the route slug is not mirrored for your organization | "deploy that route from your repo so its bundle syncs to the mirror, then retry — the hosted lane serves only your own organization's routes." |
+| **502** | the entitlement or balance could not be read | "refused on purpose (fail-closed) rather than served on an unknown entitlement / without confirming funds; retry shortly, and check control-plane health if it persists." |
+| **503** | the call ran but its charge could not be anchored, or the hosted lane is misconfigured | "refused on purpose (fail-closed) rather than billed against a shared idempotency key — retry shortly." |
+
+A 404 here is a routing fact, not a permissions oracle: the hosted lane resolves
+slugs **only inside the calling key's organization**, so another organization's
+route is simply "not found".
+
+## What you see on the row
+
+A served call's inference row carries `destination: modelrig-served`, the
+provider and model that actually served it, the served tier, the
+server-measured cost (which is what the ledger drew), and the inference id the
+charge is anchored to. It is the same row shape as every other call — the
+console, the analytics surface, exports and tenant statements all read it
+unchanged — so "which calls did ModelRig serve for me, and what did they cost"
+is one filter on the `destination` tag.
+
+## Data posture
+
+On the served path your request reaches the serving provider on ModelRig's
+credentials, which makes that provider ModelRig's subprocessor for the request
+— the published security page states the posture, and the named list is part
+of the security-questionnaire pack available on request. Regulated or PHI data
+stays on `direct` (or managed custody) and is not sent through the served path
+until the subprocessor agreement chain is confirmed. Content custody is a
+separate axis with its own account setting (see
+[Artifact content custody](content-custody.md)); the serving destination never
+changes what is stored.
+
+## See also
+
+- [Route bundles](route-bundles.md) — the `destination` field and the provider × knob table.
+- [Routing & reliability](routing-reliability.md) — what fails closed and why.
+- [Quickstart](quickstart.md) — the `direct` path everything above is additive to.