modelrig 0.9.0 → 0.10.0

package/docs/mcp-oracle.md

@@ -58,7 +58,7 @@ on purpose.
 | Tool | Does | Never does |
 |---|---|---|
 | `get_proposals` | Lists open proposals for your routes — each carries an `evidence.change_spec` (the machine-readable diff + `apply_instructions` a coding agent applies) plus its evidence and savings. | Change anything. |
-| `create_route` | Writes a **draft** route bundle — YAML, schema, prompt — into your drafts directory, candidates seeded from the registry, your current model first. | Edit your source, register a route, overwrite an existing draft. |
+| `create_route` | Writes a **draft** route bundle — YAML, schema, prompt — into your drafts directory, candidates seeded from the registry, your current model first. `output_kind: text` drafts a prose route (`output: text`, no schema); `user_prompt` adds a `prompt.user` per-call user turn. | Edit your source, register a route, overwrite an existing draft. |
 | `test_route` | Makes **one** real billed call through a route, under a fresh budget envelope (default $1). | Run unbounded. |
 | `run_bakeoff` | Replays captured inputs through challenger variants, each arm under its own envelope (default $2). | Switch what serves your route. |
 | `run_optimizer` | Runs **one** explicit optimizer cycle for a route — reflect, score candidates on your golden eval cases, file a proposal carrying a `change_spec`. Pass `{ estimate: true }` first for the cost preview. Needs the `oracle-act` scope. | Apply anything; run on a schedule (there is none). |
@@ -66,7 +66,7 @@ on purpose.
 | `execute_swap` | Records an approved swap and **returns** the route-YAML diff to apply via a PR. Needs the `decision` scope. | Write any file; commit to your repo. |
 | `record_grade` | Attaches a 0–1 grade (with an optional comment) to one inference or a whole run — the signal the next cycle learns from. Needs the `grade` scope on the HTTP path. | Spend a billed call; guess attribution for an unknown subject. |
 | `get_task_settings` / `set_task_settings` | Reads / writes a task's governance settings and its **grading guide** (the rubric the task's grader is taught from). `set` needs the `task-settings` scope. | Change route config (the pass threshold lives in the route, and is refused here). |
-| `get_call_config` | Reads a route's **current live** call-config — its version, mode, and the model(s) it serves. Read-only. | Change anything. |
+| `get_call_config` | Reads a route's **current live** call-config — its version, mode, the model(s) it serves, the `effective` model + why (pin / YAML default), and any `drift`. Read-only. | Change anything. |
 | `set_call_config` | **Sets what serves a route right now** — pins a model or starts a live A/B — on the human's behalf. A real, versioned control-plane change. | Bypass the eligibility gate or the `route-config` scope; imply it is a draft. |
 | `rollback_call_config` | Restores a prior call-config version (re-appended as a new version — history is never deleted). | Delete history; escape the scope check. |
 
@@ -84,6 +84,55 @@ This is the half of the pivot where the agent sets routes *for the human*.
 call-config tools deliberately **do**: they change what serves live traffic right
 now, on the human's behalf, and say so unmistakably.
 
