pi-pignon 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.4 — 2026-09-24
+
+- `/pignon login` saves the Jev (TypeSafe) API key, so you no longer have to
+  export `TYPESAFE_API_KEY`. It can store a command that prints the key
+  (Keychain, 1Password, …), so the key never touches the disk, or the key
+  itself in `~/.pi/agent/pignon/credentials.json` (0600; refused when others
+  can read it). The environment variable still wins. `/pignon logout` removes
+  the key. `/pignon init` and the no-config default pick Jev when a key was
+  saved.
+- README: a "Choosing a decider" comparison (latency, cost, privacy, setup),
+  setup steps in the order they run in Pi, and what `/pignon doctor` reports.
+  The configuration reference explains where Jev's key is looked up and how to
+  reach Jev through OpenRouter.
+- The internal `docs/PLAN-*.md` notes are no longer shipped in the package.
+
+## 0.1.3 — 2026-09-24
+
+- No changes from 0.1.2: the same documentation, released from `main`.
+
+## 0.1.2 — 2026-09-24
+
+- The repository moved to `siiick/pi-pignon`, after the npm package. Links and
+  the config's `$schema` URL point there (the old URLs redirect).
+- The README is shorter: the configuration reference moved to
+  `docs/CONFIGURATION.md` and the design notes to `docs/DESIGN.md`, both
+  shipped in the package.
+
 ## 0.1.1 — 2026-09-23
 
 - Published on npm: `pi install npm:pi-pignon`.

package/README.md

@@ -38,12 +38,25 @@ pi install npm:pi-pignon
 ```
 
 `pi update --extensions` keeps it up to date. To pin a version:
-`pi install npm:pi-pignon@0.1.1`. To try unreleased changes:
+`pi install npm:pi-pignon@0.1.4`. To try unreleased changes:
 `pi install git:github.com/siiick/pi-pignon`.
 
-### 1. Give it a decision model
+### Choosing a decider
 
-pignon needs a local **Laya server**, a **Jev API key**, or both.
+pignon needs a decision model: a local **Laya server**, **TypeSafe's Jev**, or both.
+
+| | Laya (`laya-serve`) | Jev |
+|---|---|---|
+| Runs | On your machine (NVIDIA GPU, Apple Silicon or CPU) | TypeSafe's API |
+| Latency | ~75 ms on Apple Silicon | ~70–500 ms |
+| Cost | Free | Paid per decision; shown on each card and in `/pignon-stats` |
+| Privacy | Prompts stay on your machine | The first 4 000 characters of each routed prompt are sent to TypeSafe |
+| Setup | Install and run a server | An API key |
+
+**Both:** Laya first, and Jev only when Laya is down or unsure, with the
+[`sequential` strategy](docs/CONFIGURATION.md#using-several-deciders).
+
+### 1. Start Laya, or save a Jev key
 
 **Local: Laya with `laya-serve`**
 
@@ -55,35 +68,56 @@ LAYA_HOST=127.0.0.1 laya-serve  # http://127.0.0.1:8000
 - Always set `LAYA_HOST=127.0.0.1` (default listens on all interfaces)
 - Loads the best available device (NVIDIA GPU → Apple Silicon → CPU)
 - First start downloads checkpoints and may take a while; later starts take 2–3 s
-- While loading or down, prompts are **not routed** — they keep the current model
+- While loading or down, prompts are **not routed**: they keep the current model
+- To start it at login on macOS, see [the launchd recipe](docs/CONFIGURATION.md#start-laya-serve-at-login-macos)
 
 **Remote: Jev**
 
-Get a key from [TypeSafe](https://typesafe.ai) and export it:
+Get a key from [TypeSafe](https://typesafe.ai), start `pi`, and run:
 
 ```bash
-export TYPESAFE_API_KEY="sk-..."
+/pignon login
 ```
 
-To use OpenRouter instead, see the [configuration reference](docs/CONFIGURATION.md#deciders).
+Pick where the key comes from:
 
-### 2. Restart Pi
+- **A command** that prints it, e.g. `security find-generic-password -ws typesafe`
+  (macOS Keychain) or `op read op://Private/TypeSafe/credential` (1Password).
+  pignon runs it once per session; the key is never written to disk. Recommended.
+- **Paste the key.** It is saved in `~/.pi/agent/pignon/credentials.json`, which
+  only you can read. pignon refuses the file if other users can read it.
 
