feat(iso-route): bundled preset system — extends: standard + iso-route init

Adds an opinionated tiered preset so newcomers don't have to know that
OpenCode takes opencode/* prefixes, Codex accepts Anthropic natively,
or which Haiku variant to pin — the decision is centralized in the
package and evolves with releases.

Two surfaces:

1. `extends: <preset>` in models.yaml — pulls in the bundled preset as
   the base layer, then deep-merges the user's fields on top. User wins
   at every key. targets.<harness> sub-objects merge atomically per
   harness (user's override replaces the preset's for that harness as a
   unit). Explicit null on a target removes the preset's override.

2. `iso-route init [--preset <name>] [--out <path>] [--force]` — writes
   a starter models.yaml that extends the preset, with a commented
   example override block to guide first-time edits.

Preset content verified against 2026-04 provider catalogs (Anthropic,
OpenAI, OpenCode Zen/Go):

  default:  anthropic/claude-sonnet-4-6 (opencode/glm-5.1 on OpenCode)
  fast:     claude-haiku-4-5 (opencode/big-pickle, openai/gpt-5.4-mini)
  quality:  claude-opus-4-7 high reasoning (opencode-go/kimi-k2.5,
            openai/gpt-5.4 high reasoning)
  minimal:  claude-haiku-4-5 (opencode/minimax-m2.5-free,
            openai/gpt-5.4-nano)

Cursor has no programmatic model binding, so its per-target override is
absent on every role — iso-route build still emits the advisory README
with the resolved picks for users to select manually in the Cursor UI.

Ships presets/ in the published tarball (added to package.json files).

10 new tests cover preset loading, scalar overrides, atomic target
replacement, null-to-remove semantics, unknown preset rejection, and
adding-new-roles-alongside-preset cases.

Deferred follow-up (flagged, not done): optional cron-scraper that
auto-bumps the preset when new models ship upstream. Until then,
preset maintenance is a normal release-cycle concern.

Author: CharGrnmn

.changeset/iso-route-presets.md

@@ -0,0 +1,68 @@
+---
+"@razroo/iso-route": minor
+---
+
+Bundled preset system — `extends: standard` in models.yaml + `iso-route init`.
+
+Ships an opinionated cost-tiered preset so newcomers don't have to know
+that OpenCode takes `opencode/*` prefixes, Codex accepts Anthropic
+natively, or which Haiku variant to pin — the decision is made once
+inside iso-route and evolves with new releases.
+
+**`extends: standard`** in any `models.yaml` pulls in the bundled
+preset as the base layer, then deep-merges the user's fields on top.
+User wins at every key. `targets.<harness>` sub-objects merge atomically
+per harness (a user's override replaces the preset's for that harness
+as a unit, not field-by-field). Explicit `null` on a target removes
+the preset's override.
+
+```yaml
+extends: standard
+# Everything below is optional — override only what you want:
+roles:
+  quality:
+    targets:
+      codex:
+        provider: openai
+        model: gpt-5.4
+```
+
+**`iso-route init`** scaffolds a starter `models.yaml` in the current
+directory that extends the standard preset and points the user at the
+overridable hooks:
+
+```
+iso-route init                         # writes ./models.yaml
+iso-route init --preset standard       # explicit
+iso-route init --out custom/path.yaml  # different location
+iso-route init --force                 # overwrite existing
+```
+
+**Preset content — `standard`** (verified against 2026-04 provider
+catalogs: Anthropic, OpenAI, OpenCode Zen/Go):
+
+- `default`: anthropic/claude-sonnet-4-6; opencode/glm-5.1 on OpenCode
+- `fast` role: claude-haiku-4-5; opencode/big-pickle on OpenCode;
+  openai/gpt-5.4-mini on Codex
+- `quality` role: claude-opus-4-7 with high reasoning; opencode-go/
+  kimi-k2.5 on OpenCode; openai/gpt-5.4 with high reasoning on Codex
+- `minimal` role: claude-haiku-4-5; opencode/minimax-m2.5-free on
+  OpenCode; openai/gpt-5.4-nano on Codex
+
+Cursor has no programmatic model binding, so its per-target override
+is absent on every role — `iso-route build` still emits the advisory
+README with the resolved picks for users to select manually from the
+Cursor UI.
+
+**Additive — fully backwards-compatible.** A `models.yaml` without
+`extends:` behaves exactly as before. The `presets/` directory now
+ships in the published tarball.
+
+**Deferred follow-up:** an optional cron-scraper that auto-bumps preset
+models when new versions ship upstream. Not in this release — the
+catalog was hand-verified via web search, and preset maintainers will
+bump via a normal release cycle until the scraper lands.
+
+Adds 10 tests across the parser covering preset loading, scalar
+overrides, atomic target replacement, null-to-remove semantics, unknown
+preset rejection, and adding-new-roles-alongside-preset.

packages/iso-route/package.json

@@ -14,6 +14,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "examples",
+    "presets",
     "README.md",
     "LICENSE"
   ],

packages/iso-route/presets/standard.yaml

@@ -0,0 +1,72 @@
+# @razroo/iso-route — standard preset
+#
+# Opinionated cost-tiered routing across Claude Code, Cursor, Codex, and
+# OpenCode. Verified against each provider's 2026-04 model catalogs:
+#   Anthropic docs, OpenAI docs, xAI docs, Google Gemini docs, OpenCode
+#   Zen/Go proxy listings.
+#
+# Three roles, each with per-harness overrides:
+#   - fast     — cheap + quick, for procedural work
+#   - quality  — top-tier, for judgment / writing / reasoning
+#   - minimal  — smallest credible model, for narrow one-shot transforms
+#
+# Users extend this preset in their own models.yaml:
+#
+#   extends: standard
+#   # ...override only what you want:
+#   roles:
+#     quality:
+#       targets:
+#         codex: { provider: openai, model: gpt-5.4 }
+
+default:
+  provider: anthropic
+  model: claude-sonnet-4-6
+  targets:
+    opencode:
+      provider: opencode
+      model: opencode/glm-5.1
+
+roles:
+  # fast — procedural worker. Cheap per-call cost; assumes the task is
+  # scripted / deterministic and quality-sensitive prose is NOT required.
+  fast:
+    provider: anthropic
+    model: claude-haiku-4-5
+    targets:
+      opencode:
+        provider: opencode
+        model: opencode/big-pickle
+      codex:
+        provider: openai
+        model: gpt-5.4-mini
+
+  # quality — top-tier worker. Use for writing, evaluation narratives,
+  # nuanced judgment calls, or high-stakes single applications where the
+  # marginal cost is worth the quality delta.
+  quality:
+    provider: anthropic
+    model: claude-opus-4-7
+    reasoning: high
+    targets:
+      opencode:
+        provider: opencode
+        model: opencode-go/kimi-k2.5
+      codex:
+        provider: openai
+        model: gpt-5.4
+        reasoning: high
+
+  # minimal — narrow one-shot extractor / classifier. Smallest credible
+  # model on each harness; input/output is expected to be ≤5K tokens and
+  # structured. Not for multi-step workflows.
+  minimal:
+    provider: anthropic
+    model: claude-haiku-4-5
+    targets:
+      opencode:
+        provider: opencode
+        model: opencode/minimax-m2.5-free
+      codex:
+        provider: openai
+        model: gpt-5.4-nano

packages/iso-route/src/cli.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ALL_TARGETS, build } from "./build.js";
-import { loadPolicy } from "./parser.js";
+import { listPresets, loadPolicy } from "./parser.js";
 import type { HarnessTarget } from "./types.js";
 
 const USAGE = `iso-route — one model policy, every harness
@@ -14,8 +14,11 @@ usage:
   iso-route build  <models.yaml> [--out <dir>] [--targets claude,codex,opencode,cursor]
                                   [--dry-run]
   iso-route plan   <models.yaml>
+  iso-route init   [--preset <name>] [--out <path>] [--force]
 
 targets default to all four. --dry-run emits nothing but prints every file it *would* write.
+"init" scaffolds a starter models.yaml from a built-in preset. Run "iso-route init --help"
+to see available presets.
 `;
 
 function readVersion(): string {
@@ -111,6 +114,77 @@ function cmdPlan(args: string[]): number {
   return 0;
 }
 
+function cmdInit(args: string[]): number {
+  let preset = "standard";
+  let outPath = "models.yaml";
+  let force = false;
+  let showHelp = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--preset") {
+      preset = args[++i] ?? "";
+      if (!preset) {
+        console.error("iso-route init: --preset requires a name");
+        return 2;
+      }
+    } else if (a === "--out") {
+      outPath = args[++i] ?? "";
+      if (!outPath) {
+        console.error("iso-route init: --out requires a path");
+        return 2;
+      }
+    } else if (a === "--force") {
+      force = true;
+    } else if (a === "--help" || a === "-h") {
+      showHelp = true;
+    } else {
+      console.error(`iso-route init: unknown flag "${a}"`);
+      return 2;
+    }
+  }
+  if (showHelp) {
+    console.log(
+      `iso-route init — scaffold a models.yaml from a built-in preset\n\n` +
+        `available presets: ${listPresets().join(", ")}\n\n` +
+        `flags:\n` +
+        `  --preset <name>  preset to use (default: standard)\n` +
+        `  --out <path>     where to write (default: ./models.yaml)\n` +
+        `  --force          overwrite an existing file\n`,
+    );
+    return 0;
+  }
+
+  const presets = listPresets();
+  if (!presets.includes(preset)) {
+    console.error(
+      `iso-route init: unknown preset "${preset}". Available: ${presets.join(", ")}`,
+    );
+    return 2;
+  }
+
+  const absOut = resolve(process.cwd(), outPath);
+  if (existsSync(absOut) && !force) {
+    console.error(
+      `iso-route init: ${absOut} already exists. Pass --force to overwrite, or --out <other>.`,
+    );
+    return 2;
+  }
+
+  // Scaffold a lean consumer models.yaml that extends the preset. Users can
+  // see the preset's content by reading node_modules/@razroo/iso-route/presets/
+  // or by running `iso-route plan` on this file.
+  const header = `# Model policy for this project. Extends @razroo/iso-route's built-in "${preset}"\n`;
+  const explain =
+    `# preset — override only what you want to differ. Run \`iso-route plan\` to see\n` +
+    `# the resolved policy (preset + your overrides applied).\n`;
+  const body = `\nextends: ${preset}\n\n# Example override — uncomment and edit:\n#\n# roles:\n#   quality:\n#     targets:\n#       codex:\n#         provider: openai\n#         model: gpt-5.4\n`;
+  writeFileSync(absOut, header + explain + body);
+  console.log(`iso-route: wrote ${absOut} (extends preset "${preset}")`);
+  console.log(`  next: \`iso-route plan ${outPath}\` to see resolved roles`);
+  console.log(`        \`iso-route build ${outPath} --out .\` to emit harness configs`);
+  return 0;
+}
+
 function formatBytes(n: number): string {
   if (n < 1024) return `${n} B`;
   if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
@@ -131,6 +205,7 @@ function main(argv: string[]): number {
   const rest = args.slice(1);
   if (cmd === "build") return cmdBuild(rest);
   if (cmd === "plan") return cmdPlan(rest);
+  if (cmd === "init") return cmdInit(rest);
   console.error(`iso-route: unknown command "${cmd}"\n`);
   console.error(USAGE);
   return 2;