pi-typesafe-router 0.1.0 → 0.2.0

package/README.md

@@ -1,64 +1,56 @@
 # pi-typesafe-router
 
-An opt-in [Pi](https://github.com/earendil-works/pi) extension that asks Jev to classify a task, then selects a generation model from your ordered mappings.
-
-Classification supports **TypeSafe direct, Cloudflare Workers AI, and Vercel AI Gateway**. Model fallback happens only before generation. A failed task is never automatically replayed by this extension.
+Use Jev to classify requests and route them to the right model for the task.
 
 ## Setup
 
-Requires Node.js 22.19+ and Pi 0.85.1. This is an unpublished local implementation; no live backend credentials have been tested.
+Do not enable this alongside another automatic router.
 
-From this checkout, install dependencies and load the extension for one session:
+Install via:
 
-```sh
-npm ci
-pi -e ./src/index.ts
+```bash
+`pi install npm:pi-typesafe-router`
 ```
 
-Do not enable this alongside another automatic router. Choose a real provider/model in Pi first, then run:
+Choose a real provider/model in Pi first, then run:
 
 ```text
 /typesafe-router setup typesafe
 ```
 
-This creates `~/.pi/agent/typesafe-router.json`, initially **off**, using your selected model for all three routes. It never overwrites a file. Edit the mappings, set `TYPESAFE_API_KEY` in the environment that launches Pi, and restart Pi. Never put the key in your prompt or config file.
+This creates `~/.pi/agent/typesafe-router.json`, initially **off**, using your selected model for all three routes. Edit the mappings, set `TYPESAFE_API_KEY` in the environment that launches Pi, and run `/reload`.
 
-For a persistent local installation, use `pi install /absolute/path/to/pi-typesafe-router`. Once published, the equivalent will be `pi install npm:pi-typesafe-router`.
+`pi install npm:pi-typesafe-router`.
 
 ## Usage
 
-Apply configuration and verify the classifier and generation targets, then enable routing:
+Verify your configuration, then enable routing:
 
 ```text
 /typesafe-router doctor
 /typesafe-router on
 ```
 
-`doctor` checks local eligibility, sends one synthetic classifier request, and probes each distinct configured provider/model with an isolated synthetic generation request. No actual conversation transcript or tools are sent. **These requests may incur charges**, even while routing is off; there is no strict monetary cap. Explicit invocation also works headless with `allowHeadless: false`. Doctor never changes the selected model or runs or replays your task.
-
-Doctor must complete successfully, including the classifier check, with at least one locally eligible, successfully probed target in **each** of `quick`, `standard`, and `deep`. Until then, `on`, `shadow`, and automatic input are blocked; `off` and manual Pi use remain available. Subsequent preflight skips failed targets, even the first configured target, and preserves the configured order of remaining successful candidates. A probe is a health snapshot, not a guarantee that a later task will succeed.
-
-Verification is session-only and never persisted. Restart or reload requires doctor again. Changes to routes, credential references, backend configuration, or model metadata—even under the same provider/model ID—invalidate verification. Each doctor refresh discards old proofs; cancellation or incomplete checks never partially unlock routing.
-
-`/typesafe-router` (or `status`) is read-only: it reports the applied configuration, runtime mode, current model, and on-disk differences without network calls. Reports include next steps only where relevant. Pi's built-in `/reload` loads updated extension code; it is not needed for configuration changes—use `/typesafe-router doctor` instead.
+Doctor tests the classifier and configured models with synthetic requests, without sending your conversation, using tools, or changing the selected model. These checks may incur charges.
 
-Use `shadow` instead of `on` to classify without changing the model. **Shadow mode still transmits text and can incur charges.** `/typesafe-router off` stops classification. `/model` selection also turns automatic routing off. Session mode changes are recorded in that session. `doctor` reloads valid configuration while preserving the current session mode; it never enables routing that is off. Missing or invalid configuration disables routing.
-
-Escape, Ctrl+C, or `/typesafe-router off` cancels preflight and stops the original prompt. If Pi is already resolving generation credentials, cancellation waits for its non-cancellable model setter; verify the selected model before resubmitting. Prompts rejected or cancelled during preflight are not automatically queued or replayed.
-
-After a failed generation, use Pi's `/model` to choose a model, inspect completed tool effects, and manually continue when safe. The router never selects a fallback after generation or replays a task. Pi's own retry and compaction settings remain unchanged.
+Run `/typesafe-router help` for a table explaining every command.
 
 ## Configuration
 
-See the [configuration reference](docs/configuration.md) and examples for [TypeSafe](examples/typesafe.json), [Cloudflare](examples/cloudflare.json), and [Vercel](examples/vercel.json). Only the global file is read; `PI_CODING_AGENT_DIR` relocates it. Project-local configuration is intentionally ignored.
+Configuration examples are provided for [TypeSafe](examples/typesafe.json), [Cloudflare](examples/cloudflare.json), [Vercel](examples/vercel.json), and [OpenRouter](examples/openrouter.json).
 
-| Backend               | Credential                                   | Model             |
-| --------------------- | -------------------------------------------- | ----------------- |
-| TypeSafe              | `TYPESAFE_API_KEY`                           | `jev-1.13.0`      |
-| Cloudflare Workers AI | `CLOUDFLARE_API_TOKEN`, account ID in config | `typesafe/jev`    |
-| Vercel AI Gateway     | `AI_GATEWAY_API_KEY`                         | `typesafe-ai/jev` |
+To use one:
 
-Backends are explicit; there is no cross-backend failover. Vercel uses the experimental AI SDK evaluation protocol, not a chat-completions endpoint. Missing confidence uses the conservative route; confidence is **not** the probability that the generation model will solve your task.
+```text
+/typesafe-router setup [typesafe|cloudflare|vercel|openrouter]
+```
+
+| Backend               | Credential                                                | Model               |
+| --------------------- | --------------------------------------------------------- | ------------------- |
+| TypeSafe              | `TYPESAFE_API_KEY`                                        | `jev-1.13.0`        |
+| Cloudflare AI Gateway | `CLOUDFLARE_API_TOKEN`, account and gateway IDs in config | `typesafe/jev`      |
+| Vercel AI Gateway     | `AI_GATEWAY_API_KEY`                                      | `typesafe-ai/jev`   |
+| OpenRouter            | `OPENROUTER_API_KEY`                                      | `typesafe/jev-1.13` |
 
 ## Project structure
 
@@ -66,11 +58,31 @@ Backends are explicit; there is no cross-backend failover. Vercel uses the exper
 - `src/config.ts`, `context.ts`, `routing.ts`: schema, bounded text projection, and deterministic policy.
 - `src/index.ts`, `settings.ts`: Pi lifecycle, commands, cancellation, and global settings.
 - `tests/`: synthetic transport, policy, lifecycle, and real Pi SDK tests. No paid API calls.
-- `docs/`: [privacy](docs/privacy.md), [architecture and limits](docs/architecture.md), and [release checklist](docs/releasing.md).
+- `infra/github/`: [Pulumi-managed repository settings](infra/github/README.md) and `main` ruleset.
+- `docs/`: architecture decision records (ADRs), recording implemented decisions and their tradeoffs.
+
+## Testing
+
+Run `npm run check` for offline tests, lint, formatting, and typechecking.
+
+`npm install` also installs the Lefthook pre-commit hook. Each commit formats and lints its
+staged files, applying safe fixes before the commit is created. CI runs the same formatting and
+lint checks as a required job in parallel with the test matrix.
 
-## Contributing
+E2E tests require the following variables to be set:
 
-Run `npm run fmt` to format with Oxfmt, and `npm run lint:fix` to apply safe Oxlint fixes. Run `npm run check` before proposing changes; it checks formatting, lint, TypeScript, and tests, and also runs in CI. Tests must remain offline and must not read real credentials. Use `npm run smoke:package` to check the packed extension in an isolated Pi installation. Public benchmark or performance claims require clarification of TypeSafe's terms first.
+- `OPENROUTER_API_KEY`
+- `TYPESAFE_API_KEY`
+- `CLOUDFLARE_API_TOKEN`
+- `CLOUDFLARE_ACCOUNT_ID`
+- `CLOUDFLARE_GATEWAY_ID`
+- `AI_GATEWAY_API_KEY`
+
+Then:
+
+```sh
+TYPESAFE_ROUTER_LIVE_E2E=1 npm run test:e2e
+```
 
 ## License
 

package/docs/0001-route-before-generation.md

@@ -0,0 +1,58 @@
+# ADR 0001: Classify tasks, select locally, and route only before generation
+
+Status: Accepted — implemented against Pi 0.85.1
+
+## Context
+
+We want task-aware model selection without replacing Pi's providers, credentials, conversation handling, or tools. Jev can classify task demand, but its confidence does not measure whether a generation model will complete the task. Untrusted conversation text can also influence classification.
+
+The routing boundary matters. In Pi 0.85.1, `before_agent_start` runs after initial model authentication and compaction. A virtual generation provider would hide the real selected model and require us to preserve downstream streaming, limits, identity, and recovery behavior. Switching after generation begins risks repeating tool side effects.
+
+## Decision
+
+We use Jev as an advisory classifier and keep selection policy local. We route once at an eligible idle `input` boundary, before generation authentication and compaction. We select real Pi models rather than registering a synthetic provider.
+
+```text
+idle input → session verification → bounded text classification
+           → local route policy → ordered eligibility checks
+           → serialized model selection → original input continues once
+```
+
+### Classification does not grant authority
+
+- We use a fixed `quick` / `standard` / `deep` taxonomy plus `uncertain`. Configuration maps routes to flat, ordered lists of exact provider/model identities. This avoids inferred model names, route graphs, and implicit destinations.
+- We validate labels, probability distributions, and confidence at runtime. Errors and timeouts use `defaultRoute`; uncertainty or missing/low confidence uses `uncertainRoute`. Both default to `deep`. Confidence is not a downstream success probability.
+- We check current catalogue availability, model scope, image support, context/output budgets, and the generation proofs from [ADR 0002](0002-verify-routing-with-doctor.md). Failed selection advances only within the configured chain. An exhausted chain stops the prompt rather than silently using a stale model.
+- We use Pi's context accounting and token estimates rather than treating bytes as tokens. Unknown post-compaction usage leaves compaction to Pi; we do not trim generation history to fit a cheaper target.
+
+### Disclosure and transport are explicit
+
+We read only global configuration under Pi's agent directory. Repository-local configuration could redirect private content without a deliberate global choice. Configuration stores credential references, not keys; setup creates an off-mode file without overwriting existing settings.
+
+We send the intact current request and bounded recent user/assistant text, not system prompts, raw tool results, reasoning, images, or files. Oversized, empty, or unexpanded slash input takes the conservative route without classification. This limits disclosure and irrelevant context, but ordinary text can still contain secrets. Shadow mode also sends text and can incur charges.
+
+We support one explicitly selected backend: TypeSafe direct, Cloudflare AI Gateway's account-scoped universal REST API with an explicit gateway ID, Vercel AI Gateway's experimental evaluation API, or OpenRouter's alpha Decisions API. Small HTTP adapters serve TypeSafe, Cloudflare, and OpenRouter; Vercel uses pinned AI SDK `7.0.105` because evaluation is not a chat-completions protocol. All adapters share the rubric and normalized validation boundary.
+
+We do not retry classification, follow redirects, accept arbitrary classifier endpoints, or fail over between backends. Credentials and classification share a deadline. This bounds optional overhead and avoids silently changing recipients or billing. Pi-managed classifier credentials are opt-in API-key reuse, not proof of endpoint compatibility. Cloudflare requests disabled logging/cache and one attempt; Vercel requests zero data retention by default. Neither control establishes a universal retention guarantee.
+
+### Pi owns generation; we do not replay tasks
+
+We skip extension-generated input, steering, and queued follow-ups. The router keeps selection sticky through the tool loop rather than chasing per-step prices or sacrificing cache reuse. Manual model selection disables routing. Pi's native retry and compaction behavior remains unchanged; failure guidance waits for `agent_settled` and directs manual recovery through `/model`. There is no router recovery command that selects a post-generation fallback or resubmits work.
+
+We serialize operations and invalidate stale work with epochs and abort signals. Cancellation stops the original submission; it does not authorize fallback generation. We return `handled` to stop input because Pi can catch an input-hook exception and continue.
+
+Pi's asynchronous `setModel()` has no cancellation argument. We await the actual setter even after cancellation, keeping the selection lock held. Racing it against a timeout and selecting another candidate could let the abandoned setter overwrite the newer choice. Concurrent submissions are rejected; navigation is refused during preflight; teardown cancels and awaits completion. We do not roll back to a potentially stale model.
+
+## Consequences and alternatives
+
+- We retain Pi's real model identity and generation machinery instead of maintaining a proxy provider. We cannot offer transparent runtime outage failover or exclusive ownership against competing extensions. Do not enable competing routers.
+- A cancelled setter can still change the model. A credential plugin that never resolves can block selection and reload; restarting Pi is the recovery. TUI Escape/Ctrl+C and `off` cancel router preflight; headless callers must use `off` because normal agent abort is not active yet.
+- Context estimates are conservative, not exact candidate-specific tokenization. Later prompt expansion and other extensions can change the eventual request.
+- We defer learned cost optimization, arbitrary classifier rubrics, automatic thinking-level routing, and per-tool-step rerouting. These need outcome evidence, not merely confident task labels.
+- Synthetic tests establish local behavior, not live backend parity, savings, retention, or task quality. Vercel confidence metadata remains account-dependent evidence to verify; missing confidence stays conservative. OpenRouter's Decisions API is alpha and may change. Public performance claims require review of TypeSafe's terms.
+
+## Implementation and verification
+
+- [Configuration](../src/config.ts), [projection](../src/context.ts), [classifier adapters](../src/classifier.ts), and [pure routing policy](../src/routing.ts).
+- [Lifecycle and cancellation](../src/index.ts); regressions in [core](../tests/core.test.ts), [classifier](../tests/classifier.test.ts), [runtime](../tests/runtime.test.ts), and [real Pi integration](../tests/pi-integration.test.ts) tests.
+- Setup and configuration examples: [README](../README.md#configuration).

package/docs/0002-verify-routing-with-doctor.md

@@ -0,0 +1,56 @@
+# ADR 0002: Gate routing on session-local doctor verification
+
+Status: Accepted — implemented
+
+## Context
+
+A catalogue entry and configured credentials do not prove remote model access. They cannot establish permissions, quota, endpoint compatibility, or whether authentication succeeds. Enabling routing from these signals alone can send the first real task into a broken configuration.
+
+Separate reload, validation, and network-check commands also make it easy to inspect one configuration while routing with another. We need a single explicit operation that applies configuration and tests access, without enabling routing or running the actual task.
+
+## Decision
+
+We consolidate configuration refresh, local eligibility checks, classifier testing, and generation probes into `/typesafe-router doctor`. We keep `status` and `help` read-only. The command surface is `setup`, `doctor`, `status`, `on`, `shadow`, `off`, and `help`; omitted subcommands show status. Help prints a command table without reading configuration, making network calls, or interrupting active work. Old check/validate/reload/recover/cancel commands are not part of the contract.
+
+### Verification is required, not inferred
+
+Every doctor refresh discards previous proofs before checking anything. Readiness requires a completed run with a successful classifier check and at least one locally eligible, successfully probed model in **each** route. We do not require every fallback target to pass: a broken primary should not defeat a working authorized alternative. Later preflight skips failed targets and preserves the configured order of successful candidates.
+
+`on`, `shadow`, and automatic input require current verification. Shadow shares the gate so it evaluates a configuration we can actually use, even though it does not select a model. After the gate passes, shadow records its proposal without blocking generation for an empty proposed candidate chain. Off/manual Pi use remains available without doctor.
+
+Doctor applies valid configuration while preserving the current session mode. It never enables an off session; invalid or missing configuration disables routing. Status reports applied configuration, disk differences, current activity/model/mode, and a historical last decision. It neither applies changes nor renews proofs. This separates observation from operations with network and billing effects.
+
+### Probes exercise the actual generation path without the task
+
+Doctor performs local checks, then concurrently runs one synthetic classifier request and one isolated generation probe per distinct configured provider/model. Targets shared across routes are probed once. Generation probes use Pi's `modelRegistry.complete`, not `setModel`, so they exercise configured providers, OAuth, headers, and endpoints without changing the selected model.
+
+Probes contain no conversation transcript and use `tools: []`, `maxTokens: 128` where supported, and `maxRetries: 0`. Each generation probe has its own `generationProbeTimeoutMs` deadline, separate from classification. We validate response identity, stop reason, absence of tool calls, and nonempty text rather than trusting the model to declare its own health.
+
+Explicit doctor invocation authorizes potentially billable diagnostics without a second confirmation, including while off or headless with `allowHeadless: false`. That flag still gates automatic routing. One command gives a complete access report rather than another optional step that can be mistaken for verification. The cost is real: token and time limits are not a strict monetary cap, and credentials may refresh.
+
+### Proofs belong to the current session and configuration
+
+We retain passed target identities and a verification fingerprint only in memory. The fingerprint covers configuration, resolved model metadata, provider object identities, auth status, and registered provider configuration, including classifier-only Pi credential providers. We never persist the fingerprint or credential material as verification evidence.
+
+Restart/reload or an identity change requires a fresh doctor run. Current local eligibility is rechecked before enabling or routing, so changed scope or context can invalidate readiness. Provider refreshes can conservatively require another run even with unchanged provider/model IDs. The fingerprint does not detect every secret rotation; changing an environment variable's value alone does not change it. Persisted proofs would imply validity across changes we cannot reliably observe.
+
+Doctor serializes with preflight and model selection. Cancellation aborts the batch; incomplete work never publishes partial readiness. Probes check cancellation again after authentication and before transport, so late credential resolution cannot start an abandoned request or publish a proof. A credential plugin can still finish authentication or refresh credentials after cancellation.
+
+### Reports distinguish progress, access, and readiness
+
+We count completed checks, including failures, while preserving configured route order in the final report. TUI progress uses one temporary widget above the editor, independent of routing mode and the footer, and clears on completion or cancellation. Other interfaces receive textual progress; headless diagnostics use stderr. This makes parallel work visible without a stream of persistent TUI notifications.
+
+Reports show the applied configuration result, runtime mode, current model, credential source, local eligibility, classifier result, generation outcomes, and readiness. Next steps depend on the actual state. We report normalized reasons rather than raw provider errors or response bodies. Shutdown suppresses stale output.
+
+## Consequences and alternatives
+
+- We prefer active access checks over catalogue-only validation, but doctor is only a health snapshot. It does not guarantee later availability, quota, task quality, or classifier accuracy.
+- Requiring fresh session proofs adds startup friction and charges, including for shadow mode. We accept this rather than silently treating old success or partial checks as readiness.
+- Deduplication and concurrency reduce duplicate charges and elapsed time, but a large target set still creates a burst of requests. Per-model deadlines are not a total doctor deadline or spending limit.
+- We keep diagnostics separate from task recovery. Doctor never selects a generation model, executes tools, or retries the original task. Generation failure remains manual recovery as described in [ADR 0001](0001-route-before-generation.md).
+
+## Implementation and verification
+
+- [Command lifecycle and readiness gate](../src/index.ts), [verification identity](../src/verification.ts), [isolated probes](../src/generation-probe.ts), and [report formatting](../src/diagnostics.ts).
+- Regressions in [verification](../tests/verification.test.ts), [probe](../tests/generation-probe.test.ts), [diagnostics](../tests/diagnostics.test.ts), and [runtime](../tests/runtime.test.ts) tests.
+- Run `npm run check` for offline checks and `npm run smoke:package` for packed-install loading. Neither replaces account-specific live compatibility checks of response shape, confidence extraction, permissions, billing controls, and cancellation. Run live checks only with explicit approval for charges.

package/examples/cloudflare.json

@@ -6,6 +6,7 @@
     "type": "cloudflare",
     "model": "typesafe/jev",
     "accountId": "00000000000000000000000000000000",
+    "gatewayId": "replace-with-your-gateway-slug",
     "auth": {
       "source": "env",
       "variable": "CLOUDFLARE_API_TOKEN"

package/examples/openrouter.json

@@ -0,0 +1,40 @@
+{
+  "version": 1,
+  "mode": "off",
+  "allowHeadless": false,
+  "backend": {
+    "type": "openrouter",
+    "model": "typesafe/jev-1.13",
+    "auth": {
+      "source": "env",
+      "variable": "OPENROUTER_API_KEY"
+    }
+  },
+  "timeoutMs": 1500,
+  "minConfidence": 0.8,
+  "maxContextChars": 12000,
+  "historyMessages": 4,
+  "outputReserveTokens": 8192,
+  "routes": {
+    "quick": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_QUICK_MODEL_ID"
+      }
+    ],
+    "standard": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_STANDARD_MODEL_ID"
+      }
+    ],
+    "deep": [
+      {
+        "provider": "REPLACE_WITH_PI_PROVIDER",
+        "model": "REPLACE_WITH_DEEP_MODEL_ID"
+      }
+    ]
+  },
+  "defaultRoute": "deep",
+  "uncertainRoute": "deep"
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-typesafe-router",
-  "version": "0.1.0",
-  "description": "Opt-in Jev task routing for Pi with TypeSafe, Cloudflare and Vercel backends and ordered preflight model fallbacks",
+  "version": "0.2.0",
+  "description": "Opt-in Jev task routing for Pi with TypeSafe, Cloudflare, Vercel, and OpenRouter backends and ordered preflight model fallbacks",
   "keywords": [
     "jev",
     "model-routing",
@@ -10,38 +10,46 @@
     "typesafe"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jekozyra/pi-typesafe-router.git"
+  },
   "files": [
     "src",
     "examples",
     "README.md",
     "LICENSE",
-    "docs/privacy.md",
-    "docs/configuration.md",
-    "docs/architecture.md",
-    "docs/releasing.md"
+    "docs/0001-route-before-generation.md",
+    "docs/0002-verify-routing-with-doctor.md"
   ],
   "type": "module",
   "scripts": {
     "test": "tsx --test tests/*.test.ts",
+    "test:e2e": "tsx --test --test-concurrency=1 tests/e2e/*.test.ts",
     "typecheck": "tsc --noEmit",
     "fmt": "oxfmt --write .",
     "fmt:check": "oxfmt --check .",
-    "lint": "oxlint --deny-warnings src tests scripts",
-    "lint:fix": "oxlint --fix --deny-warnings src tests scripts",
-    "check": "npm run fmt:check && npm run lint && npm run typecheck && npm test",
+    "lint": "oxlint --deny-warnings src tests scripts infra/github",
+    "lint:fix": "oxlint --fix --deny-warnings src tests scripts infra/github",
+    "check:quality": "lefthook validate && npm run fmt:check && npm run lint",
+    "check": "npm run check:quality && npm run typecheck && npm test",
     "smoke:package": "node scripts/package-smoke.mjs",
-    "prepack": "npm run typecheck"
+    "prepack": "npm run typecheck",
+    "changeset": "changeset",
+    "release:version": "changeset version && npm install --package-lock-only --ignore-scripts"
   },
   "dependencies": {
     "ai": "7.0.105",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@changesets/cli": "3.0.3",
     "@earendil-works/pi-ai": "0.85.1",
     "@earendil-works/pi-coding-agent": "0.85.1",
     "@earendil-works/pi-tui": "0.85.1",
     "@oxlint/plugins": "1.83.0",
     "@types/node": "^22.0.0",
+    "lefthook": "2.1.14",
     "oxfmt": "0.68.0",
     "oxlint": "1.83.0",
     "tsx": "^4.20.0",

package/src/classifier.ts

@@ -72,12 +72,25 @@ const gatewayResponseSchema = z.object({
     .catch(undefined),
 });
 
+// Run markers must not fall through to legacy answers when a run is incomplete or malformed.
+const cloudflareAnswerSchema = directResponseSchema.extend({
+  state: z.never().optional(),
+  result: z.never().optional(),
+});
+
+const cloudflareResultSchema = z.union([
+  z
+    .object({ state: z.literal("Completed"), result: directResponseSchema })
+    .transform((value) => value.result),
+  cloudflareAnswerSchema,
+]);
+
 // A malformed envelope must not fall through to the bare-result alternative.
 const cloudflareResponseSchema = z.union([
   z
-    .object({ success: z.literal(true), result: directResponseSchema })
+    .object({ success: z.literal(true), result: cloudflareResultSchema })
     .transform((value) => value.result),
-  directResponseSchema.extend({ success: z.never().optional(), result: z.never().optional() }),
+  cloudflareAnswerSchema.extend({ success: z.never().optional() }),
 ]);
 
 type Answer = z.output<typeof answerSchema>;
@@ -227,25 +240,43 @@ export function createClassifier(
         );
       }
 
-      const url =
-        backend.type === "typesafe"
-          ? "https://api.typesafe.ai/v1/systemone"
-          : `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(backend.accountId)}/ai/run`;
+      const headers = new Headers({
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      });
 
-      const body =
-        backend.type === "typesafe"
-          ? { model: backend.model, state, questions }
-          : { model: backend.model, input: { state, questions } };
+      let url: string;
+      let body: string;
+      let schema: typeof directResponseSchema | typeof cloudflareResponseSchema;
+
+      switch (backend.type) {
+        case "typesafe":
+          url = "https://api.typesafe.ai/v1/systemone";
+          body = JSON.stringify({ model: backend.model, state, questions });
+          schema = directResponseSchema;
+          break;
+        case "openrouter":
+          url = "https://openrouter.ai/api/alpha/decisions";
+          body = JSON.stringify({ model: backend.model, state, questions });
+          schema = directResponseSchema;
+          break;
+        case "cloudflare":
+          url = `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(backend.accountId)}/ai/run`;
+          body = JSON.stringify({ model: backend.model, input: { state, questions } });
+          schema = cloudflareResponseSchema;
+          headers.set("cf-aig-gateway-id", backend.gatewayId);
+          headers.set("cf-aig-collect-log", "false");
+          headers.set("cf-aig-skip-cache", "true");
+          headers.set("cf-aig-max-attempts", "1");
+          break;
+      }
 
       const response = await guardedFetch(url, {
         method: "POST",
-        headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
-        body: JSON.stringify(body),
+        headers,
+        body,
       });
 
-      const schema =
-        backend.type === "cloudflare" ? cloudflareResponseSchema : directResponseSchema;
-
       const parsed = schema.parse(await response.json());
       signal.throwIfAborted();
 

package/src/config.ts

@@ -45,6 +45,7 @@ const backend = z.discriminatedUnion("type", [
         .string()
         .length(32)
         .regex(/^[a-fA-F0-9]{32}$/u),
+      gatewayId: identifier,
       auth: auth.default(envAuth("CLOUDFLARE_API_TOKEN")),
     })
     .strict(),
@@ -56,6 +57,13 @@ const backend = z.discriminatedUnion("type", [
       zeroDataRetention: z.boolean().default(true),
     })
     .strict(),
+  z
+    .object({
+      type: z.literal("openrouter"),
+      model: z.literal("typesafe/jev-1.13").default("typesafe/jev-1.13"),
+      auth: auth.default(envAuth("OPENROUTER_API_KEY")),
+    })
+    .strict(),
 ]);
 
 const target = z.object({ provider, model: identifier }).strict();

package/src/index.ts

@@ -29,7 +29,9 @@ import {
 import { classifierLines, routeLines, runtimeLines, type EvaluationResult } from "./diagnostics.ts";
 import { abortable, createConfig, loadConfig } from "./settings.ts";
 import {
+  BACKEND_TYPES,
   ClassifierError,
+  isBackendType,
   targetKey,
   type Classification,
   type Classify,
@@ -47,8 +49,21 @@ const sessionModeSchema = z.object({ mode: z.enum(["off", "auto", "shadow"]) });
 const DISCLOSURE =
   "Classification sends your request and bounded recent user/assistant text to the configured backend. Text can contain private code or secrets. Shadow mode also sends data and may incur charges. No automatic generation replay or classifier-backend failover.";
 
-const HELP =
-  "/typesafe-router setup [typesafe|cloudflare|vercel] | doctor | status | on | shadow | off";
+const BACKEND_HELP = BACKEND_TYPES.join("|");
+
+const HELP = `/typesafe-router setup [${BACKEND_HELP}] | doctor | status | on | shadow | off | help`;
+
+const COMMAND_HELP = `Usage: /typesafe-router <command>
+
+Command                              Description
+---------------                      ------------------------------------
+setup [${BACKEND_HELP}] Create a config interactively.
+doctor                               Apply and validate config..
+status                               Show current settings and activity.
+on                                   Enable automatic routing.
+shadow                               Classify without switching models.
+off                                  Disable routing.
+help                                 Show this table.`;
 
 interface Decision {
   route: Route;
@@ -685,7 +700,7 @@ export function registerRouter(pi: RouterAPI, dependencies: Dependencies = {}):
             "classifier check: skipped; no valid configuration",
             invalidConfig
               ? "next: fix the configuration JSON, fields, or file permissions, then run /typesafe-router doctor"
-              : "next: /typesafe-router setup typesafe (or cloudflare/vercel), then /typesafe-router doctor",
+              : `next: /typesafe-router setup typesafe (or ${BACKEND_TYPES.slice(1).join("/")}), then /typesafe-router doctor`,
           ].join("\n"),
           "error",
         );
@@ -940,6 +955,12 @@ export function registerRouter(pi: RouterAPI, dependencies: Dependencies = {}):
         return;
       }
 
+      if (command === "help") {
+        notify(ctx, COMMAND_HELP);
+
+        return;
+      }
+
       if (command === "off") {
         configError = false;
         setMode("off", ctx);
@@ -1002,12 +1023,11 @@ export function registerRouter(pi: RouterAPI, dependencies: Dependencies = {}):
         }
 
         const backend =
-          option ??
-          (await ctx.ui.select("Classification backend", ["typesafe", "cloudflare", "vercel"]));
+          option ?? (await ctx.ui.select("Classification backend", [...BACKEND_TYPES]));
 
         if (!backend || !permitted()) return;
 
-        if (!["typesafe", "cloudflare", "vercel"].includes(backend)) {
+        if (!isBackendType(backend)) {
           notify(ctx, HELP, "warning");
 
           return;
@@ -1020,6 +1040,13 @@ export function registerRouter(pi: RouterAPI, dependencies: Dependencies = {}):
 
         if (!permitted() || (backend === "cloudflare" && !accountId)) return;
 
+        const gatewayId =
+          backend === "cloudflare"
+            ? await ctx.ui.input("Cloudflare AI Gateway ID (gateway slug, not an API token)")
+            : undefined;
+
+        if (!permitted() || (backend === "cloudflare" && !gatewayId)) return;
+
         const models = ctx.modelRegistry
           .getAvailable()
           .filter((model) => !["auto", "smart-router", "typesafe-router"].includes(model.provider));
@@ -1041,7 +1068,10 @@ export function registerRouter(pi: RouterAPI, dependencies: Dependencies = {}):
 
           const initial = parseConfig({
             version: 1,
-            backend: backend === "cloudflare" ? { type: backend, accountId } : { type: backend },
+            backend:
+              backend === "cloudflare"
+                ? { type: backend, accountId, gatewayId }
+                : { type: backend },
             routes: { quick: [target], standard: [target], deep: [target] },
           });
 

package/src/types.ts

@@ -10,15 +10,30 @@ export type CredentialSource =
   | { source: "env"; variable: string }
   | { source: "pi"; provider: string };
 
+export const BACKEND_TYPES = ["typesafe", "cloudflare", "vercel", "openrouter"] as const;
+
+export type BackendType = (typeof BACKEND_TYPES)[number];
+
+export function isBackendType(value: string): value is BackendType {
+  return BACKEND_TYPES.some((backend) => backend === value);
+}
+
 export type Backend =
   | { type: "typesafe"; model: string; auth: CredentialSource }
-  | { type: "cloudflare"; model: "typesafe/jev"; accountId: string; auth: CredentialSource }
+  | {
+      type: "cloudflare";
+      model: "typesafe/jev";
+      accountId: string;
+      gatewayId: string;
+      auth: CredentialSource;
+    }
   | {
       type: "vercel";
       model: "typesafe-ai/jev";
       auth: CredentialSource;
       zeroDataRetention: boolean;
-    };
+    }
+  | { type: "openrouter"; model: "typesafe/jev-1.13"; auth: CredentialSource };
 
 export interface Target {
   provider: string;

package/docs/architecture.md

@@ -1,59 +0,0 @@
-# Routing before generation
-
-Jev classifies task demand. A local policy chooses eligible generation targets. Neither classifier output nor task text can supply a provider URL, invent a model target, or bypass the configured chains.
-
-```text
-idle user input
-  → current session doctor verification gate
-  → bounded text projection
-  → one explicitly selected classifier adapter
-  → validated quick / standard / deep / uncertain answer
-  → local confidence policy
-  → ordered candidate eligibility checks
-  → serialized Pi model selection
-  → original input continues once
-```
-
-`classify` normalizes three protocols. `chooseRoute` and `candidateChecks` are pure. `registerRouter` owns lifecycle and session-local state. This is not an LLM proxy and does not register a synthetic generation model.
-
-## Lifecycle contract
-
-The implementation targets Pi **0.85.1**. Its idle `input` hook runs before initial generation authentication and compaction. `before_agent_start` is too late for a router that must rescue a missing initial model/auth configuration. Selection happens once at the idle input boundary; streaming steering/follow-up and extension-generated input pass through without classification. Tool-loop selection is sticky by router policy, not by an immutable host guarantee.
-
-The extension returns `handled` when preflight must stop a prompt. Throwing would be unsafe: Pi catches input-hook exceptions and can continue generation. No path uses `sendUserMessage`, resends the original input, or chooses a new model after a generation error. Native Pi retry/overflow recovery is not disabled or replaced. Failure guidance waits for `agent_settled`, after native recovery finishes.
-
-Model selection requires a current successful doctor generation proof, then checks exact catalogue identity, configured auth presence, nonempty scoped-model restrictions, image support, and conservative context/output budgets. A setter returning false or throwing skips to the next candidate before generation. Failed doctor targets are skipped, even when first in a chain; remaining successful candidates keep their configured order. Catalogue eligibility alone does not prove remote credentials, quotas, availability, or task quality. A successful probe is only a health snapshot, not a guarantee of future generation. Context sizing uses Pi's `ctx.getContextUsage()` count, which incorporates provider-reported usage and Pi's trailing-message estimates. Unsent input uses Pi's exported `estimateTokens`; the router does not count serialized metadata or treat bytes as tokens. If Pi reports unknown usage immediately after compaction, the router skips only its context-size check and leaves compaction/accounting to Pi. If no usage API result is available, it sums Pi's message estimates. Counts are not exact candidate-specific tokenization; Pi's current accounting is the shared basis. Unknown post-input changes from templates, context hooks, tools, or other extensions cannot be predicted.
-
-## Cancellation and concurrency
-
-Each operation has an epoch and an AbortController. Classifier credentials and HTTP share a deadline. Late classification/credential results are ignored. Escape/Ctrl+C are intercepted during TUI preflight, and `/typesafe-router off` also invalidates the operation. Headless callers must use `off` during preflight; Pi's normal agent abort signal is not yet active there.
-
-Pi's `setModel()` is asynchronous and has **no cancellation argument**. A timeout race cannot prevent it from later changing the model. The router therefore awaits the actual setter, never starts another selection in parallel, and consumes the cancelled original input afterward. Concurrent input is rejected, even if routing was turned off while authentication was pending. Model selection may finish after cancellation; users must verify it before resubmitting. There is no unsafe rollback to a stale model.
-
-Session navigation is refused while preflight is active, cancelling the operation first. Shutdown/reload cancels and awaits its completion before allowing teardown. If a credential plugin never resolves its model-auth promise, selection and reload can remain blocked; restarting Pi is the recovery. This is an explicit limitation of the host setter, not something a timer can safely fix.
-
-## Failure and recovery
-
-Classification errors, timeouts, invalid responses, or missing keys use `defaultRoute`. Low/missing confidence and explicit uncertainty use `uncertainRoute`. Oversized, empty, and unexpanded slash input skip classification and use the conservative route. No eligible candidate consumes the prompt with an error instead of silently using a stale model. After the doctor gate passes, shadow mode records the proposed route but neither changes the model nor blocks generation for an empty candidate chain. Both on and shadow modes, including automatic input, are blocked without current doctor verification; off/manual Pi use remains available.
-
-After generation fails, guidance points to Pi's `/model`, inspection of completed tool effects, and manual continuation when safe. The router does not select a post-generation fallback or replay a task. Manual model selection disables routing. Do not run multiple routers: Pi does not provide exclusive model-selection ownership between extensions.
-
-## Diagnostics and configuration
-
-`/typesafe-router doctor` serializes with preflight and model selection. It applies valid configuration while retaining the current session's on/off/shadow mode; it never enables an off session. Missing or invalid configuration disables routing. Every refresh invalidates old proofs before checking anything. Readiness requires a completed, successful doctor run: the classifier check must succeed and every quick/standard/deep route must contain at least one locally eligible target with a successful generation probe. Cancellation or incomplete work cannot publish partial readiness.
-
-Doctor checks local eligibility, then runs the synthetic classifier request and one isolated synthetic generation request per distinct configured provider/model concurrently, deduplicated across routes. A shared progress counter counts completed checks (including failures), while the final report preserves configured route order. TUI progress updates one widget above the editor, independent of the footer and routing mode, and clears on completion, failure, or cancellation. Other interfaces receive textual progress notifications. Cancelling doctor aborts the whole batch; partial results cannot grant verification. Generation probes use Pi's `modelRegistry.complete` with the actual credential providers, including OAuth, custom headers, and configured endpoints. Credentials may refresh. Probes contain no actual conversation transcript and use `tools: []`, `maxTokens: 128` where supported, and `maxRetries: 0`. `generationProbeTimeoutMs` bounds each model probe (default 15000 ms), separately from the classifier's `timeoutMs`. These limits are not a strict monetary cap. Explicit invocation authorizes potentially billable diagnostics even while off or headless with `allowHeadless: false`. Doctor never calls the generation model setter, changes the selected model, or runs or replays the original task.
-
-Generation proofs and readiness live only in memory, not session records or config. Restart/reload requires doctor again. The verification identity covers routes, credential references, backend configuration, and model metadata, so changes under the same provider/model IDs still invalidate it. Native auth status and provider references contribute to an in-memory hash; no secrets are persisted. A changed identity requires a fresh successful doctor run, not reuse of old proofs. Effective Pi provider object identity covers native registrations and applied `models.json` changes; a provider-registry refresh can conservatively require doctor again. Classifier-only Pi credential providers are included. Before enabling or routing, every route must still have an eligible verified candidate, including current scope and context limits.
-
-Probe cancellation releases doctor promptly and checks the abort signal again after Pi resolves authentication, before invoking provider transport. A credential plugin that ignores cancellation may still finish authentication or refresh credentials later; its late result cannot start the probe transport or publish verification.
-
-Reports reflect runtime, config path/application result, actual mode, current model, backend/model, credential source, local eligibility, classifier result/latency, generation probe outcomes, and readiness, with conditional next steps. Cancellation and incomplete work are explicit; shutdown suppresses stale output. Off/Escape cancels pending work but cannot release a pending model setter's lock early.
-
-`status`, also the default subcommand, is read-only and makes no network calls. It reports applied configuration and on-disk differences (or inability to check), current activity/model/mode, and a historical last decision. It does not apply configuration or renew verification. Classifier success alone does not prove generation-provider health; successful generation probes do not guarantee later availability, quota, or task quality.
-
-## Verification boundaries
-
-Offline tests validate schema/policy, request serialization, normalized responses, cancellation, no replay, and real SDK extension loading. Packed-install smoke tests exercise Pi's actual extension loader using an isolated profile and installed production dependencies. Synthetic transports do not establish live service contracts or quality. In particular, Gateway confidence metadata needs a live account check; absent confidence stays conservative.
-
-Before claiming savings or quality, evaluate privately on representative coding tasks with pinned versions and per-model success/cost/latency outcomes. Classifier confidence measures concentration, not downstream success probability. TypeSafe's public benchmarking restrictions require permission/clarification before publishing results.

package/docs/configuration.md

@@ -1,135 +0,0 @@
-# Configure task routing
-
-The router reads only `typesafe-router.json` under Pi's agent directory (normally `~/.pi/agent`). `PI_CODING_AGENT_DIR` changes that directory. It does not read project files or discover credentials in a repository.
-
-## Map classes to model chains
-
-Copy an [example](../examples/typesafe.json), or run `/typesafe-router setup typesafe` in Pi. Replace every example target with exact IDs from Pi's model catalogue. A provider ID cannot contain a slash; a model ID can.
-
-```json
-{
-  "version": 1,
-  "mode": "off",
-  "allowHeadless": false,
-  "backend": {
-    "type": "typesafe",
-    "model": "jev-1.13.0",
-    "auth": { "source": "env", "variable": "TYPESAFE_API_KEY" }
-  },
-  "timeoutMs": 1500,
-  "generationProbeTimeoutMs": 15000,
-  "minConfidence": 0.8,
-  "maxContextChars": 12000,
-  "historyMessages": 4,
-  "outputReserveTokens": 8192,
-  "defaultRoute": "deep",
-  "uncertainRoute": "deep",
-  "routes": {
-    "quick": [{ "provider": "your-provider", "model": "your-fast-model" }],
-    "standard": [{ "provider": "your-provider", "model": "your-balanced-model" }],
-    "deep": [
-      { "provider": "your-provider", "model": "your-strong-model" },
-      { "provider": "another-provider", "model": "your-backup-model" }
-    ]
-  }
-}
-```
-
-Each chain contains one to eight distinct targets. Order is authoritative: targets without a current successful doctor generation proof, or failing local eligibility, are skipped; selection stops at the first successful `pi.setModel`. A failed first target does not prevent selection of a later successful one. Remaining successful candidates keep their configured order. Doctor deduplicates probes across chains by exact provider/model identity. There is no random sampling, cost lookup, or per-task remote health probe. `auto`, `smart-router`, and `typesafe-router` virtual providers are rejected.
-
-Unknown fields, duplicate targets, invalid types, and out-of-range settings reject the entire file. Missing, unreadable, or invalid configuration disables routing. Repair the file and run `/typesafe-router doctor` to apply it; explicitly enable routing afterward if desired.
-
-| Setting                    | Default | Accepted values                                                                  |
-| -------------------------- | ------- | -------------------------------------------------------------------------------- |
-| `version`                  | `1`     | `1`                                                                              |
-| `mode`                     | `off`   | `off`, `shadow`, `auto`                                                          |
-| `allowHeadless`            | `false` | Boolean; explicitly permit automatic routing outside TUI                         |
-| `timeoutMs`                | `1500`  | Integer, 100–30000; credentials plus classification                              |
-| `generationProbeTimeoutMs` | `15000` | Integer, 100–60000; timeout for each model’s doctor generation probe             |
-| `minConfidence`            | `0.8`   | Number, 0–1                                                                      |
-| `maxContextChars`          | `12000` | Integer, 256–32000; combined request and history text                            |
-| `historyMessages`          | `4`     | Integer, 0–20                                                                    |
-| `outputReserveTokens`      | `8192`  | Integer, 256–131072; capped at candidate's maximum output                        |
-| `defaultRoute`             | `deep`  | `quick`, `standard`, `deep`; classifier failure/unavailability                   |
-| `uncertainRoute`           | `deep`  | Same values; uncertainty, absent/low confidence, oversized or unexpanded request |
-
-`generationProbeTimeoutMs` is a top-level setting applied separately to each distinct model probe, not a total doctor deadline. Probes request `maxTokens: 128` where supported and `maxRetries: 0`; these are fixed probe options, not configuration fields. They do not establish a strict monetary cap.
-
-Character limits use JavaScript string length. The current request is never truncated. If it cannot fit, classification is skipped and the conservative route is used. Only contiguous newest fitting conversation text is included. Set `historyMessages: 0` for request-only classification.
-
-## Select one classification backend
-
-### TypeSafe direct
-
-```json
-{
-  "type": "typesafe",
-  "model": "jev-1.13.0",
-  "auth": { "source": "env", "variable": "TYPESAFE_API_KEY" }
-}
-```
-
-Requests go to `https://api.typesafe.ai/v1/systemone`. The versioned model ID is the default; explicitly configured aliases may change behavior over time. No automatic retries occur.
-
-### Cloudflare Workers AI
-
-```json
-{
-  "type": "cloudflare",
-  "accountId": "0123456789abcdef0123456789abcdef",
-  "model": "typesafe/jev",
-  "auth": { "source": "env", "variable": "CLOUDFLARE_API_TOKEN" }
-}
-```
-
-Use your own 32-hex-character account ID and a token authorized for Workers AI. The fixed account-scoped REST endpoint is `https://api.cloudflare.com/client/v4/accounts/{accountId}/ai/run`. This is Workers AI evaluation, not arbitrary Cloudflare AI Gateway chat compatibility.
-
-### Vercel AI Gateway
-
-```json
-{
-  "type": "vercel",
-  "model": "typesafe-ai/jev",
-  "zeroDataRetention": true,
-  "auth": { "source": "env", "variable": "AI_GATEWAY_API_KEY" }
-}
-```
-
-This uses AI SDK `experimental_evaluate`, pinned to SDK `7.0.105`, and the Gateway evaluation model interface. No OpenAI-compatible chat endpoint is involved. `zeroDataRetention` defaults to true; the provider may reject unsupported retention options instead of silently weakening them.
-
-Confidence is read from the per-question `providerMetadata.typesafe.confidence.task_class` map. Public documentation identifies the enclosing confidence metadata but does not demonstrate its full shape. Missing confidence remains missing and selects `uncertainRoute`; malformed confidence fails validation and selects `defaultRoute`. Run `/typesafe-router doctor` with your account before relying on this experimental integration. No live service parity is claimed.
-
-### Optional Pi-managed credentials
-
-All backends also accept `{"source":"pi","provider":"your-provider-id"}` as `auth`. This calls Pi 0.85.1's `getProviderAuth` at request time. It is opt-in, never an implicit fallback from a missing environment key. Only the resolved API key is forwarded; custom auth headers are not. A provider credential does not establish that the target evaluation endpoint accepts it. Verify audience, permissions, and backend compatibility yourself. Environment credentials are the recommended initial setup.
-
-## Commands
-
-| Command                                | Effect                                                                                                     |
-| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `setup [typesafe\|cloudflare\|vercel]` | Interactive creation of an off-mode config; never overwrites                                               |
-| `doctor`                               | Apply config, test the classifier and distinct generation targets, and refresh session verification        |
-| `status` (default)                     | Read-only report of applied config, runtime mode, current model/activity, and disk differences; no network |
-| `on` / `shadow` / `off`                | Change session mode; on/shadow require successful doctor; off cancels preflight                            |
-
-Prefix each with `/typesafe-router`. With no subcommand, the command shows status.
-
-`doctor` reloads valid configuration while preserving the current session's on/off/shadow mode, rather than adopting the file's mode. It never enables an off session. Missing or invalid configuration disables routing. It never changes the selected generation model or runs or replays a user task.
-
-Doctor automatically sends one synthetic classifier request and one isolated synthetic generation request per distinct configured provider/model, without confirmation. No actual conversation transcript is sent, and generation probes have `tools: []`. **These requests may incur charges**; there is no strict monetary cap. Explicit invocation authorizes them even with routing off or in print/RPC mode with `allowHeadless: false`. Automatic routing in those modes still requires `allowHeadless: true` and an enabled mode. Headless diagnostics go to stderr, not the assistant's output.
-
-Generation probes run through Pi's `modelRegistry.complete`, using the actual configured credential providers, including OAuth, custom headers, and custom endpoints. Credentials may refresh during diagnostics. This differs from the classifier's optional API-key-only Pi credential reuse described above.
-
-Readiness requires doctor to complete successfully, including the classifier check, and at least one locally eligible, successfully probed target in each of `quick`, `standard`, and `deep`. Not every target must pass. Failed targets are skipped in subsequent preflight, preserving the configured order of remaining successful candidates. Until ready, `on`, `shadow`, and automatic input are blocked; `off` and manual Pi use remain available. A configured startup mode does not bypass verification.
-
-Verification is session-only and never persisted. Restart/reload requires doctor again. Changes to routes, credential references, backend configuration, or model metadata invalidate it even if provider/model IDs stay the same. Native auth status and provider references contribute to an in-memory identity hash; no secrets are persisted. Each doctor refresh invalidates previous proofs. Cancellation or incomplete checks never partially unlock routing; run doctor again to recover.
-
-Doctor reports runtime, config path/application result, actual session mode, current generation model, backend/model, credential source, local eligibility, classifier result/latency, generation probe outcomes, and readiness. Reports give conditional next steps for the actual state. Local eligibility alone does not prove generation-provider health; a successful probe is a health snapshot, not a guarantee of later availability, quota, or task quality.
-
-Status reports the applied configuration, not merely the file on disk. It identifies disk differences or inability to check the file, and labels the last routing decision as historical. It neither applies changes nor tests services. Use doctor to apply and test changes.
-
-Escape/Ctrl+C in the TUI or `off` cancels preflight. While Pi's non-cancellable model setter is pending, the selection lock remains held; verify the selected model before resubmitting. Doctor is serialized with preflight/model selection.
-
-After generation fails, use `/model`, inspect completed tool effects, and manually continue when safe. The router performs no post-generation fallback and never replays a task.
-
-Manual `/model` selection turns routing off. Ordinary tool loops and queued steering/follow-up messages do not reroute. Session-tree navigation turns routing off. Active preflight blocks concurrent submissions and session navigation; after cancellation settles, repeat the desired submission/navigation yourself.