-```bash
-pi    # or /reload
-```
+`/pignon logout` removes the saved key. In CI, or if you prefer, export
+`TYPESAFE_API_KEY` before starting Pi instead; it takes precedence over a saved
+key. To reach Jev through OpenRouter, see
+[the configuration reference](docs/CONFIGURATION.md#jev-through-openrouter).
+
+### 2. Initialize and check
 
-### 3. Initialize and go live
+In Pi:
 
 ```bash
-/pignon init          # writes ~/.pi/agent/pignon.json
-/pignon doctor        # checks config, deciders and models
-/pignon live          # start routing (default is shadow mode)
+/pignon init          # writes ~/.pi/agent/pignon.json with the deciders it finds
+/reload               # loads the config (and a key saved with /pignon login)
+/pignon doctor        # checks config, deciders and models, with one test decision
 ```
 
 `/pignon init anthropic` (or `openai`, `openrouter`) picks a preset explicitly.
 `init` never overwrites an existing file.
 
+`/pignon doctor` says what is wrong with a decider: laya-serve not running, no
+Jev key, a key rejected by the API, a key command that fails, or a credentials
+file others can read.
+
+### 3. Go live
+
+pignon starts in shadow mode: it shows what it would do on each prompt without
+switching models. When the decisions look right:
+
+```bash
+/pignon live
+```
+
 ## Commands
 
 | Command | Description |
@@ -98,6 +132,7 @@ pi    # or /reload
 | `/pignon config migrate` | Convert a laya-router config to pignon format |
 | `/pignon init [preset]` | Write a starter `pignon.json` |
 | `/pignon doctor` | Check config, deciders and models |
+| `/pignon login` / `logout` | Save or remove the Jev API key |
 | `/pignon-stats` | Show tier × form × confidence histogram |
 | `/pignon-stats compare` | Compare two deciders side-by-side |
 | `/pignon-stats export [path]` | Export decisions as JSON lines |
@@ -154,7 +189,7 @@ Run `/pignon config` to see the resolved table currently in use.
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PIGNON_CONFIG` | `<Pi config dir>/pignon.json` | Config file path |
-| `TYPESAFE_API_KEY` | *(unset)* | Jev API key |
+| `TYPESAFE_API_KEY` | *(unset)* | Jev API key (instead of `/pignon login`) |
 | `TYPESAFE_BASE_URL` | `https://api.typesafe.ai` | Jev API root |
 | `LAYA_HOST`, `LAYA_PORT`, `LAYA_MODELS` | *(varies)* | `laya-serve` startup options |
 
@@ -165,6 +200,9 @@ Full list: [docs/CONFIGURATION.md](docs/CONFIGURATION.md#environment-variables).
 - **Local prompts stay local.** With `laya-serve` on this machine, prompts never
   leave it. Jev (or remote laya-serve) receives the first 4 000 characters;
   cards are marked `☁`.
+- **Keys stay out of the config.** The Jev key comes from `TYPESAFE_API_KEY`
+  or `/pignon login`, never from `pignon.json`, and a saved key is only sent
+  to TypeSafe.
 - **Fail-open.** If a decider is unreachable or fails, the prompt is not routed
   and keeps the current model (a few milliseconds of delay).
 - **Switch cost.** Changing models discards the prompt cache. Downgrades must
@@ -187,7 +225,7 @@ pi install ./         # load the clone in place
 npm run typecheck     # Type check
 npm test              # Unit tests
 npm run test:worker   # Python worker tests
-npm run test:live     # Real decider calls (needs API key)
+npm run test:live     # Real decider calls (needs TYPESAFE_API_KEY and/or laya-serve)
 npm run schema        # Regenerate JSON Schema
 npm run check         # typecheck + tests + worker tests
 ```

package/docs/CONFIGURATION.md

@@ -18,8 +18,8 @@ Run `/pignon config` to see the resolved table currently in use.
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PIGNON_CONFIG` | `<Pi config dir>/pignon.json` | Path of the optional config file |
-| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | Pi's config directory; pignon keeps its config and exports there |
-| `TYPESAFE_API_KEY` | *(unset)* | Jev API key (another variable can be named with `apiKeyEnv`) |
+| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | Pi's config directory; pignon keeps its config, exports and saved key (`pignon/credentials.json`) there |
+| `TYPESAFE_API_KEY` | *(unset)* | Jev API key (another variable can be named with `apiKeyEnv`). Takes precedence over a key saved with `/pignon login` |
 | `TYPESAFE_BASE_URL` | `https://api.typesafe.ai` | Jev API root, when `baseURL` is not set |
 | `TYPESAFE_DEFAULT_MODEL` | `jev-latest` | Jev model, when `model` is not set |
 | `LAYA_ROUTER_CONFIG` | `~/.pi/agent/laya-router.json` | **Legacy:** read only when there is no pignon config |
@@ -28,7 +28,7 @@ laya-serve reads its own `LAYA_*` variables (`LAYA_HOST`, `LAYA_PORT`, `LAYA_MOD
 
 ## Deciders
 
-`deciders` picks the decision model. `/pignon init` writes it for you. Without it, pignon uses the experimental worker when installed, else Jev when `TYPESAFE_API_KEY` is set; it does not look for laya-serve on its own.
+`deciders` picks the decision model. `/pignon init` writes it for you. Without it, pignon uses the experimental worker when installed, else Jev when `TYPESAFE_API_KEY` is set or a key was saved with `/pignon login`; it does not look for laya-serve on its own.
 
 ```json
 {
@@ -46,11 +46,34 @@ laya-serve reads its own `LAYA_*` variables (`LAYA_HOST`, `LAYA_PORT`, `LAYA_MOD
 | | `timeoutMs` | `1500` | Timeout for one decision |
 | `laya-local` | | | [Experimental worker](#experimental-pignons-mlx-worker), see its section |
 | `jev` | `model` | `jev-latest` | Jev version to pin. Confidences are calibrated per version, so pinning keeps your thresholds valid |
-| | `apiKeyEnv` | `TYPESAFE_API_KEY` | Environment variable holding the key. Keys are never read from the config file |
-| | `baseURL` | TypeSafe | `https://openrouter.ai/api` to go through OpenRouter (with `"apiKeyEnv": "OPENROUTER_API_KEY"`) |
+| | `apiKeyEnv` | `TYPESAFE_API_KEY` | Environment variable holding the key. When it is unset, the key saved with `/pignon login` is used, but only when neither `apiKeyEnv` nor `baseURL` is set, so the TypeSafe key never goes elsewhere. Keys are never read from the config file |
+| | `baseURL` | TypeSafe | Another API root, e.g. [OpenRouter](#jev-through-openrouter) |
 | | `timeoutMs` | `1500` | Timeout for one decision |
 | | `maxRetries` | `0` | Retries after a failed call; each gets the full timeout |
 
+### Jev's API key
+
+pignon looks for the key in this order:
+
+1. the environment variable named by `apiKeyEnv` (`TYPESAFE_API_KEY` by default);
+2. the key saved with `/pignon login`, in `<Pi config dir>/pignon/credentials.json`: either the key itself, or a `!command` that prints it (run once per session, e.g. to read the macOS Keychain or 1Password). The file must be readable by you only (`chmod 600`).
+
+`/pignon login` and `/pignon logout` take effect after `/reload`. A saved key is only used for TypeSafe's own API: never with a `baseURL` or `apiKeyEnv` of your own, and never for laya-serve.
+
+### Jev through OpenRouter
+
+Jev is also reachable through OpenRouter. `/pignon login` does not apply there: export your OpenRouter key and name it in the config:
+
+```json
+{
+  "deciders": [
+    { "type": "jev", "baseURL": "https://openrouter.ai/api", "apiKeyEnv": "OPENROUTER_API_KEY" }
+  ]
+}
+```
+
+Run `/pignon doctor` to check that it answers.
+
 ### Using several deciders
 
 List more than one and `strategy` says how they work together:

package/docs/DESIGN.md

@@ -4,6 +4,8 @@
 
 With `laya-serve` on this machine (`127.0.0.1` or `localhost`) or `laya-local`, prompts never leave it. With `jev`, or a laya-serve on another host, the first 4 000 characters of each routed prompt are sent over the network, and decision cards are marked ☁. The SDK's own logging is capped at `warn` and kept in `/pignon log`, so prompts are never logged, even with `TYPESAFE_LOG_LEVEL=debug`.
 
+The Jev key is never read from `pignon.json`, which people share. `/pignon login` saves it in its own file, `<Pi config dir>/pignon/credentials.json`, not in Pi's `auth.json`, which Pi writes under a lock extensions cannot take. The file is written 0600 in a 0700 directory, through a temporary file and a rename, and refused when group or others can read it. It can hold a `!command` instead of the key (Keychain, 1Password…), so the key never touches the disk; the command runs once per session, and its stderr is never shown, since it could echo the key. The environment variable takes precedence, and a saved key is only given to a `jev` decider on TypeSafe's own endpoint, never to a custom `baseURL`, a custom `apiKeyEnv`, or laya-serve.
+
 ## Fail-open
 
 If a decider cannot be reached or a decision fails, the decision is `null` and the extension keeps the current model. A laya-serve that is down refuses the connection at once, so the prompt waits a few milliseconds, not a timeout. The experimental worker loads its model in the background from `session_start`; prompts sent before it is ready are not routed (status shows `model loading — prompt not routed`) rather than held. It stays warm for the session, is reloaded in the background if it crashes, and is stopped on `session_shutdown`. A worker that is not ready within 5 minutes is killed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pignon",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Pi coding agent extension that shifts to the right LLM for each prompt, using a local (Laya) or remote (Jev) decision model to judge task difficulty",
   "keywords": [
     "pi-package",
@@ -27,7 +27,9 @@
     "src",
     "schema",
     "examples",
-    "docs",
+    "docs/CONFIGURATION.md",
+    "docs/DESIGN.md",
+    "docs/assets",
     "CHANGELOG.md"
   ],
   "engines": {
@@ -40,7 +42,7 @@
     "clean": "rm -rf dist node_modules/.vitest",
     "build": "echo 'nothing to build (TypeScript runs via jiti)'",
     "check": "tsc --noEmit && vitest run && npm run test:worker",
-    "test:worker": "cd worker && .venv/bin/python -m unittest",
+    "test:worker": "cd worker && ${PYTHON:-.venv/bin/python} -m unittest",
     "schema": "UPDATE_SCHEMA=1 vitest run tests/schema.test.ts",
     "test:live": "PIGNON_LIVE=1 vitest run tests/live",
     "prepublishOnly": "npm run check"
@@ -61,9 +63,9 @@
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",
     "@earendil-works/pi-tui": "^0.87.1",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0",
+    "@types/node": "^26.6.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1",
     "typebox": "^1.3.34"
   }
 }

package/schema/config.schema.json

@@ -109,7 +109,7 @@
               "apiKeyEnv": {
                 "type": "string",
                 "minLength": 1,
-                "description": "Environment variable holding the API key. Default: TYPESAFE_API_KEY."
+                "description": "Environment variable holding the API key. Default: TYPESAFE_API_KEY, else the key saved with /pignon login (only when neither apiKeyEnv nor baseURL is set)."
               },
               "timeoutMs": {
                 "type": "number",
@@ -129,7 +129,7 @@
       },
       "minItems": 1,
       "maxItems": 4,
-      "description": "Decision models, in the order to try them. Default: laya-local when its experimental worker is installed, else jev when TYPESAFE_API_KEY is set. /pignon init adds laya-serve when it is running."
+      "description": "Decision models, in the order to try them. Default: laya-local when its experimental worker is installed, else jev when TYPESAFE_API_KEY is set or a key was saved with /pignon login. /pignon init adds laya-serve when it is running."
     },
     "strategy": {
       "type": "object",

package/src/config/schema.ts

@@ -147,7 +147,7 @@ export const JevDeciderSchema = Type.Object(
       Type.String({ minLength: 1, description: "API root. `https://openrouter.ai/api` goes through OpenRouter. Default: TypeSafe." }),
     ),
     apiKeyEnv: Type.Optional(
-      Type.String({ minLength: 1, description: "Environment variable holding the API key. Default: TYPESAFE_API_KEY." }),
+      Type.String({ minLength: 1, description: "Environment variable holding the API key. Default: TYPESAFE_API_KEY, else the key saved with /pignon login (only when neither apiKeyEnv nor baseURL is set)." }),
     ),
     timeoutMs: timeoutMs("Timeout for one decision, in milliseconds. Default: 1500."),
     maxRetries: Type.Optional(Type.Integer({ minimum: 0, maximum: 3, description: "Retries after a failed attempt. Default: 0." })),
@@ -165,7 +165,7 @@ export const DecidersSchema = Type.Array(Type.Union([LayaServeDeciderSchema, Lay
   minItems: 1,
   maxItems: 4,
   description:
-    "Decision models, in the order to try them. Default: laya-local when its experimental worker is installed, else jev when TYPESAFE_API_KEY is set. /pignon init adds laya-serve when it is running.",
+    "Decision models, in the order to try them. Default: laya-local when its experimental worker is installed, else jev when TYPESAFE_API_KEY is set or a key was saved with /pignon login. /pignon init adds laya-serve when it is running.",
 });
 
 export const StrategySchema = Type.Object(

package/src/credentials.ts

@@ -0,0 +1,101 @@
+/**
+ * API keys stored by `/pignon login`, for users who would rather not export an
+ * environment variable.
+ *
+ * They live in their own file, `<agent dir>/pignon/credentials.json`, never in
+ * pignon.json (which people share) nor in Pi's auth.json (which Pi writes
+ * under a lock pignon cannot take). The file is created 0600 in a 0700
+ * directory, and refused, like ssh does, when group or others can read it.
+ *
+ * A stored key is either the key itself or, like in Pi's auth.json, a command
+ * prefixed with `!` whose output is the key (`!security find-generic-password
+ * -ws typesafe`): with a password manager, the key never touches the disk.
+ *
+ *   { "typesafe": { "key": "sk-..." } }
+ */
+
+import { exec } from "node:child_process";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { agentDir } from "./config/load.js";
+
+/** Name of the TypeSafe (Jev) key in the credentials file. */
+export const TYPESAFE_CREDENTIAL = "typesafe";
+
+/** A key command gets this long, e.g. to wait for a Keychain or 1Password prompt. */
+const COMMAND_TIMEOUT_MS = 30_000;
+
+export function credentialsPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(agentDir(env), "pignon", "credentials.json");
+}
+
+export type StoredKey =
+  | { kind: "missing" }
+  | { kind: "error"; error: string }
+  /** `value` is the key, or a command (starting with `!`) that prints it. */
+  | { kind: "ok"; value: string };
+
+/** Read one stored key without resolving it. */
+export function readStoredKey(name: string, path: string = credentialsPath()): StoredKey {
+  let text: string;
+  try {
+    const mode = statSync(path).mode;
+    if (process.platform !== "win32" && (mode & 0o077) !== 0) {
+      return { kind: "error", error: `${path} can be read by other users; run chmod 600 on it` };
+    }
+    text = readFileSync(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { kind: "missing" };
+    return { kind: "error", error: `cannot read ${path}: ${(err as Error).message}` };
+  }
+  let entry: unknown;
+  try {
+    entry = (JSON.parse(text) as Record<string, unknown>)[name];
+  } catch {
+    return { kind: "error", error: `${path} is not valid JSON` };
+  }
+  if (entry === undefined) return { kind: "missing" };
+  const value = (entry as { key?: unknown } | null)?.key;
+  if (typeof value !== "string" || !value.trim()) return { kind: "error", error: `${path}: ${name}.key must be a non-empty string` };
+  return { kind: "ok", value: value.trim() };
+}
+
+/** Store (or, with `undefined`, remove) one key, leaving the others. */
+export function writeStoredKey(name: string, value: string | undefined, path: string = credentialsPath()): void {
+  let data: Record<string, unknown> = {};
+  try {
+    data = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+  if (value === undefined) delete data[name];
+  else data[name] = { key: value };
+
+  if (Object.keys(data).length === 0) {
+    rmSync(path, { force: true });
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  // Written aside then renamed: a crash never leaves a half-written file.
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(temp, 0o600);
+  renameSync(temp, path);
+}
+
+/** The key a stored value stands for: the value itself, or what its `!command` prints. */
+export async function resolveStoredKey(value: string): Promise<string> {
+  if (!value.startsWith("!")) return value;
+  const command = value.slice(1).trim();
+  const output = await new Promise<string>((resolve, reject) => {
+    exec(command, { timeout: COMMAND_TIMEOUT_MS, encoding: "utf8" }, (err, stdout) => {
+      // The command's stderr is not quoted: it could echo the key.
+      if (err) reject(new Error(`key command failed (${err.killed ? "timed out" : `exit ${err.code ?? "?"}`})`));
+      else resolve(stdout);
+    });
+  });
+  const key = output.trim();
+  if (!key) throw new Error("key command printed nothing");
+  return key;
+}

package/src/deciders/create.ts

@@ -8,6 +8,7 @@
  * returns an `UnavailableDecider` whose warmup error says what to install.
  */
 
+import { type StoredKey, TYPESAFE_CREDENTIAL, credentialsPath, readStoredKey } from "../credentials.js";
 import type { DeciderSpec, RouterConfig } from "../types.js";
 import { DEFAULT_API_KEY_ENV, JevDecider } from "./jev.js";
 import { LayaWorker, layaRuntimeStatus } from "./laya-local.js";
@@ -26,10 +27,13 @@ export interface CreateDeciderDeps {
   env?: NodeJS.ProcessEnv;
   /** Whether the local worker can run here (tests replace the platform check). */
   layaStatus?: typeof layaRuntimeStatus;
+  /** Reads a key saved by `/pignon login`. Defaults to the credentials file. */
+  storedKey?: (name: string) => StoredKey;
 }
 
 export function createDecider(config: RouterConfig, deps: CreateDeciderDeps = {}): CreatedDecider {
   const env = deps.env ?? process.env;
+  const storedKey = deps.storedKey ?? ((name: string) => readStoredKey(name, credentialsPath(env)));
   const notes: string[] = [];
   let specs = config.deciders;
 
@@ -37,19 +41,19 @@ export function createDecider(config: RouterConfig, deps: CreateDeciderDeps = {}
     const laya = (deps.layaStatus ?? layaRuntimeStatus)(env);
     if (laya.ok) {
       specs = [{ type: "laya-local" }];
-    } else if (env[DEFAULT_API_KEY_ENV]?.trim()) {
+    } else if (env[DEFAULT_API_KEY_ENV]?.trim() || storedKey(TYPESAFE_CREDENTIAL).kind !== "missing") {
       specs = [{ type: "jev" }];
     } else {
       return {
         decider: new UnavailableDecider(
-          `no decider configured: start laya-serve (see pignon's README) and run /pignon init, or set ${DEFAULT_API_KEY_ENV} for Jev`,
+          `no decider configured: start laya-serve (see pignon's README) and run /pignon init, or run /pignon login (or set ${DEFAULT_API_KEY_ENV}) for Jev`,
         ),
         notes,
       };
     }
   }
 
-  const deciders = specs.map((spec) => build(spec, config, env));
+  const deciders = specs.map((spec) => build(spec, config, env, storedKey));
   if (deciders.length === 1) return { decider: deciders[0]!, notes };
   return {
     decider: new StrategyDecider(deciders, config.strategy, (answers, latencyMs) => parseDecision(answers, latencyMs, config)),
@@ -57,7 +61,7 @@ export function createDecider(config: RouterConfig, deps: CreateDeciderDeps = {}
   };
 }
 
-function build(spec: DeciderSpec, config: RouterConfig, env: NodeJS.ProcessEnv): Decider {
+function build(spec: DeciderSpec, config: RouterConfig, env: NodeJS.ProcessEnv, storedKey: (name: string) => StoredKey): Decider {
   switch (spec.type) {
     case "laya-serve":
       return createLayaServeDecider(spec, env);
@@ -69,6 +73,10 @@ function build(spec: DeciderSpec, config: RouterConfig, env: NodeJS.ProcessEnv):
     case "jev":
       return new JevDecider({
         env,
+        // The stored key is TypeSafe's: only for TypeSafe's own endpoint and variable.
+        ...(spec.apiKeyEnv === undefined && spec.baseURL === undefined
+          ? { storedKey: () => storedKey(TYPESAFE_CREDENTIAL) }
+          : {}),
         ...(spec.model !== undefined ? { model: spec.model } : {}),
         ...(spec.baseURL !== undefined ? { baseURL: spec.baseURL } : {}),
         ...(spec.apiKeyEnv !== undefined ? { apiKeyEnv: spec.apiKeyEnv } : {}),

package/src/deciders/jev.ts

@@ -28,6 +28,7 @@ import {
   TypeSafeError,
 } from "@typesafe-ai/sdk";
 
+import { type StoredKey, resolveStoredKey } from "../credentials.js";
 import type { LayaQuestion } from "../types.js";
 import { type Decider, type DeciderResult, type DecisionRequest, DeciderError } from "./types.js";
 
@@ -59,6 +60,12 @@ export interface JevDeciderOptions {
   timeoutMs?: number;
   /** Retries after a failed attempt. Each gets the full timeout. */
   maxRetries?: number;
+  /**
+   * The key saved by `/pignon login`, used when the environment variable is
+   * unset. Only for TypeSafe itself: never set it with another `baseURL` or
+   * `apiKeyEnv`, which would send the TypeSafe key elsewhere.
+   */
+  storedKey?: () => StoredKey;
   /** Where to read the API key and SDK settings. Defaults to `process.env`. */
   env?: NodeJS.ProcessEnv;
   /** HTTP implementation (tests). */
@@ -78,6 +85,8 @@ export class JevDecider implements Decider {
   private readonly timeoutMs: number;
   private readonly logLines: string[] = [];
   private client?: TypeSafeClient;
+  /** A stored key command runs once per session, failed or not: it may prompt the user. */
+  private storedKeyResolution?: Promise<string>;
   private lastModel?: string;
   private stopped = false;
 
@@ -89,9 +98,12 @@ export class JevDecider implements Decider {
     this.timeoutMs = options.timeoutMs ?? DEFAULT_JEV_TIMEOUT_MS;
   }
 
-  /** Ready as soon as an API key is available (or none is needed); there is nothing to load. */
+  /**
+   * Ready as soon as an API key is available (or none is needed); there is
+   * nothing to load. A stored key is ready once `warmup` has resolved it.
+   */
   get isReady(): boolean {
-    return !this.stopped && (this.apiKey() !== undefined || this.options.requireApiKey === false);
+    return !this.stopped && (this.client !== undefined || this.envApiKey() !== undefined || this.options.requireApiKey === false);
   }
 
   /** The model that last answered, else the one requests will name. */
@@ -107,11 +119,11 @@ export class JevDecider implements Decider {
 
   /** Check the API key and build the client. No network call. */
   async warmup(): Promise<void> {
-    this.ensureClient();
+    await this.ensureClient();
   }
 
   async decide(request: DecisionRequest, signal?: AbortSignal): Promise<DeciderResult> {
-    const client = this.ensureClient();
+    const client = await this.ensureClient();
     const started = Date.now();
     try {
       const result = await client.systemOne(
@@ -147,16 +159,37 @@ export class JevDecider implements Decider {
     return this.options.env ?? process.env;
   }
 
-  private apiKey(): string | undefined {
+  private envApiKey(): string | undefined {
     const key = this.env()[this.apiKeyEnv]?.trim();
     return key ? key : undefined;
   }
 
-  private ensureClient(): TypeSafeClient {
+  /** The environment variable first (CI, existing setups), then the stored key. */
+  private async apiKey(): Promise<string | undefined> {
+    const fromEnv = this.envApiKey();
+    if (fromEnv || !this.options.storedKey) return fromEnv;
+    const stored = this.options.storedKey();
+    if (stored.kind === "missing") return undefined;
+    if (stored.kind === "error") throw new DeciderError(`${this.id}: ${stored.error}`);
+    this.storedKeyResolution ??= resolveStoredKey(stored.value);
+    try {
+      return await this.storedKeyResolution;
+    } catch (err) {
+      throw new DeciderError(`${this.id}: ${(err as Error).message}; fix it with /pignon login, then /reload`, err);
+    }
+  }
+
+  private async ensureClient(): Promise<TypeSafeClient> {
+    if (this.stopped) throw new DeciderError(`${this.id}: decider is stopped`);
+    if (this.client) return this.client;
+    const apiKey = (await this.apiKey()) ?? (this.options.requireApiKey === false ? NO_API_KEY : undefined);
+    if (!apiKey) {
+      const hint = this.options.storedKey ? ` (or run /pignon login)` : "";
+      throw new DeciderError(`${this.id}: ${this.apiKeyEnv} is not set${hint}`);
+    }
+    // The key may have taken a while to resolve.
     if (this.stopped) throw new DeciderError(`${this.id}: decider is stopped`);
     if (this.client) return this.client;
-    const apiKey = this.apiKey() ?? (this.options.requireApiKey === false ? NO_API_KEY : undefined);
-    if (!apiKey) throw new DeciderError(`${this.id}: ${this.apiKeyEnv} is not set`);
 
     const env = this.env();
     try {

package/src/extension.ts

@@ -1,9 +1,9 @@
 /**
  * pignon — Pi agent extension.
  *
- * Shifts to the right model for each prompt by asking a decider (today: the
- * local Laya System-1 model, via a stdio worker it spawns and supervises) how
- * hard the prompt is, then looking the answer up in the routing table.
+ * Shifts to the right model for each prompt by asking a decider (a local Laya
+ * model through laya-serve, TypeSafe's hosted Jev, or the experimental worker)
+ * how hard the prompt is, then looking the answer up in the routing table.
  *
  *   /pignon                -> show current mode
  *   /pignon live           -> apply decisions
@@ -15,6 +15,8 @@
  *   /pignon config migrate -> convert a laya-router config file
  *   /pignon init [preset]  -> write a starter config file
  *   /pignon doctor         -> check deciders, models and config
+ *   /pignon login          -> save the TypeSafe (Jev) API key
+ *   /pignon logout         -> remove it
  *   /pignon-stats          -> session statistics
  *   /pignon-stats compare  -> how two deciders agree (parallel strategy)
  *   /pignon-stats export [path] -> decisions as JSON lines
@@ -46,6 +48,7 @@ import { showReport } from "./report.js";
 import { buildStatsLines } from "./stats.js";
 import type { DeciderSpec, RouterConfig, RouterLogEntry, RouterMode } from "./types.js";
 import { hideDeciding, renderDecisionCard, showDeciding } from "./ui.js";
+import { login, logout } from "./login.js";
 import {
   type ModelLookup,
   choosePreset,
@@ -75,6 +78,8 @@ const SUBCOMMANDS = [
   "init",
   ...PRESET_NAMES.map((name) => `init ${name}`),
   "doctor",
+  "login",
+  "logout",
 ];
 
 type PiModel = Parameters<ExtensionAPI["setModel"]>[0];
@@ -337,6 +342,17 @@ export function createExtension(options: ExtensionOptions = {}): (pi: ExtensionA
         await showReport(ctx, "pignon doctor", report.then(([, ...body]) => body));
         return;
       }
+      if (arg === "login") {
+        if (!ctx.hasUI) return;
+        const result = await login(ctx.ui);
+        if (result) notify(ctx, `pignon: ${result.message}`, result.level);
+        return;
+      }
+      if (arg === "logout") {
+        const result = logout();
+        notify(ctx, `pignon: ${result.message}`, result.level);
+        return;
+      }
       if (arg === "config migrate") {
         if (!loaded.legacy) {
           notify(ctx, "pignon: config is already in the pignon format");
@@ -411,7 +427,7 @@ export function createExtension(options: ExtensionOptions = {}): (pi: ExtensionA
       SUBCOMMANDS.filter((v) => v.startsWith(prefix)).map((v) => ({ value: v, label: v }));
 
     pi.registerCommand("pignon", {
-      description: "pignon mode (shadow | live | off | unpin | log | config)",
+      description: "pignon mode and setup (shadow | live | off | unpin | log | config | init | doctor | login | logout)",
       getArgumentCompletions: completions,
       handler: modeCommand,
     });

package/src/login.ts

@@ -0,0 +1,76 @@
+/**
+ * `/pignon login` and `/pignon logout`: save or remove the TypeSafe (Jev) API
+ * key in pignon's credentials file (see `credentials.ts`).
+ *
+ * Pi-free: the dialogs are reached through `LoginUI`.
+ */
+
+import {
+  TYPESAFE_CREDENTIAL,
+  credentialsPath,
+  readStoredKey,
+  resolveStoredKey,
+  writeStoredKey,
+} from "./credentials.js";
+import { DEFAULT_API_KEY_ENV } from "./deciders/jev.js";
+
+/** The part of Pi's UI the login dialogs use. */
+export interface LoginUI {
+  select(title: string, options: string[]): Promise<string | undefined>;
+  input(title: string, placeholder?: string): Promise<string | undefined>;
+}
+
+export type LoginResult = { level: "info" | "warning" | "error"; message: string };
+
+const FROM_COMMAND = "Read it from a command (password manager, Keychain): the key is not written to disk";
+const PASTE = "Paste the key: saved in pignon's credentials file (readable by you only)";
+
+const EXAMPLE_COMMAND =
+  process.platform === "darwin" ? "security find-generic-password -ws typesafe" : "op read op://Private/TypeSafe/credential";
+
+export async function login(
+  ui: LoginUI,
+  env: NodeJS.ProcessEnv = process.env,
+  path: string = credentialsPath(env),
+): Promise<LoginResult | undefined> {
+  const how = await ui.select("How should pignon get your TypeSafe API key?", [FROM_COMMAND, PASTE]);
+  if (how === undefined) return undefined;
+
+  let value: string;
+  if (how === FROM_COMMAND) {
+    const command = (await ui.input("Command that prints the key", EXAMPLE_COMMAND))?.trim().replace(/^!\s*/, "");
+    if (!command) return undefined;
+    value = `!${command}`;
+    try {
+      await resolveStoredKey(value);
+    } catch (err) {
+      return { level: "error", message: `${(err as Error).message}; nothing saved` };
+    }
+  } else {
+    const key = (await ui.input("TypeSafe API key", "paste the key"))?.trim();
+    if (!key) return undefined;
+    if (/\s/.test(key)) return { level: "error", message: "an API key has no spaces; nothing saved" };
+    value = key;
+  }
+
+  try {
+    writeStoredKey(TYPESAFE_CREDENTIAL, value, path);
+  } catch (err) {
+    return { level: "error", message: `could not write ${path}: ${(err as Error).message}` };
+  }
+  const shadowed = env[DEFAULT_API_KEY_ENV]?.trim() ? ` ${DEFAULT_API_KEY_ENV} is set and is used first.` : "";
+  return { level: shadowed ? "warning" : "info", message: `saved the TypeSafe key in ${path}; /reload to use it.${shadowed}` };
+}
+
+export function logout(env: NodeJS.ProcessEnv = process.env, path: string = credentialsPath(env)): LoginResult {
+  if (readStoredKey(TYPESAFE_CREDENTIAL, path).kind === "missing") {
+    return { level: "info", message: "no TypeSafe key saved" };
+  }
+  try {
+    writeStoredKey(TYPESAFE_CREDENTIAL, undefined, path);
+  } catch (err) {
+    return { level: "error", message: `could not write ${path}: ${(err as Error).message}` };
+  }
+  const still = env[DEFAULT_API_KEY_ENV]?.trim() ? ` ${DEFAULT_API_KEY_ENV} is still set.` : "";
+  return { level: "info", message: `removed the saved TypeSafe key; /reload to apply.${still}` };
+}

package/src/onboarding.ts

@@ -10,6 +10,7 @@ import { dirname } from "node:path";
 
 import { type PresetName, PRESETS, PRESET_NAMES } from "./config/presets.js";
 import { CONFIG_SCHEMA_URL } from "./config/schema.js";
+import { type StoredKey, TYPESAFE_CREDENTIAL, credentialsPath, readStoredKey } from "./credentials.js";
 import { DEFAULT_API_KEY_ENV } from "./deciders/jev.js";
 import { type WorkerLaunch, layaRuntimeStatus } from "./deciders/laya-local.js";
 import { probeLayaServe } from "./deciders/laya-serve.js";
@@ -49,16 +50,17 @@ export function choosePreset<M>(lookup: ModelLookup<M>): PresetName {
 /**
  * The decider to start with, local first: a running laya-serve on its default
  * address, else the experimental worker when installed, else Jev when its key
- * is set.
+ * is set or saved by `/pignon login`.
  */
 export async function detectDeciders(
   env: NodeJS.ProcessEnv = process.env,
   layaStatus: typeof layaRuntimeStatus = layaRuntimeStatus,
   probe: () => Promise<boolean> = () => probeLayaServe(),
+  storedKey: (name: string) => StoredKey = (name) => readStoredKey(name, credentialsPath(env)),
 ): Promise<DeciderSpec[]> {
   if (await probe()) return [{ type: "laya-serve" }];
   if (layaStatus(env).ok) return [{ type: "laya-local" }];
-  if (env[DEFAULT_API_KEY_ENV]?.trim()) return [{ type: "jev" }];
+  if (env[DEFAULT_API_KEY_ENV]?.trim() || storedKey(TYPESAFE_CREDENTIAL).kind !== "missing") return [{ type: "jev" }];
   return [];
 }
 

package/docs/PLAN-command-output.md

@@ -1,161 +0,0 @@
-# Plan (pignon): command output that is not truncated and does not persist
-
-Status: implemented · 2026-09-23 (see *Changes from the proposal*)
-
-## Problem
-
-`/pignon doctor` (and `config`, `log`, `stats`) render through `ctx.ui.setWidget(key, string[])`.
-Two consequences, both bad UX:
-
-1. **Truncated.** Pi keeps only the first 10 lines of a string-array widget and appends
-   `... (widget truncated)`. Doctor emits ~15–25 lines, so the model checks — the part the
-   user ran the command for — are silently dropped.
-2. **Persists.** A widget is a persistent slot: it stays above the editor through every
-   following prompt until `setWidget(key, undefined)`, i.e. until `/pignon doctor clear`.
-
-## Why it happens (verified in the Pi source)
-
-`@earendil-works/pi-coding-agent` 0.87.1, `InteractiveMode` in
-`dist/bundle/chunks/chunk-OJP47DM6.js`:
-
-```js
-if (Array.isArray(content)) {
-  let container = new Container;
-  for (let line of content.slice(0, _InteractiveMode.MAX_WIDGET_LINES))
-    container.addChild(new Text(line, 1, 0));
-  content.length > _InteractiveMode.MAX_WIDGET_LINES &&
-    container.addChild(new Text(theme.fg("muted", "... (widget truncated)"), 1, 0));
-  component = container;
-} else component = content(this.ui, theme);   // factory overload: no cap
-```
-
-with `static MAX_WIDGET_LINES = 10`.
-
-The cap applies **only** to the `string[]` overload. The component-factory overload is
-uncapped — `src/ui.ts` already relies on that for the `pignon-deciding` spinner.
-
-Corroborated by a third-party extension (`itayinbarr/little-coder`,
-`.pi/extensions/extensions-info/manifest.ts`):
-
-> pi slices a string-array widget to MAX_WIDGET_LINES (10) and appends
-> "... (widget truncated)", so anything past that is silently lost.
-
-Persistence is by design, not a bug: `docs/tui.md` lists `ctx.ui.setWidget()` under
-*"Persistent content near the editor"*. The fix is therefore to stop using a widget for
-one-shot reports, not to tune the widget.
-
-## What each command emits today
-
-| command | lines | vs the 10-line cap |
-| --- | --- | --- |
-| `doctor` | ~15–25: header, `config` + 1–2, `deciders` + 1–3, `models` + up to 8 | truncated |
-| `log` | 30 (`LOG_WIDGET_LINES`) | truncated to 10 — worst case |
-| `stats` | ~12+: header, bucket header, 3 tiers × 2 forms, summary | truncated |
-| `config` | ~8: header, column header, N tiers, footer, hint | ok at 3 tiers, truncates at 4+ |
-
-## Decision
-
-Render one-shot reports in a **dismissible overlay** (`ctx.ui.custom({ overlay: true })`)
-that scrolls itself: no line cap, scrollable, disposed on close so nothing persists.
-Fallback to `notify` in RPC mode and to stderr in print/JSON mode.
-
-Apply it to **all four** commands through one shared helper.
-
-## Design
-
-### `src/report.ts` (new)
-
-```ts
-export async function showReport(
-  ctx: ExtensionContext,
-  title: string,
-  lines: string[] | Promise<string[]>,
-): Promise<void>
-```
-
-Three tiers, following `docs/extensions.md` (*"Guard terminal-only behavior with
-`ctx.mode === "tui"` and use `ctx.hasUI` for interactions supported by interactive and RPC
-clients"*):
-
-| mode | behaviour |
-| --- | --- |
-| `ctx.mode === "tui"` | `ctx.ui.custom(..., { overlay: true })` — `ReportOverlay` below |
-| RPC (`ctx.hasUI`, not tui) | `ctx.ui.notify(lines.join("\n"), "info")` — RPC forwards `notify`, not custom components |
-| print / JSON (`!ctx.hasUI`) | `process.stderr.write(lines.join("\n") + "\n")` — stdout stays parseable in JSON mode |
-
-The `Promise<string[]>` overload matters for `doctor`, which can block ~15 s on the decider
-probe: open the overlay immediately with `running checks…`, then `setLines()` →
-`invalidate()` + `tui.requestRender()` when it resolves. The editor is never left looking
-frozen.
-
-### `ReportOverlay`
-
-A `Component` (`render(width)` / `handleInput(data)` / `invalidate()` / `dispose()`):
-
-- Keeps its own line offset and renders only the visible slice, framed by a
-  rounded border: title in the top rule; hint and `a–b/n` position in the bottom rule
-- Body height: 70% of `tui.terminal.rows` (read on each render) minus the 2 border rows
-- Overlay options: `{ width: <widest line + frame>, minWidth: 40, anchor: "center", margin: 1 }`;
-  `90%` while doctor's lines are still pending (Pi resolves overlay options once, at open)
-- Keys: ↑↓ / `j` `k` (line), PgUp / PgDn / space (page), Home / End / `g` `G`,
-  `Esc` / `q` / `Enter` → `done()`
-- Every line passes through `truncateToWidth(…, pad)` — see Risks
-
-## Files
-
-| file | change |
-| --- | --- |
-| `src/report.ts` | **new** — `showReport()` + `ReportOverlay` |
-| `src/extension.ts` | replace the 4 report `showWidget(...)` calls with `showReport(...)`; drop the `"(/pignon X clear to hide)"` trailers; raise `LOG_WIDGET_LINES` 30 → 200 (the overlay scrolls) |
-| `src/config/describe.ts` | drop its internal `"(/pignon config clear to hide)"` line |
-| `src/ui.ts` | unchanged — `showDeciding` is *meant* to persist, and already uses the uncapped factory overload |
-| `src/onboarding.ts` | unchanged — already returns plain `string[]` |
-| `tests/extension.test.ts`, `tests/extension-routing.test.ts` | add `custom` and `mode` to the mocks; update the `ctx.ui.setWidget` assertions |
-| `tests/report.test.ts` | **new** — overlay line rendering and key handling (pure, no terminal) |
-| `tests/helpers/fake-report.ts` | **new** — a `ctx.ui.custom` fake that keeps the overlay for assertions |
-| `src/stats.ts`, `src/compare.ts` | drop their `"(/pignon-stats clear to hide)"` lines |
-| `README.md`, `CHANGELOG.md` | the four commands no longer need `clear`; keep the subcommands as no-ops for back-compat |
-
-## Steps
-
-1. Write `src/report.ts`: `ReportOverlay` (Box + ScrollView + Text) and `showReport()`.
-2. Rewire `doctor`, `config`, `log`, `stats` in `src/extension.ts`; remove the "clear to
-   hide" trailers.
-3. Extend the test mocks with `custom` and `mode`, then update and add tests.
-4. Update README and CHANGELOG.
-
-## Risks
-
-- **Width overflow.** pi-tui throws on over-wide lines (reported upstream as issue #48 by
-  `little-coder`). `truncateToWidth()` on every line is load-bearing, not cosmetic.
-- **Modal.** `doctor` now needs `Esc` before the user can type again. Accepted: it is a
-  diagnostic, and it is the cost of nothing persisting.
-- **Key collision.** `matchesKey(data, "q")` is safe here only because the overlay has no
-  text input. Any future search/filter field inside it must handle `q` as text first.
-- **Back-compat.** `doctor clear` / `config clear` / `stats clear` / `log clear` stay
-  accepted and keep clearing the (now unused) widget key so a stale widget from an older
-  session cannot linger.
-
-## Changes from the proposal
-
-- **No `ScrollView`.** Pi composites overlays in `TUI.compositeOverlays()`
-  (`pi-tui/dist/tui.js`): it calls `component.render(width)` and slices the result to
-  `maxHeight`. The `[LAYOUT_NODE]` / `updateLayout` path runs only in
-  `renderLayoutFrame()` for the alt-screen root, never for overlays, and
-  `ScrollView.render()` returns all of its child's lines. A `ScrollView` in an overlay
-  would therefore never scroll, and `maxHeight: "70%"` would truncate it silently: the
-  same bug with a border around it. `ReportOverlay` scrolls itself instead.
-- **Overlay options go under `overlayOptions`**, not at the top level of the `custom()`
-  options.
-- **Width fits the content** instead of a fixed 80%, which truncated the config table's
-  last column at 100 columns.
-- **Five call sites, not four**: `/pignon-stats compare` also used the widget. `stats.ts`
-  and `compare.ts` had their own "clear to hide" lines too.
-- **Titles move into the border.** Each report's first line (`pignon doctor`,
-  `pignon config · <source>`, …) becomes the overlay title. The producers are unchanged,
-  so RPC and stderr output still start with it.
-- `clear` subcommands are no longer offered in completion, but are still accepted.
-- A rejected `lines` promise shows `✗ <message>` in the overlay instead of leaving
-  `running checks…` forever.
-- Verified in Pi 0.87.1 through a pty: config and doctor render whole, doctor scrolls on a
-  14-row terminal, and Esc leaves nothing above the editor.

package/docs/PLAN-deciders.md

@@ -1,327 +0,0 @@
-# Plan (pignon): pluggable deciders (local Laya + remote Jev) and a user-defined routing table
-
-Status: proposal · 2026-09-23
-
-## Goals
-
-1. **Remote decider.** Route with TypeSafe's Jev (hosted, via `@typesafe-ai/sdk`) as well
-   as the local Laya worker. Jev is used as a *fallback*: when Laya is unavailable, errors,
-   or answers below a confidence floor.
-2. **User-owned routing table.** Move the model map and the difficulty tiers out of
-   `types.ts` into config. Users name their own models and write their own ordered list of
-   difficulty tiers (2..N, with the criterion text sent to the decider).
-3. **Publishable.** Easy setup, a schema-checked config, docs, tests, and modules small
-   enough to read one at a time.
-
-Non-goals (for now): fine-tuning Laya, per-project config, and asking questions other than
-tier and form.
-
-## What stays the same
-
-- The routing policy (`policy.ts`) keeps its algorithm: confidence gates, cooldown, payback
-  and cache guard, fail-open.
-- Pi wiring: modes (shadow/live/off), manual pin, decision cards, `/pignon-stats` (renamed from `/laya*`, kept as aliases for one release).
-- The Laya worker protocol and the Python worker. Only the TS client moves.
-- Prompt privacy on the local path (the hash and length are logged, never the text).
-
-## Facts that constrain the design (from the SDK v0.6.0 `.d.ts`)
-
-| Fact | Consequence |
-|---|---|
-| `TypeSafeClient({ apiKey, baseURL, defaultModel, timeout, retry, logger, logLevel, fetch })` | `fetch` can be injected, so tests need no network. `baseURL: "https://openrouter.ai/api"` + an OpenRouter key also works. |
-| Env fallbacks: `TYPESAFE_API_KEY`, `TYPESAFE_BASE_URL`, `TYPESAFE_DEFAULT_MODEL` | Nothing to configure for the common case. |
-| `timeout` applies **per attempt**, default 2 retries, no total budget | Set `retry.maxRetries: 0` (or 1) and bound the whole call with our own `AbortSignal.timeout`. |
-| Default logger is `console`, and `debug` logs request **bodies** | Pass our own logger (into the `/pignon log` ring buffer), cap `logLevel` at `warn`, so nothing draws over the TUI and prompts never reach logs. |
-| `ChoiceResponse` = `{ choice, confidence, probabilities }`, **no `type` field** | The shared parser must not require `type === "choice"` (the local worker's `choiceOf` does today). |
-| `usage` has tokens; cost comes back at runtime but is not typed | Record `costUsd` when present and show it in stats. |
-| 70–500 ms latency, 32k-token state limit, input-billed | Separate timeout per decider (Jev ≈ 1500 ms). Keep the 4 000-char prompt cap for both deciders. |
-| Error classes: `AuthenticationError`, `RateLimitError`, `APITimeoutError`, `APIUserAbortError`… | Map them to short status texts ("jev: bad API key", "jev: rate limited"). |
-
-## Architecture
-
-```
-            ┌──────────────── extension.ts (Pi wiring only) ────────────────┐
-prompt ───► │ router.ts: routePrompt()                                      │
-            │   deciders/*  ──► RoutingDecision ──► policy.decide() ──► setModel
-            └───────────────────────────────────────────────────────────────┘
-
-deciders/
-  types.ts        Decider interface, DecisionQuestions, RawAnswers
-  questions.ts    build the tier/form questions from config (single source)
-  parse.ts        RawAnswers → RoutingDecision (shared, tolerant)
-  laya-local.ts   LayaWorker (today's laya-worker.ts) implementing Decider
-  jev.ts          TypeSafeClient adapter implementing Decider
-  fallback.ts     FallbackDecider: tries deciders in order, escalating on low confidence
-  create.ts       factory: config → Decider
-```
-
-### The `Decider` seam
-
-```ts
-export interface Decider {
-  readonly id: string;                 // "laya-local" | "jev" | "fallback(laya-local→jev)"
-  readonly label: string;              // shown on the spinner and card, e.g. "jev-1.13.0"
-  readonly isReady: boolean;           // local: model warm; remote: key present
-  readonly remote: boolean;            // prompt leaves the machine → shown on the card
-  warmup(signal?: AbortSignal): Promise<void>;
-  decide(q: DecisionQuestions, text: string, signal: AbortSignal): Promise<DeciderResult>;
-  stop(): void;
-  readonly recentLogs: readonly string[];
-}
-
-export interface DeciderResult {
-  answers: RawAnswers;                 // { reasoning_demand: {choice, confidence}, needs_exploration: … }
-  deciderId: string;                   // which decider actually answered
-  model: string;                       // checkpoint / jev model version
-  latencyMs: number;
-  costUsd?: number;
-  attempts: Attempt[];                 // one per decider tried (for the card and stats)
-}
-```
-
-`parse.ts` turns `answers` into `RoutingDecision` against the **configured** tier ids, so the
-policy never sees decider-specific shapes.
-
-### Fallback semantics (`FallbackDecider`)
-
-Config order is the try order. For each decider:
-
-1. Skip it if it is not ready (e.g. Laya still loading) → record `skipped: not ready`.
-2. Call it with its own timeout, under the caller's signal.
-3. Accept the answer if `tierConfidence >= escalateBelow` **or** it is the last decider.
-4. Otherwise escalate: record the attempt and try the next one.
-
-If every decider fails, rethrow → the policy fails open (as today). When the last decider
-answers with *lower* confidence than an earlier one, keep the most confident answer. An
-overall `budgetMs` (default 3000) caps total latency, so a slow Laya plus a slow Jev cannot
-stall a prompt.
-
-Defaults: `escalateBelow: 0.75`, and escalate on error and on not-ready.
-
-## Configuration (v2)
-
-One JSON file, as today (`~/.pi/agent/pignon.json` or `$PIGNON_CONFIG`; the old `laya-router.json` is read as a fallback with a rename hint). Every
-key is optional; defaults reproduce today's behavior exactly.
-
-```jsonc
-{
-  "$schema": "https://unpkg.com/pignon/schema/config.schema.json",
-  "version": 2,
-
-  // 1. Deciders, in fallback order
-  "deciders": [
-    { "type": "laya-local", "timeoutMs": 2500 },               // optional: model, python, workerDir…
-    { "type": "jev", "timeoutMs": 1500, "model": "jev-1.13.0" } // apiKey from TYPESAFE_API_KEY
-  ],
-  "strategy": { "mode": "sequential", "escalateBelow": 0.75 },   // see "Decision strategies"
-
-  // 2. Model aliases: define once, reference by name
-  "models": {
-    "flash":    { "provider": "openrouter", "modelId": "deepseek/deepseek-v4-flash-0731", "thinking": "off" },
-    "flash-41": { "provider": "openrouter", "modelId": "deepseek/deepseek-v4.1-flash", "thinking": "low" },
-    "glm":      { "provider": "openrouter", "modelId": "z-ai/glm-5.3", "thinking": "high" },
-    "hy4":      { "provider": "openrouter", "modelId": "tencent/hy4-preview", "thinking": "low" }
-  },
-
-  // 3. Difficulty tiers, easiest first. The criterion is what the decider reads.
-  "tiers": [
-    { "id": "trivial",  "criterion": "Mechanical edit, rename, formatting, or a single factual lookup",
-      "model": "flash", "explorationAllowed": false },
-    { "id": "standard", "criterion": "Localized change across a few files with clear intent",
-      "model": "flash-41" },
-    { "id": "hard",     "criterion": "Multi-step investigation, debugging with unclear cause, or cross-cutting design",
-      "direct": "glm", "exploration": "hy4" }
-  ],
-
-  // Optional wording overrides; bump questionsVersion whenever you edit criteria.
-  "questions": { "version": "q1", "tierInstructions": "…", "explorationInstructions": "…" },
-
-  "thresholds": { "minConfidenceDowngrade": 0.85 }
-}
-```
-
-Rules:
-
-- A tier gives either `model` (both forms) or `direct` + `exploration`. A value can be an
-  alias or an inline `{ provider, modelId, thinking }`.
-- `explorationAllowed: false` generalizes today's hard-coded "exploration forbids trivial"
-  rule: an exploration task at that tier goes up to the next tier that allows it.
-- Need 2..8 tiers with unique ids. Unknown alias → error naming the tier.
-- `version` missing + the old `tiers: { hard: { direct: … } }` object shape → migrate in
-  memory and notify once ("config uses v1 format; run `/pignon config migrate`").
-- Invalid config: same contract as today. Report it on session start, fall back per
-  section, never block loading.
-- **Secrets never go in the file.** `jev.apiKeyEnv` (default `TYPESAFE_API_KEY`) names the
-  variable. A literal `apiKey` is rejected with a message.
-
-### Validation
-
-Use TypeBox (see "Validation with TypeBox" below). The schema module is the single source
-for the TS types, the runtime checks, and `schema/config.schema.json`.
-
-### Presets and onboarding
-
-- `presets/openrouter.json` (today's table), `presets/anthropic.json`, `presets/openai.json`.
-  Config can say `"extends": "openrouter"` and override only what differs.
-- `/pignon init [preset]` writes a starter config (it refuses to overwrite an existing file),
-  lists the models from `ctx.modelRegistry` that resolve, and flags those that do not.
-- `/pignon doctor` checks each decider (worker venv present? Apple Silicon? key set? one test
-  `decide` round-trip) and each table model (in registry? auth?), with one ✓/✗ line per check.
-- `/pignon config` shows the resolved table (tier × form → model · thinking) and its source.
-
-## Code changes, file by file
-
-| File | Change |
-|---|---|
-| `src/types.ts` | Drop `Tier` union, `DEFAULT_TIERS`, `TIER_ORDER`; keep protocol + policy types. `Profile.tier: TierId` (string). Add `DeciderAttempt`, extend `RouterLogEntry` with `decider`, `escalated`, `attempts`, `costUsd`, `questionsVersion`. |
-| `src/config/schema.ts` | TypeBox schema, v1→v2 migration. |
-| `src/config/load.ts` | Today's `loadConfig` (file read, error collection) on top of the schema; resolves `extends` and aliases into a `ResolvedConfig` whose `table` is an ordered array. |
-| `src/config/defaults.ts` | Default models, tiers, and deciders (`[laya-local]` so behavior does not change on upgrade). |
-| `src/deciders/*` | See the architecture section. `laya-worker.ts` moves to `deciders/laya-local.ts` with its public API unchanged, plus a thin `Decider` adapter. |
-| `src/policy.ts` | Tier order comes from `config.table` (index = rank). The trivial/exploration rule reads `explorationAllowed`. `profileFromModel` takes the table. |
-| `src/router.ts` | New: `routePrompt` + `buildLogEntry` pulled out of `extension.ts` (Pi-free except for a small `RouterHost` interface: `findModel`, `setModel`, `setThinking`, `contextTokens`), so it can be tested without Pi mocks. |
-| `src/extension.ts` | Wiring only: build the decider from config, register hooks and commands. Spinner/status text use `decider.label`. |
-| `src/ui.ts` | Card head shows the decider that answered (`laya` / `jev ☁`), escalation (`laya 0.62 → jev 0.91`), and cost. Stats grid rows come from the config tiers. |
-| `package.json` | `@typesafe-ai/sdk` and `typebox` in `dependencies`; `files`, `license`, `repository`, `keywords: ["pi-package", "pi-extension"]`; drop `private`. |
-
-The old `~/.pi/agent/extensions/jev-router` becomes redundant: its behavior equals
-`deciders: [{ "type": "jev" }]`. Remove it after migration so two routers don't both fire.
-
-## Tests
-
-| Suite | Covers |
-|---|---|
-| `deciders/contract.test.ts` | One shared suite run against every `Decider` (Laya via a fake spawn, Jev via an injected `fetch`): ready/not-ready, abort, timeout, malformed answers, `stop()`. |
-| `deciders/jev.test.ts` | Request body (questions from config, 4 000-char cap, model pin); SDK errors → short messages; `maxRetries` 0; no console output; cost parsing; missing key → `isReady=false`, never throws at construction. |
-| `deciders/fallback.test.ts` | Escalation on low confidence, error, and not-ready; keeps the best answer; overall budget; caller abort stops the chain; `attempts` recorded. |
-| `config/*.test.ts` | Schema accept/reject tables, alias resolution, `extends`, v1 migration, literal-apiKey rejection, per-section fallback, JSON Schema file up to date. |
-| `policy.test.ts` | Existing 38 cases kept, parameterized over a 2-tier and a 4-tier table; `explorationAllowed`. |
-| `router.test.ts` | End-to-end through `RouterHost` fakes (moves most of `extension-routing.test.ts`). |
-| `extension.test.ts` | Commands incl. `init`, `doctor`, `config`. |
-| `live.test.ts` | Skipped unless `TYPESAFE_API_KEY` is set (`npm run test:live`): one real Jev call checks the response shape still matches the parser. |
-
-`npm run check` = typecheck + unit + worker tests + schema freshness. No network in `check`.
-
-## Docs
-
-- `README.md`, restructured: 60-second quickstart (Jev only: set the key, `/pignon init`,
-  `/pignon live`), then "Add the local Laya model (Apple Silicon)", then Configuration
-  reference, Commands, How routing decides, Privacy, Troubleshooting (`/pignon doctor`).
-- **Privacy section:** local Laya keeps prompts on the machine. Jev sends the first 4 000
-  characters of each routed prompt to TypeSafe (or OpenRouter). The card marks remote
-  decisions with ☁.
-- `docs/configuration.md`: every key, generated tables from the schema descriptions.
-- `docs/writing-tiers.md`: how to write criteria, why to bump `questions.version`, and how
-  to calibrate thresholds from `/laya-stats` in shadow mode.
-- `CHANGELOG.md`, `LICENSE`, and `examples/*.json`.
-
-## Phases (each ends green on `npm run check`)
-
-1. ✅ **Seam, no behavior change.** `git init`; add the `Decider` interface; wrap `LayaWorker`;
-   move parsing to `parse.ts`; extract `router.ts`. Existing tests keep passing.
-2. ✅ **Configurable table.** TypeBox schema, aliases, ordered tiers, questions built from config,
-   v1 migration, dynamic tiers in policy/UI/stats.
-3. ✅ **Jev decider.** SDK adapter, error mapping, logger/retry hardening, contract + unit tests.
-4. ✅ **Strategies.** sequential + parallel, budget, `/pignon-stats compare|export`, attempts on card and log, stats
-   per decider (escalation rate, cost).
-5. ✅ **Onboarding.** Presets + `extends`, `/pignon init|doctor|config`, JSON Schema generation.
-6. ✅ **Publish.** ~~PyPI `pignon-laya` + uvx launcher~~ (dropped, see below) + protocol check, docs, package metadata, live test,
-   `npm pack` dry-run, and a test install into a clean `~/.pi` via `pi install`/symlink. Retire `jev-router`.
-   Released as git tag `v0.1.0` (`pi install git:github.com/siiick/pignon@v0.1.0`); npm is deferred, the package
-   is ready for it (only the Pi package gallery needs npm).
-7. ✅ **laya-serve.** `laya-serve` decider over the Jev client (no key, local when on loopback), detected by
-   `/pignon init`, documented as the way to run Laya locally; `laya-local` becomes experimental.
-
-## Decision (2026-09-23): laya-serve instead of publishing pignon-laya
-
-The official `laya` package already ships `laya-serve`, a server speaking Jev's
-`POST /v1/systemone`. Benchmarked through pignon's own deciders on 12 prompts × 5 rounds:
-same tier and exploration answers on 12/12 (probabilities equal to ~0.001), p50 75 ms
-against 61 ms for the MLX worker, 2–3 s restart (18 s on the very first run), 712 MB
-installed against 258 MB. A stopped server refuses connections within milliseconds, so
-prompts are never held. Publishing our own package would duplicate it for ~14 ms, so
-`pignon-laya` stays in the repository, unpublished (PyPI's `Private :: Do Not Upload`
-classifier), and the uvx launcher is removed. A `serve` command upstream in laya-mlx
-would bring MLX speed to everyone; to propose there.
-
-## Decisions (2026-09-23)
-
-1. **Default deciders.** Laya if its runtime can start, else Jev if a key is set, else a
-   status that says "no decider, run `/pignon doctor`". Resolved once per session, and
-   `/pignon config` shows which one was picked.
-2. **Name: `pignon`** (the sprocket on a bike cassette: the router changes sprockets between tiers). npm `pignon`, PyPI `pignon-laya`, commands `/pignon` and `/pignon-stats`, config `~/.pi/agent/pignon.json`, env prefix `PIGNON_` (`LAYA_*` stays for the worker itself).
-3. **Validation: TypeBox**, not zod (see below).
-4. **Both strategies**, `sequential` and `parallel`, with a comparison view for benchmarking.
-
-## Validation with TypeBox (replaces the zod section)
-
-TypeBox 1.x (`typebox` on npm, 1.3.x; Pi itself depends on 1.3.27) builds schemas that
-*are* JSON Schema objects:
-
-- Types: `Static<typeof ConfigSchema>`.
-- Checking: `Compile(ConfigSchema)` from `typebox/compile`. Its `.Errors(value)` gives
-  instance paths for the notify message.
-- JSON Schema: `npm run schema` writes `JSON.stringify(ConfigSchema, null, 2)` to
-  `schema/config.schema.json`. No converter needed. A test fails if the file is stale.
-- Add `typebox` as our own `dependency` (range `^1.3.27`). It is not hoisted from Pi.
-
-## Decision strategies
-
-```jsonc
-"deciders": [ { "type": "laya-local" }, { "type": "jev" } ],
-"strategy": {
-  "mode": "sequential",          // or "parallel"
-  "escalateBelow": 0.75,         // sequential: try the next decider below this confidence
-  "pick": "most-confident",      // parallel: "most-confident" | "first" (list order wins when it answers)
-  "budgetMs": 3000               // both modes: total wall time
-}
-```
-
-- **sequential** (default): the fallback behavior above. Cheapest; Jev is only called
-  when needed.
-- **parallel**: every ready decider runs at once under `budgetMs`. The router then uses
-  one answer, chosen by `pick`. With `pick: "first"`, Laya stays authoritative and Jev
-  only runs alongside it for comparison: this is the benchmarking setup. Note that every
-  routed prompt then costs a Jev call and sends the prompt out.
-- Every attempt is logged (`decider`, `model`, tier, confidences, latency, cost, error), so
-  the data is the same in both modes.
-- `/pignon-stats compare` shows, over the session's parallel decisions, the tier agreement rate
-  and a Laya × Jev confusion matrix, the form agreement rate, mean confidence per decider,
-  p50/p95 latency, and total Jev cost. `/pignon-stats export` writes the attempts as JSONL
-  (hashes, not prompts) for offline analysis or future fine-tuning labels.
-
-## Distributing the optional Laya runtime
-
-Laya needs Python, `laya-mlx` (MLX), and Apple Silicon. Most users of a published
-extension will have none of these. So the runtime must be **opt-in**, **outside the npm
-package**, and it **must survive extension updates**.
-
-| Option | Verdict |
-|---|---|
-| Ship `worker/` in the npm package; user runs `uv sync` inside `node_modules/…` | ✗ The venv is hidden, is wiped on every update, and the absolute paths break (already an issue today with `rsync`). |
-| Prebuilt binary (PyInstaller) as an optional npm dependency | ✗ MLX + Metal make it large, it needs code signing and notarization, and it rebuilds on every laya-mlx release. |
-| Docker | ✗ No Metal GPU in containers on macOS. |
-| **Separate PyPI package, launched with `uvx`** | ✓ Recommended. |
-
-**Recommended design:**
-
-- Publish `worker/` to PyPI as `pignon-laya` (`[project.scripts] pignon-laya = "laya_worker:main"`,
-  dependency `laya-mlx`). It is a separate release artifact with its own version, and it
-  lives in the same repo.
-- The npm package does **not** include `worker/` (`files` whitelist).
-- Launch order in the `laya-local` decider:
-  1. `command` in config (dev: `["uv", "run", "--project", "./worker", "pignon-laya"]`);
-  2. `pignon-laya` on `PATH` (for `uv tool install pignon-laya` or `pipx`);
-  3. `uvx --from pignon-laya==<compatible range> pignon-laya`. It installs nothing up
-     front, uv caches the environment outside the extension, and it survives npm updates;
-  4. none of these → `isReady = false` with a clear reason; the strategy skips it.
-- **Protocol handshake:** the `ready` line already carries `PROTOCOL_VERSION` (0.3.0).
-  The extension declares the major version it accepts and refuses a mismatch with an
-  "upgrade with `uv tool upgrade pignon-laya`" message instead of misparsing.
-- **Platform gate:** on anything other than `darwin`/`arm64`, the decider reports
-  "unsupported platform" without trying to spawn anything.
-- **Onboarding:** `/pignon laya install` runs `uv tool install pignon-laya` and then a warmup
-  (the first checkpoint download is about 850 MB; progress goes to the log widget). It
-  asks first and needs `uv` (doctor links to the uv installer).
-- **Worker tests** stay in the Python package. `npm run check` still runs them in the repo.
-- The existing env allowlist, the model pinning, and the stderr capture are unchanged.