+### Point a scoped key at the control plane (once)
+
+The four read tools work with no account. The call-config tools do **not**: a
+read needs a valid `rig_sk_` key, and a **write** (`set_call_config` /
+`rollback_call_config`) needs that key to carry the **`route-config`** scope. Give
+the MCP server both the key and the host so the tools can reach `/v1`:
+
+```jsonc
+{
+  "mcpServers": {
+    "modelrig": {
+      "command": "npx",
+      "args": ["modelrig-oracle"],
+      "env": {
+        // A rig_sk_ key minted at app.modelrig.ai (/keys). To FLIP a route it
+        // must carry the `route-config` scope; a read-only key still reads.
+        "MODELRIG_API_KEY": "rig_sk_…",
+        // The control plane the oracle's tools call. Omit to use the hosted
+        // default (https://api.modelrig.ai). The oracle reads MODELRIG_INGEST_URL
+        // ONLY — MODELRIG_SERVER_URL is an app-side var and is NOT honored here.
+        "MODELRIG_INGEST_URL": "https://api.modelrig.ai"
+      }
+    }
+  }
+}
+```
+
+A key without `route-config` authenticates fine and reads, then a write returns a
+teaching **403** naming the missing scope — mint or rotate a key with it, or set
+the config in the console.
+
+### The flip, end to end
+
+1. **Read the current config.** `get_call_config(route)` → the live `version`,
+   `mode`, and model(s) serving the route this instant. `version: 0` means no
+   override (the route resolves to its deployed bundle default).
+2. **Set the new model.** `set_call_config({ route, mode: "pin", provider, model })`
+   (shape below). The response names the new **version** and a rollback hint.
+3. **It takes effect at serve time — no redeploy.** The SDK reads the route's
+   config **just-before-call**, merges the pin over the deployed bundle, and
+   serves it. It is **fail-open**: on any control-plane error the last-known-good
+   (else the deployed bundle) serves, and a route with **no override resolves
+   byte-identical** to today. The change lands on the route's *next* request once
+   the resolver's short cache refreshes (TTL ~30–60s). (Serving requires the app
+   to overlay call-config on the route — see
+   [Change your route's model live](quickstart.md#change-your-routes-model-live-no-redeploy).)
+4. **Undo when you want.** `rollback_call_config({ route, toVersion })` re-appends a
+   prior version as a new one (history is never deleted).
+
 | Tool | Endpoint | Scope |
 |---|---|---|
 | `get_call_config` | `GET /v1/routes/:route/call-config` | any org-scoped key — a read needs none special |
@@ -96,6 +145,30 @@ Version `0` means there is no override yet — the route resolves to its deploye
 (mirrored) bundle default. History (audit + rollback targets) is at
 `GET /v1/routes/:route/call-config/history`.
 
+**It also answers "what will this route serve, and why?"** (RV-1). The tool reads
+`GET /v1/routes/:route/call-config?include=effective` and returns:
+
+- `effective` — `{ source, provider, model, version, since }`, where `source` is
+  `pin` (a call-config pin serves; `version` = the call-config version),
+  `experiment` (a live A/B — no single model), `deployed_default` (no override; the
+  app's YAML default = the registered route's first candidate; `version` = the YAML
+  route version), or `unknown` (no deployment has registered the route in your org).
+  `serving` phrases it in one line.
+- `drift` — non-null only when a pin is set but recent calls on the route (last 24h,
+  from 5 minutes after the pin, ≤500 sampled) served a **different** model:
+  `{ servedProvider, servedModel, calls, lastSeen, pinnedCalls, windowStart }`, plus a
+  `drift_warning` sentence. It means the app's resolver is failing open — check its SDK
+  version, its `MODELRIG_API_KEY`, and that the call path resolves call-config at
+  serve time. Setting the pin again will not fix drift; the app has to honor it.
+
+Routes appear here before their first call: a rig created with routes and a
+control-plane key registers them on startup — metadata plus the declared bundle
+(prompt template, schema, policy), `ingest` scope only. That registered bundle is
+what `set_call_config` checks a pin against, so **pins work for api-mode apps once
+their routes register**; before that, a pin is refused with a teaching 422 ("no
+servable bundle in your organization") — start the app (with an SDK that has
+RV-1) and retry.
+
 **Pin a model:**
 
 ```jsonc

package/docs/migration-playbook.md

@@ -213,8 +213,9 @@ regression). Silent is the only forbidden outcome.
   `dimensions[].key` in `rig.yaml` (tag-safe `[A-Za-z0-9_]{1,64}`) so the
   console can attribute cost by it. A `required: true` dimension missing from a
   run's tags **warns once per process** (and under-attributes that run) — it
-  is never rejected. An example that shows `tags: { run_id }` assumes a
-  `run_id` dimension exists.
+  is never rejected. Don't put `run_id` in your tags: inside a run the SDK stamps
+  it (it is reserved — see the
+  [reserved tag keys](instrumentation.md#reserved-tag-keys-the-one-list)).
 - **`result.output` is already parsed and schema-validated** — delete the old
   call site's `JSON.parse` and fence-stripping rather than keeping both.
 - **Routes resolve from `./modelrig/routes` relative to the process CWD.** In a
@@ -391,7 +392,7 @@ through `rig.runRaw` without a `run.start` around it records inferences but no
 run — `/runs` stays empty and `/projects` shows "(no run)". Open the run context
 around each pipeline execution (`rig.artifacts.run.start({ pipeline, episodeKey })`
 … `run.end()`); inside it the SDK names the step and stamps the `run_id` tag —
-and the `step` tag too (a value you pass always wins) — you tag `subject` /
+and the `step` tag too (`run_id` is reserved: never set it yourself) — you tag `subject` /
 `feature` yourself. Do not declare a
 migration done until one real execution shows a run with steps on `/runs`.
 
@@ -434,7 +435,7 @@ Because this is behaviour-affecting, the agent **proposes, never applies**:
    keeps the diff inside the customer's codebase legible — a product surface.
 5. **A human merges.** The skill's autonomy ends at a green report and an open PR.
 
-### Replaced-call disposition (RULED, Matt 2026-08-16): DELETE the original, never comment it out
+### Replaced-call disposition: DELETE the original, never comment it out
 
 Rollback is git-native and the skill makes it explicit:
 

package/docs/quickstart.md

@@ -1,5 +1,7 @@
 # ModelRig quickstart — see, prove, and save on every model call
 
+**The question this page answers: how do I get from nothing to my first run on `/runs`, with its steps and artifacts, in about ten minutes?**
+
 ModelRig is the operating layer for your AI workstream. Each LLM task becomes a
 **versioned route file** (prompt template + JSON schema + candidate models +
 policy) that you call with one line — `rig.run("task.name", {input, tags})` —
@@ -15,22 +17,33 @@ and three things happen at once:
 - **Save** — a winning candidate is a change to your YAML you review; nothing
   swaps a model on its own, and your routes are always YAML in your git.
 
-The rest of this page is Step 0 (two minutes, once), then the two ways to
-instrument your project — point your coding agent at it, or do it by hand.
+The path is the same whoever does the work: **mint a key → install → confirm the
+org → define a route → wrap one pipeline execution in a run → see it on `/runs`.**
+Step 0 is yours (two minutes, once); after that, point your coding agent at this
+page or follow the steps by hand. Already have LLM calls you only want to *watch*
+first? [Choosing a lane](https://modelrig.dev/choosing-a-lane.html) shows the observe path, which skips
+the route.
 
 ## Step 0 — create your org and key (two minutes, human-only)
 
 Account setup stays human: your coding agent never creates accounts, signs in,
-or holds credentials. Once, up front:
+or holds credentials. Once, up front, sign up and create your organization at
+[app.modelrig.ai](https://app.modelrig.ai) (email and an org name is the whole
+form). Then:
+
+<!-- BLOCK:KEY -->
+**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.
 
-1. Sign up and create your organization at
-   [app.modelrig.ai](https://app.modelrig.ai) — email and an org name is the
-   whole form.
-2. Issue an API key in the console (the `rig_sk_…` value is shown once — copy it).
-3. Export it beside your provider keys: `MODELRIG_API_KEY=rig_sk_…`.
+```bash
+# Wherever your app reads configuration: .env.local, your platform's env vars, a secret manager. Never in code.
+MODELRIG_API_KEY=rig_sk_…
+```
+<!-- /BLOCK:KEY -->
 
 That key is the only ModelRig credential your app ever holds — never a database
-URL, never a service-role key. Provider keys never leave your process.
+URL, never a service-role key. Provider keys never leave your process. Which org
+a key belongs to, and how the console chooses the org it shows you, is
+[Orgs and keys](https://modelrig.dev/orgs-and-keys.html).
 
 **No account needed for the open lane:** with only your provider keys set,
 routes, probes and telemetry run entirely on your machine — the hosted console
@@ -51,33 +64,18 @@ Same flat 2% margin either way; your negotiated provider discounts stay yours.
 
 ## Point your coding agent at it
 
-The fastest migration is the one your agent performs. From inside your project,
-paste this into Claude Code, Codex, or Cursor:
+The fastest migration is the one your agent performs. Paste the migration prompt
+from [modelrig.ai/get-started](https://modelrig.ai/get-started) (the console's
+`/setup` page carries the same prompt) into Claude Code, Codex, or Cursor from
+inside your project. It is the maintained version: it starts the agent at the
+bottom of the [autonomy ladder](migration-playbook.md), has it confirm the org
+your key exports to, wrap each pipeline execution in a run, and stop for your
+approval at every checkpoint.
 
-```
-Migrate this project to ModelRig routes (https://modelrig.dev).
-
-0. If MODELRIG_API_KEY is not set and I want hosted telemetry, STOP and ask me
-   to create an org and issue a rig_sk_ key at https://app.modelrig.ai. Never
-   create accounts, sign in, or handle credentials yourself. Without the key,
-   proceed in local-only mode — that is fully supported.
-1. Read https://modelrig.dev/quickstart.html and
-   https://modelrig.dev/route-bundles.html.
-2. Find every place this codebase calls an LLM API directly.
-3. For each call site, define a route bundle YAML (schema, candidate models,
-   policy, prompt template) and replace the direct call with
-   rig.run("<route.name>"). Keep prompt and schema semantics unchanged.
-4. Before naming any model capability, check the probed registry — declared
-   flags and probed behavior differ; trust the probed layer.
-5. Run the project's existing tests and report every file you changed.
-```
-
-Your agent reads the docs, finds your LLM call sites, and turns them into
-routes. It **won't** create accounts, sign in, or touch your API keys (those
-stay in the environment you set in Step 0), and it swaps call sites to
-`rig.run()` without changing prompt or schema semantics — same model, human-
-reviewed. The full autonomy ladder and same-model guarantees are in the
-[migration playbook](migration-playbook.md).
+Your agent reads the docs, finds your LLM call sites, and wires them in. It
+**won't** create accounts, sign in, or touch your API keys (those stay in the
+environment you set in Step 0), and when it replaces a call site with `rig.run()`
+it keeps prompt and schema semantics unchanged — same model, human-reviewed.
 
 ## Or set it up by hand
 
@@ -87,14 +85,15 @@ reviewed. The full autonomy ladder and same-model guarantees are in the
 pnpm add modelrig      # or npm i modelrig — Node >= 20
 ```
 
-It installs a native module (`better-sqlite3`) — prebuilt for macOS/Linux on
-x64/arm64; an unusual platform compiles it and needs a C++ toolchain.
+It installs a native module (`better-sqlite3`) from a prebuilt binary on
+macOS and Linux (x64/arm64); any other platform compiles it at install time and
+needs a C++ toolchain.
 
-**Deploying:** `modelrig` installs prebuilt (no separate build step), but it
-needs a **Node** runtime (not Edge/Workers), and if your deploy bundles server
-code you must mark it external — Next.js `serverExternalPackages: ['modelrig']`,
-esbuild `--external:better-sqlite3`, webpack `externals`. Set `MODELRIG_API_KEY`
-on every service, worker, and cron that runs a rig.
+**Deploying:** `modelrig` needs a **Node** runtime (not Edge/Workers), and if
+your deploy bundles server code you must mark it external — Next.js
+`serverExternalPackages: ['modelrig']`, esbuild `--external:better-sqlite3`,
+webpack `externals`. Set `MODELRIG_API_KEY` on every service, worker, and cron
+that runs a rig; hosted-platform specifics are in [Deploying](https://modelrig.dev/deploying.html).
 
 ```ts
 import { createRig, loadConfigFromEnv } from "modelrig";
@@ -117,12 +116,21 @@ MODELRIG_TELEMETRY_DB=./.modelrig/telemetry.db # default
 MODELRIG_ENVELOPE_BUDGET_USD=25                # default envelope budget
 ```
 
-Provider keys never leave your process on either lane. A `rig_sk_` key is issued
-in the console at [app.modelrig.ai](https://app.modelrig.ai) and is the only
-ModelRig credential your app ever holds — never a database URL, never a
-service-role key.
+### 2. Confirm the org
 
-### 2. Define a route bundle
+<!-- 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 -->
+
+### 3. Define a route bundle
 
 One YAML file per route under `modelrig/routes/`:
 
@@ -175,15 +183,15 @@ types allowed, and `format` is annotation-only — it is not asserted (an
 `email`/`date-time` format is documentation, not a constraint). Author 2020-12
 unless you have a draft-07 schema already; both work.
 
-### 3. Call it
+### 4. Call it
 
 ```ts
 const rig = createRig(loadConfigFromEnv());
 
 const result = await rig.run("example.support_summarize", {
   input: { ticket: rawTicket, product: "Acme Cloud", priorContext: history },
-  tags: { run_id: "run-123", step: "summarize", customer: "acme" },
-  budget: { envelope: "run-123" },   // hard-stop cost envelope for the run
+  tags: { subject: "acme", feature: "summarize" },
+  budget: { envelope: "ticket-123" }, // hard-stop cost envelope for the run
 });
 
 result.output;                 // JSON, already validated against your schema
@@ -195,51 +203,70 @@ result.meta.attemptsByClass;   // retries consumed, per failure class
 rig.close();
 ```
 
-### 4. Wrap it in a run — the standard path
+### 5. Wrap it in a run — the standard path
 
 **Every pipeline execution is a run.** A run is the standard way ModelRig records
-what your workstream did — not an appendix. Wrap the execution in a run context,
-name one **step** per model-call family, and **save the work products** as
-artifacts; then the console's **Runs** tab shows the run → step → artifact chain
-you can click through, and `/projects` groups it by tag.
+what your workstream did — not an appendix. The console's **Runs** tab then shows
+the run → step → artifact chain you can click through, and `/projects` groups it
+by tag.
+
+<!-- BLOCK:RUN_WRAP -->
+**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());
 
-// One run per pipeline execution. run.scope isolates concurrent runs; use
-// run.start()/run.end() for one run at a time on a request path.
+// 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 },
+  { 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" }, // run_id auto-stamped
-      stepKey: "summarize",                              // names this step on /runs
+      tags: { subject: customer, feature: "summarize" },
+      stepKey: "summarize", // names this step on /runs
     });
-    // Save the work product — prompt/raw/parsed all save the same way.
-    rig.artifacts.artifact.save(result.output, { name: "summary", type: "step_output" });
+    rig.artifacts.artifact.save(result.output, { name: "summary", type: "step_output", stepKey: "summarize" });
   },
 );
