modelrig 0.8.1 → 0.10.0

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})` —
@@ -8,29 +10,40 @@ and three things happen at once:
 - **See** — the run lands in an **inspectable artifact store** (runs → steps →
   artifacts, lineaged and integrity-hashed; see the
   [instrumentation guide](instrumentation.md)), with cost/tokens/tier and a
-  verdict recorded against your tags.
+  grade recorded against your tags.
 - **Prove** — you get schema-validated output, served only by a model you
   authorized, and you can replay that traffic against cheaper candidates in a
   bake-off before you change anything.
 - **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
+
+<!-- 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).
 
-### 2. Define a route bundle
+```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,193 @@ 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.
+- **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)
+
+A route's **call-config** — which model/provider serves it, and its sampling — can be
+changed *while your app runs*, without editing YAML or redeploying. You set it in the
+console (the route's **call-config card**), or your coding agent sets it for you over
+MCP (`set_call_config`, below); the SDK reads the current config **just-before-call** and
+merges it over your bundle. Two modes:
+
+- **`pin`** — one model serves the route right now.
+- **`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()`:
+
+```ts
+import {
+  createRig, loadConfigFromEnv,
+  createApiCallConfigFetcher, createCallConfigResolver,
+  getCallConfig,                 // pin-only convenience: route + bundle → runnable bundle
+} from "modelrig";
+
+const rig = createRig(loadConfigFromEnv());
+
+// Build once, reuse across calls. TTL is the cache-freshness window (~30–60s).
+const resolver = createCallConfigResolver({
+  fetcher: createApiCallConfigFetcher({
+    ingestUrl: process.env.MODELRIG_INGEST_URL ?? "https://api.modelrig.ai",
+    apiKey: process.env.MODELRIG_API_KEY!,   // a read needs no special scope
+  }),
+  ttlMs: 30_000,
+});
+
+// `bundle` is the route's deploy-time bundle you already hold (see runBundle below).
+// getCallConfig merges the live PIN over it; with no override it returns the SAME
+// bundle reference — byte-identical to today.
+const runnable = await getCallConfig("example.support_summarize", { resolver, bundle });
+const result = await rig.runBundle(runnable, { input, tags });
+```
+
+**Fail-open, always.** The read **never throws**: on any error it serves the last-known-good
+config, and a route with **no override resolves byte-identical** to the deploy-time bundle
+(the same bundle reference, unchanged). Turning this on adds no failure mode to the hot path.
+
+**Where it applies.** Call-config is overlaid onto a **bundle** you serve through
+`rig.run()` / `rig.runBundle()` — **not** `rig.runRaw`. The raw lane is BYOK and has no
+route or bundle to overlay, so a routeless raw-lane caller that wants live routing must
+first own a route/bundle (build one with `bundleFromResolved`, or resolve one from disk)
+and serve it through `runBundle`.
+
+**A/B — draw an arm locally, record it.** For `mode='experiment'`, resolve the config and
+draw the arm for this one call with `resolveCallConfigForRun`, then thread the arm name onto
+`rig.runBundle(..., { arm })` so it lands on `inferences.meta.arm`:
+
+```ts
+const resolved = await resolver.getCallConfig("example.support_summarize");
+const { bundle: runnable, arm } = resolveCallConfigForRun(bundle, resolved, {
+  input,                         // stickyKey (if set) reads its unit from here…
+  // unitKey: userId,            // …or pass the unit key explicitly (sticky assignment)
+});
+const result = await rig.runBundle(runnable, { input, tags, arm });
+// arm is null for a pin / no-override / non-experiment call ⇒ no meta.arm (byte-identical).
+```
+
+Sticky assignment means the **same unit always draws the same arm**, so the A/B is measured
+honestly. The console reads per-arm outcomes at `GET /v1/console/ab-readout?route=<route>`.
+How `meta.arm` is populated and overlaid is in the
+[instrumentation guide](instrumentation.md#live-call-config-and-ab-arms).
 
-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.
+**Set it from your coding agent (MCP).** The `modelrig-oracle` MCP server exposes
+`get_call_config`, `set_call_config` (`pin` or `experiment`), and `rollback_call_config`, so
+the agent in your editor can pin a model or start an A/B **on your behalf** — a real,
+versioned, reversible control-plane change (not a draft). Writes need a `rig_sk_` key with
+the **`route-config`** scope; reads need none. The full flow, the eligibility gate, and the
+rollback contract are in [The MCP oracle → Setting a route's live config](mcp-oracle.md#setting-a-routes-live-config).
 
 ## When it fails, it fails typed
 
@@ -286,21 +436,44 @@ worker, and cron that constructs a rig — a process without it buffers to its o
 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.
 
-Telemetry says what happened; **verdicts** say whether it was good. Attach a
-thumbs up/down to a call or a whole run with `rig.feedback(...)` — from the SDK
-or over HTTP for a non-SDK surface (see the
-[feedback protocol](feedback-protocol.md)) — and every run gets an automatic
-`run-outcome@v1` verdict, with an explicit, bounded model judge available when
-you want one (see [run verdicts](run-verdicts.md)).
+Turning **Optimization on** for a route (`capture: true`) is the **recommended
+default** — your traffic is what makes the routing smarter and the bill smaller,
+and everything it keeps you can see, export and delete in the console. Keeping the
+prompts, outputs and evidence too is [content custody](content-custody.md), which
+is **on by default** — every new org is created managed, having accepted the
+published terms at signup — and captures into your managed store, scrubbed for the
+PII/PHI you classify. Either way the **opt-out is one account setting** (the
+console or the `set_org_settings` MCP tool): set posture `off` to capture nothing
+or `metadata` to keep hashes only, or use a `zero_retention` route.
+Pure router (capture off) stays real and selectable, at the same flat 2%.
+
+Telemetry says what happened; a **grade** says whether it was good. Attach a
+0–1 score (up = 1, down = 0) to a call or a whole run with `rig.grade(...)` —
+from the SDK or over HTTP for a non-SDK surface (see the
+[grade protocol](grade-protocol.md)) — and every run gets an automatic
+`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.
@@ -329,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.8.1",
+  "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",
@@ -24,10 +24,11 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "//exports": "ADDITIVE sub-path map (RP-1). `.` preserves the historical bare entry; `./receipts` (Receipt@v1 shape + canonicalize/hash/classification) is exposed ONLY here, never re-exported from index.ts (keeps the public surface — and index.ts's LOC — untouched). `./data/*` + `./registry/*` keep the runtime data/registry files reachable now that an exports map turns resolution into an allowlist. The root `receipts.d.ts` re-export shim exists ALONGSIDE this so classic-`Node` moduleResolution consumers (e.g. modelrig-server) type-resolve the sub-path too.",
+  "//exports": "ADDITIVE sub-path map (RP-1). `.` preserves the historical bare entry; `./receipts` (Receipt@v1 shape + canonicalize/hash/classification) is exposed ONLY here, never re-exported from index.ts (keeps the public surface — and index.ts's LOC — untouched). `./screen` (IP-2a-1) exposes the SC-0/SC-1 screening surface the same way — the server's grader assembly reuses assemblePrompt + createPatternDetector rather than forking the delimiting logic; still never re-exported from index.ts. `./data/*` + `./registry/*` keep the runtime data/registry files reachable now that an exports map turns resolution into an allowlist. The root `receipts.d.ts` / `screen.d.ts` re-export shims exist ALONGSIDE this so classic-`Node` moduleResolution consumers (e.g. modelrig-server) type-resolve the sub-paths too.",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
     "./receipts": { "types": "./dist/receipts/types.d.ts", "default": "./dist/receipts/types.js" },
+    "./screen": { "types": "./dist/screen/index.d.ts", "default": "./dist/screen/index.js" },
     "./package.json": "./package.json",
     "./data/*": "./data/*",
     "./registry/*": "./registry/*"
@@ -40,6 +41,7 @@
     "dist",
     "data",
     "receipts.d.ts",
+    "screen.d.ts",
     "registry/registry.json",
     "registry/leaderboard.json",
     "README.md",
@@ -49,8 +51,19 @@
     "docs/instrumentation.md",
     "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"
+    "docs/llms.txt",
+    "templates/ticket-triage.json",
+    "templates/document-extraction.json",
+    "templates/cs-next-action.json",
+    "templates/lead-qualification.json",
+    "templates/compliance-review.json",
+    "templates/catalog-cleansing.json",
+    "templates/call-disposition-qa.json",
+    "templates/financial-classification.json",
+    "templates/medical-classification.json"
   ],
   "scripts": {
     "build": "tsc",
@@ -63,10 +76,11 @@
     "@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": {
+    "@modelrig/glossary": "workspace:*",
     "@types/better-sqlite3": "^7.6.12",
     "tsx": "^4.21.0",
     "typescript": "^5.2.0",