package/docs/privacy.md

@@ -1,35 +0,0 @@
-# What leaves your machine
-
-Enabling `auto` or `shadow` sends the current request and bounded recent user/assistant text to the configured classification backend. That text can contain private code, credentials, or personal data. **This extension is not a secret scanner or redaction system.** Do not enable it for material you cannot share with that backend.
-
-The default projection excludes system prompts, raw tool calls/results, reasoning blocks, image bytes, attachments, compaction summaries, and arbitrary files. If an assistant quotes a tool result or secret in ordinary text, that text can still be included. Slash-command/template input is not classified before expansion; the conservative route is used instead. There is no background classification while the router is off.
-
-## Explicit diagnostics
-
-`/typesafe-router doctor` applies valid configuration, checks local eligibility, and automatically sends one synthetic classifier request plus one isolated synthetic generation request to each distinct configured provider/model. It sends no actual conversation transcript, uses no tools (`tools: []`), asks for no confirmation, and **may incur charges**. Generation probes request `maxTokens: 128` where supported and `maxRetries: 0`, with a per-model `generationProbeTimeoutMs` deadline (default 15000 ms). These bounds are not a strict monetary cap.
-
-Invoking doctor explicitly authorizes these requests even while routing is off or headless with `allowHeadless: false`; that setting still gates automatic routing. Doctor preserves the current session mode and never enables an off session. Missing or invalid configuration disables routing. Doctor never changes the selected model or runs or replays a user task. Isolated synthetic generation probes are not retries of the actual task.
-
-Doctor must complete successfully, including the classifier check, and establish a locally eligible, successful generation candidate for each route before `on`, `shadow`, or automatic input is allowed. Off/manual Pi use remains available. Verification is session-only: restart/reload and identity changes require doctor again. Refresh discards old proofs; cancellation never partially unlocks routing.
-
-`/typesafe-router status` (also the default) is read-only and makes no network calls. It reports applied configuration, runtime mode/current model, and on-disk differences. Local eligibility is not remote generation verification, and successful probes are only health snapshots, not future guarantees.
-
-## Recipients and retention
-
-- Direct: TypeSafe's API.
-- Cloudflare: your account's Workers AI endpoint and its upstream service arrangement.
-- Vercel: AI Gateway and its upstream service arrangement. The request explicitly enables `zeroDataRetention` by default.
-
-The router never silently changes classification backends, follows HTTP redirects, or retries classification. A failed classifier uses a local configured generation route instead. Generation content goes to the model provider selected in Pi, under that provider's normal settings. Doctor also sends synthetic probe content to every distinct configured generation target through Pi's `modelRegistry.complete`, including custom endpoints and their normal provider arrangements.
-
-No-training promises do not establish zero data retention. TypeSafe's enterprise ZDR offering, gateway logging, account controls, and contract terms need separate review. The extension cannot verify a service's retention behavior. Review [TypeSafe's terms](https://typesafe.ai/legal/mca), [Cloudflare's model documentation](https://developers.cloudflare.com/ai/models/typesafe/jev/), and [Vercel's evaluation documentation](https://vercel.com/docs/ai-gateway/modalities/evaluation) before sharing sensitive content.
-
-## Local data and credentials
-
-Configuration is global and contains credential references, not keys. Setup creates it with mode `0600` where supported. Existing files and symlinks are never overwritten. Credentials are resolved at request time and are not placed in session records. For classification, Pi-managed credential reuse is explicit and forwards only an API key, not provider-specific headers. Generation probes instead use Pi's actual credential providers, including OAuth and custom headers. Credentials may refresh during doctor, subject to Pi's normal credential storage behavior.
-
-Generation proofs and readiness are held only in memory; the router never persists them. The verification identity covers routes, credential references, backend configuration, and model metadata, including changes under unchanged provider/model IDs. Native auth status and provider references contribute to an in-memory hash. No secrets are persisted by the router for verification.
-
-Session custom entries contain route/model IDs, classifier labels/probabilities/confidence, normalized usage, elapsed time, safe failure reasons, and skipped candidates. They do not contain request text, raw responses, HTTP error bodies, or API keys. Pi itself already records ordinary conversation content independently of this extension. There is no extension telemetry or external analytics.
-
-Diagnostics report configuration errors without printing Zod values or filesystem error bodies. Model IDs and config paths are shown locally; do not use secrets as identifiers. Gateway/provider warnings are suppressed rather than printed verbatim.

package/docs/releasing.md

@@ -1,26 +0,0 @@
-# Release checklist
-
-Nothing in this repository publishes automatically. The package name was available during research, but is not reserved. There is no configured remote or maintainer identity yet.
-
-## Before the first release
-
-1. Confirm ownership of the npm name and choose the public Git repository. Add accurate `repository`, `homepage`, and `bugs` metadata to `package.json`.
-2. Confirm the MIT license choice and maintainer identity. Review the public artifact list; research, local paths, tests, and development scripts are not shipped.
-3. Run `npm ci`, `npm run check`, and `npm run smoke:package` on the supported Node/Pi versions. Inspect `npm pack --dry-run`.
-4. With explicit approval for network charges, run `/typesafe-router doctor` for each backend and configured generation target set with least-privilege credentials. Doctor preserves session mode and sends a synthetic classifier request plus one isolated generation probe per distinct provider/model, without confirmation, actual conversation transcript, or tools. It may incur charges even while off or headless with `allowHeadless: false`; token/deadline limits are not a strict monetary cap. Confirm response shape, confidence extraction, permissions, and cancellation. Do not capture keys or raw private state in fixtures. Check the following:
-   - Probes use Pi's `modelRegistry.complete` and actual credential providers, including OAuth refresh, custom headers, and custom endpoints. Options are `tools: []`, `maxTokens: 128` where supported, and `maxRetries: 0`. The top-level `generationProbeTimeoutMs` defaults to 15000 and accepts only integers from 100 through 60000, applied per model.
-   - Readiness requires completed doctor success, including the classifier, and at least one locally eligible, successfully probed candidate in every quick/standard/deep route. Failed targets, including the first configured target, are skipped during later preflight; successful targets retain their configured order.
-   - `on`, `shadow`, and automatic input are blocked without readiness; off/manual Pi use remains available. Doctor does not change the selected model or replay a user task.
-   - Proofs are session-only and never persisted. Restart/reload requires doctor again. Route, credential-reference, backend, and model-metadata changes invalidate verification even under unchanged provider/model IDs. Native auth status/provider references contribute to an in-memory hash without persisting secrets.
-   - Refresh invalidates old proofs, and cancellation or incomplete work never partially unlocks routing. Treat successful probes as health snapshots, not guarantees of future generation success.
-5. Privately evaluate representative tasks. Seek clarification of TypeSafe MCA §2.3(f) before public benchmarks, performance numbers, or comparative claims.
-6. Review privacy disclosures and experimental Vercel limitations. Choose the package version and record changes.
-7. Configure npm trusted publishing for the chosen repository/workflow and an approved release environment. Use OIDC provenance rather than storing a long-lived npm token. This step depends on the final repository identity and is intentionally not preconfigured.
-8. Only after release approval, publish the reviewed artifact with public access and provenance. Verify installation into a clean Pi profile.
-9. Verify discovery in Pi's package gallery. The manifest already has the `pi-package` keyword and `pi.extensions` entry; gallery indexing is external and is not guaranteed by a local test.
-
-The local smoke script installs the packed tarball and Pi into a temporary directory, disables resource discovery and network during extension loading, and checks the registered command through the actual loader. It does not alter the user's Pi settings or installed extensions.
-
-## Ongoing releases
-
-Keep host compatibility explicit. The tested host is Pi 0.85.1; wildcard optional peers avoid bundling a competing runtime but do not imply every Pi version is compatible. Re-characterize lifecycle/auth changes on a new host version. AI SDK evaluation is experimental and pinned; review serialization/metadata tests before upgrading it.