-rig.close();
+
+await rig.close(); // flushes the exporter — call once at shutdown
 ```
+<!-- /BLOCK:RUN_WRAP -->
 
-- **Tags:** carry `subject` (what the run is *about*) and `feature`. You no longer
-  hand-write `run_id` — **inside a run context the SDK stamps `tags.run_id`** (the
-  run's `episodeKey`, else its id) on every attempt row of both lanes; a value you
-  pass always wins, and outside a run context nothing is stamped. It also stamps
-  `tags.step` (the current step key) the same way; a value you pass always wins,
-  so name the step yourself with `stepKey` (or `tags.step`) when you want a
-  specific label.
 - **Raw lane:** a `rig.runRaw` call inside a run context records a ground-truth
   step too (since 0.5.0), so grounded/cached pipelines fill the same graph.
-- **See it:** open `/runs` — the run, its steps, its artifacts. `modelrig status`
-  prints `runs recorded: N (last: …)` as the local mirror, and `modelrig validate`
-  warns if a rig records calls but never starts a run.
-
-The full artifact API — lineage (`link`), evaluations (`evaluate`), the reusable
-per-step seam, and `run.scope` vs `run.start` — is the
-[instrumentation guide](instrumentation.md); this section is the standard path
-that links to it.
+- **Reserved tags:** `run_id` and `step` are stamped by the SDK; the full list of
+  reserved keys is in the
+  [instrumentation guide](instrumentation.md#reserved-tag-keys-the-one-list).
+
+The full artifact API — lineage (`link`), grades, the reusable per-step seam, and
+`run.scope` vs `run.start` — is the [instrumentation guide](instrumentation.md).
+
+### 6. See it on /runs
+
+Open `/runs` in the console, with the org badge showing the org `doctor` named:
+the run, its steps in order, and the artifacts you saved. `modelrig status`
+prints `runs recorded: N (last: …)` as the local mirror, and `modelrig validate`
+warns if a rig records calls but never starts a run. If the page is empty:
+
+<!-- BLOCK:EMPTY_CONSOLE -->
+**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.
+```
+<!-- /BLOCK:EMPTY_CONSOLE -->
 
 ## Change your route's model live (no redeploy)
 
@@ -253,6 +280,52 @@ merges it over your bundle. Two modes:
 - **`experiment`** — a weighted live A/B across arms, with the chosen arm recorded on
   every row so the console can score it.
 
+**See what a route serves — before its first call.** Your YAML stays the deploy-time
+default and the fail-open safety net; ModelRig is where you *see* and *change* it. A rig
+created with a `routesDir` **and** a control-plane key registers each route the moment
+`createRig()` runs — its metadata (route, version, candidates) **and its declared bundle**
+(the prompt *template* with its `{{placeholders}}`, schema, policy, plus a content hash):
+fire-and-forget, fail-open, through the same `/v1/ingest` call telemetry uses (the
+`ingest` scope is enough). The bundle is stored as **route configuration**, not captured
+content — it holds the authored template, never per-call values — so it is stored even when
+your org's capture posture is `off` (telemetry rows are still dropped then). Registering
+the bundle is what lets the control plane **validate and accept a pin** for the route: a
+pin is checked against the route's `require` before it is written, so a route with no
+registered bundle refuses pins with a teaching 422. If you promote a prompt version in
+ModelRig (Prompt System of Record), the promoted template wins over the one in your YAML
+on every later registration; everything else (candidates, schema, policy) follows your
+deploy. So every route shows up in the console and over MCP right away, and one read
+answers *"what will this route serve, and why?"*:
+
+```bash
+curl -H "authorization: Bearer $MODELRIG_API_KEY" \
+  "${MODELRIG_INGEST_URL:-https://api.modelrig.ai}/v1/routes/example.support_summarize/call-config?include=effective"
+```
+
+```jsonc
+{
+  "version": 0, "mode": null, "config": null,            // no override yet
+  "effective": {
+    "source": "deployed_default",                        // pin | experiment | deployed_default | unknown
+    "provider": "openai", "model": "gpt-5.4-mini",       // your YAML's first candidate
+    "version": 1,                                        // the YAML route version
+    "since": "2026-10-10T12:00:00Z"                      // when the deployment last declared it
+  },
+  "drift": null
+}
+```
+
+`source: "pin"` means a call-config pin is serving (its `version` is the call-config
+version); `unknown` means no deployment has registered the route in your org yet. When a
+pin is set but recent calls on the route served a **different** model, `drift` says so —
+`{ servedProvider, servedModel, calls, lastSeen, pinnedCalls, windowStart }` (last 24h,
+starting 5 minutes after the pin, ≤500 calls sampled). Drift means your app is not
+honoring the pin: its resolver is failing open (an older SDK, a wrong `MODELRIG_API_KEY`,
+or a call path that never resolves call-config — see below). The console's call-config
+card shows the same thing as **Serving: \<model\> — \<pin vN | YAML default\>** plus a
+drift warning; `get_call_config` over MCP returns it too. Without `?include=effective`
+the response is unchanged (that is what the SDK's serve-time poll reads).
+
 **Read call-config just-before-call.** Build a resolver once (it caches with a short TTL
 and revalidates by ETag — no per-call network cost when fresh), then overlay the current
 config onto a bundle and serve it through `rig.runBundle()`:
@@ -381,14 +454,26 @@ from the SDK or over HTTP for a non-SDK surface (see the
 `run-outcome@v1` grade, with an explicit, bounded model judge available when
 you want one (see the [grade protocol](grade-protocol.md#native-run-grades)).
 
+## Serve without holding the provider key (optional)
+
+Everything above runs on **your** provider key — `destination: direct`, the
+default, and nothing here changes it. If you would rather ModelRig serve a
+route's model on its own credentials and bill it from a prepaid balance, declare
+`destination: modelrig-served` on the route, set `managedServing: true` in the
+rig config, mint a key with the `serve` scope, and turn managed serving on in
+Account settings. The walk-through, including what each refusal teaches, is
+[Managed serving](managed-serving.md).
+
 ## Runtime requirements
 
 ModelRig assumes a **long-lived Node process with a writable disk**, and a few
 things follow from that. Check them before you deploy:
 
-- **Node ≥ 20**, and a native build toolchain at install time — it compiles
-  `better-sqlite3` (a C/C++ addon) for the local telemetry buffer. On a slim
-  container add the build essentials (`python3`, `make`, a C++ compiler).
+- **Node ≥ 20.** The local telemetry buffer is `better-sqlite3` (a C/C++
+  addon): it installs from a prebuilt binary on macOS and Linux (x64/arm64), and
+  compiles at install time anywhere else — on such a platform, or a slim
+  container without the prebuilt, add the build essentials (`python3`, `make`, a
+  C++ compiler).
 - **A writable disk.** Telemetry and captures go to a local SQLite file
   (`MODELRIG_TELEMETRY_DB`, default `./.modelrig/telemetry.db`); the background
   exporter batches from it. A read-only filesystem breaks this.
@@ -417,8 +502,9 @@ loader's own words, is in [route-bundles.md](./route-bundles.md#when-it-doesnt-w
 - **The bundle won't load, naming an undeclared variable.** A `{{name}}` in the
   template isn't in `prompt.variables`. Add it (or fix the typo).
 - **The first call succeeds locally but nothing appears in the console.**
-  `MODELRIG_API_KEY` isn't set in that environment. Everything runs without it;
-  it only decides where telemetry lands.
+  Usually `MODELRIG_API_KEY` isn't set in that environment, or it belongs to a
+  different org than the one the console is showing. Run `npx modelrig doctor`
+  there and work through [Troubleshooting an empty console](https://modelrig.dev/troubleshooting.html).
 - **The call runs but the output isn't what the old code produced.** Usually a
   wrong `json: native` — a claim about the model, valid only for one whose
   registry entry shows probed `structured_native`. Check the probed registry,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelrig",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": false,
   "description": "ModelRig — capability-aware AI gateway: routes-as-code, provider adapters, typed failures, budget envelopes, and local-first telemetry.",
   "license": "Apache-2.0",
@@ -52,6 +52,7 @@
     "docs/how-it-fits.md",
     "docs/migration-playbook.md",
     "docs/mcp-oracle.md",
+    "docs/managed-serving.md",
     "docs/agent-skill/SKILL.md",
     "docs/llms.txt",
     "templates/ticket-triage.json",
@@ -75,7 +76,7 @@
     "@google/genai": "^2.4.0",
     "ajv": "^8.17.0",
     "better-sqlite3": "^11.10.0",
-    "openai": "^4.77.0",
+    "openai": "^7.13.0",
     "yaml": "^2.6.0"
   },
   "devDependencies": {

package/registry/registry.json

@@ -7296,6 +7296,88 @@
         "NOT flex-eligible (mini/nano, Pro, and older families) — flex requests are silently served at default tier"
       ],
       "facts": null
+    },
+    {
+      "model_key": "zai/glm-5p2",
+      "declared": {
+        "as_of": "2026-09-08T00:00:00.000Z",
+        "source": "z.ai-price-list(2026-09-08)+adapter-static",
+        "pricing": {
+          "input_usd_per_mtok": 1.4,
+          "output_usd_per_mtok": 4.4,
+          "cached_input_usd_per_mtok": null
+        },
+        "pricing_v2": {
+          "base": {
+            "input": 0.0000014,
+            "output": 0.0000044,
+            "cache_read": null
+          },
+          "tiers": null,
+          "context_bands": null,
+          "batch_discount": null,
+          "modality": null,
+          "source": "z.ai-website",
+          "as_of": "2026-09-08T00:00:00.000Z",
+          "basis": "base · standard tier · text"
+        },
+        "flags": {
+          "supports_response_schema": true,
+          "supports_web_search": true,
+          "supports_prompt_caching": null,
+          "adapter_structured_native": null,
+          "adapter_grounded_native": false,
+          "supports_image_input": false
+        }
+      },
+      "probed": null,
+      "observed": null,
+      "discrepancies": [],
+      "callNotes": [
+        "B4a: reachable via the OpenAI-compat adapter on the Z.ai international endpoint (https://api.z.ai/api/paas/v4) keyed by ZAI_API_KEY; model id passes through verbatim (no wire prefix). Native GLM web_search (supports_web_search declared) is NOT wired on the ModelRig adapter until B4b — adapter_grounded_native is pinned false (so the derived grounded_native capability matches the fail-closed raw-lane grounding knob; B4b flips it true and wires the tool)."
+      ],
+      "facts": null
+    },
+    {
+      "model_key": "zai/glm-5p2-flash",
+      "declared": {
+        "as_of": "2026-09-08T00:00:00.000Z",
+        "source": "z.ai-price-list(2026-09-08)+adapter-static",
+        "pricing": {
+          "input_usd_per_mtok": 0.08,
+          "output_usd_per_mtok": 0.25,
+          "cached_input_usd_per_mtok": null
+        },
+        "pricing_v2": {
+          "base": {
+            "input": 0.00000008,
+            "output": 0.00000025,
+            "cache_read": null
+          },
+          "tiers": null,
+          "context_bands": null,
+          "batch_discount": null,
+          "modality": null,
+          "source": "z.ai-website",
+          "as_of": "2026-09-08T00:00:00.000Z",
+          "basis": "base · standard tier · text"
+        },
+        "flags": {
+          "supports_response_schema": true,
+          "supports_web_search": true,
+          "supports_prompt_caching": null,
+          "adapter_structured_native": null,
+          "adapter_grounded_native": false,
+          "supports_image_input": false
+        }
+      },
+      "probed": null,
+      "observed": null,
+      "discrepancies": [],
+      "callNotes": [
+        "B4a: budget GLM sibling reached via the OpenAI-compat adapter on the Z.ai international endpoint keyed by ZAI_API_KEY; model id passes through verbatim. Native web_search is B4b (adapter_grounded_native pinned false so the derived grounded_native capability matches the fail-closed raw-lane grounding knob)."
+      ],
+      "facts": null
     }
   ]
 }

package/dist/feedback/feedback.d.ts

@@ -1,35 +0,0 @@
-/**
- * rig.feedback() — Phase 4 WS2 (spec: judgment starts accumulating).
- * The SDK surface normalizes a target (inference id or {episode}) + opts
- * into a FeedbackRow; the write is a synchronous local SQLite insert
- * (fire-and-forget from the caller's view — no network, never throws for
- * sink reasons). The Supabase mirror rides the exporter, dual-store style.
- */
-import type { FeedbackRow } from "../types/telemetry";
-export type FeedbackTarget = string | {
-    readonly episode: string;
-};
-export interface FeedbackOpts {
-    readonly verdict: "up" | "down";
-    /** Optional graded signal in [0, 1]; verdict remains the primary axis. */
-    readonly score?: number;
-    readonly note?: string;
-    /** Who judged: "sdk" (default), a review-agent name, "human", … */
-    readonly source?: string;
-    /**
-     * The org this verdict belongs to (Phase 6 WS2). Omit from application code
-     * — a rig has one org and the exporter knows it.
-     *
-     * Supplied by modelrig-server, and only ever with an org it has ALREADY
-     * authorized the caller into: a value that arrived in a request body and was
-     * passed through here would be a tenant chosen by the client (T3). Setting
-     * it is what lets one hosted server hold verdicts for many orgs without
-     * misfiling any of them (QA-P6-010).
-     */
-    readonly orgId?: string;
-    /** Authenticated user who recorded it. Same provenance rule as `orgId`:
-     * resolved from a session, never read off a request body. */
-    readonly createdBy?: string | null;
-}
-export declare function buildFeedbackRow(target: FeedbackTarget, opts: FeedbackOpts): FeedbackRow;
-//# sourceMappingURL=feedback.d.ts.map