roadmodel 0.2.61__tar.gz → 0.2.63__tar.gz

{roadmodel-0.2.61 → roadmodel-0.2.63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roadmodel
-Version: 0.2.61
+Version: 0.2.63
 Summary: BYO-key CLI that recommends the right AI model, platform, and settings for a prompt.
 Project-URL: Homepage, https://roadmodel.ai
 Project-URL: Repository, https://github.com/nathanramoscfa/roadmodel

{roadmodel-0.2.61 → roadmodel-0.2.63}/docs/catalog.json

@@ -1,7 +1,7 @@
 {
-  "schema_version": "3",
+  "schema_version": "4",
   "output_contract_version": 2,
-  "generated_at_utc": "2026-10-02T17:12:09Z",
+  "generated_at_utc": "2026-10-02T18:08:21Z",
   "source_doc_sha256": {
     "model-selector.txt": "81c5530a28521df18ebe14810e56cd72e65f1e30ad93d0522d31dbf362516e93",
     "model-tier-cost-scale.md": "2b3b0eb82237eb5cb5bf468a3fe971bcaf0160ad7d0bc700698d2c16640bc41d"
@@ -1523,7 +1523,78 @@
       "exposes_max_mode": "no",
       "exposes_thinking": "yes",
       "exposes_orchestration": "yes",
-      "best_for": "Default for Claude coding or terminal tasks when a claude.ai Max subscription is active \u2014 $0 marginal cost until the Max budget is exhausted, full tool-use surface, runs as a CLI, IDE extension inside Cursor, native VS Code extension, and as of 2.1.170+ also ships Claude Fable 5 (Mythos-class) plus a first-class Claude in Chrome browser-control integration (GA in 2.1.198), with Claude Sonnet 5 now the default model (2.1.197+) at native 1M-token context; as of 2.1.219 Claude Opus 5 ships as the new default Opus (1M context, fast mode at $10/$50 per Mtok) and Opus 4.7 is removed from fast mode so `/fast` now applies to Opus 5 and Opus 4.8; 2.1.280 ships Claude Opus 5.5 as the new default Opus (1M context, $4/$20 per Mtok with $0.20/Mtok cache reads) and changes the Pro and Team Standard default model from Sonnet to Opus (matching Max / Team Premium / Enterprise); 2.1.220\u20132.1.280 are bug-fix / reliability / self-hosted-runner / UI-polish / plugin-safety / VS Code / Claude apps / AGENTS.md / auto-mode-server-classifier releases with no effort/thinking surface changes beyond the 2.1.267 `maxEffortLevel` cap and the 2.1.269 `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) knob for the Workflow tool's per-run concurrent-agent limit noted below (2.1.224 adds `claude self-hosted-runner` for turning your own machines into places where Claude Code web/mobile/desktop sessions can run, cross-session `SendMessage`, and archive-plugin sources; 2.1.225 adds gateway spend-limit reporting to the usage warning; 2.1.227 polishes the slash-command menu and fixes feature-flag evaluation for expired login tokens; 2.1.257 ships Claude Fable 5.1 as the new default Fable at 1M context and $10/$50 per Mtok; 2.1.259 adds `managedMcpServers` policy and `--permission-prompts none` for unattended headless hosts; 2.1.260 adds an inline `/diff` panel and a headless text form of `/advisor`; 2.1.261 adds `/skill-doctor` and `bashOutputMaxChars` / `taskOutputMaxChars` settings; 2.1.263 is a reliability release; 2.1.265 adds a `--plugin-dir` folder-of-plugins mode and tightens plugin path containment; 2.1.266 restores gateway/proxy behavior when `CLAUDE_CODE_USE_GATEWAY` is set alongside an API key or `apiKeyHelper`; 2.1.267 adds a `maxEffortLevel` setting \u2014 top-level or per model under `modelSettings` \u2014 that CAPS the effort level on every provider including Bedrock, Vertex, and Foundry while still letting users pick any lower level, plus `--system-prompt-snapshot off` for iterating on prompt text and a fix for `effort:` frontmatter on custom commands, skills, and subagents being ignored on models whose default effort is still pinned; 2.1.269 adds `claude plugin eval` for scored plugin eval suites, `/output-style [name]` to list and switch output styles (including over Remote Control and in headless sessions), a Bash-tool file-edit diff (setting `bashEditDiffEnabled`), `OTEL_METRICS_INCLUDE_REPOSITORY` for tagging OpenTelemetry metrics and events with `vcs.*` attributes, `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` to extend the LLM gateway `/v1/models` discovery timeout, and `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) to raise the Workflow tool's per-run concurrent-agent limit for inference-bound fan-outs \u2014 none of which change the `/effort` vocabulary; 2.1.270 fixes read-only git commands in Bash unexpectedly asking for permission after a session had been running for a while, a 2.1.269 regression, with no surface changes; 2.1.271 adds fast mode in Claude Code Remote (cloud and self-hosted runner) sessions where organization policy allows it, mouse support in the `/config` panel, per-command Bash / PowerShell / Monitor `allowed_domains` in auto mode with sandboxing, agent-frontmatter and `--agents` JSON `omitClaudeMd` to let custom / plugin subagents run without CLAUDE.md files (managed policy still loads), and `--accept-command <sha256>` for `claude plugin install` / `update`; 2.1.272 is a bug-fix / reliability release; 2.1.273 adds `x-claude-code-*` LLM-gateway request-hint headers behind `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`, forking a `--remote-control` / `/remote-control` session from the Claude app as a local background session, and MCP-server-disconnected notifications, plus fixes for permission handling, credential/auth error messages, prompt-cache retention across `/login` / `/upgrade` / `/extra-usage`, and gateway 401 messaging \u2014 no effort/thinking surface changes; 2.1.274 adds a critical-memory-usage warning with recovery steps, `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` to bound how long the first non-interactive turn waits for connecting MCP servers, an `effort` attribute on the `claude_code.llm_request` OpenTelemetry trace span, plus assorted VS Code, Claude Code on the web, Claude Tag, and Code Review fixes and improvements \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.275 adds signed-in account confirmation for Claude apps gateway sign-in, a send-now key (ctrl+enter, or ctrl+x ctrl+s) that flushes queued messages mid-turn, syncing of claude.ai-account skills and plugins into terminal sessions (opt out with `syncClaudeAiSkills: false` / `syncClaudeAiPlugins: false`), `/plugin install <plugin> --marketplace <source>`, and a startup warning when `otelHeadersHelper` fails, plus a broad set of reliability and rendering fixes \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.276 is a hotfix for a 2.1.275 regression where every request behind a proxy or gateway failed with `400 \u2026 Input tag 'advisor_20260301'`, with no surface changes; 2.1.277 adds AGENTS.md fallback support (in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead \u2014 configurable under \"Project instructions\" in `/config`; extended by 2.1.281 to Bedrock, Vertex, Foundry, LLM gateways and telemetry-disabled sessions), `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1` for Claude apps gateways whose only egress is a forward proxy, an optional `headers:` map on Claude apps gateway upstreams, plus assorted reliability, plugin, background-task, and VS Code / Claude Code on the web / Claude Tag fixes \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.278 changes auto mode for Claude API and Enterprise users, and on Bedrock, Vertex, Foundry and gateways, to default to the server-side classifier that does not charge for classifier overhead (opt out on Bedrock, Vertex, Foundry and gateways with `CLAUDE_CODE_AUTO_MODE_SERVER=0`; warns on billed fallback) and adds an `Auto mode server` row to `/status` showing whether this session's auto mode classifier runs on the server \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.280 ships Claude Opus 5.5 as the new default Opus model at 1M context and $4/$20 per Mtok, changes the Pro and Team Standard default model from Sonnet to Opus (matching Max / Team Premium / Enterprise), and stops Opus 4.7, Opus 4.8 and Fable 5 from holding their launch-default effort over an explicit `/effort`, `effortLevel`, project or managed setting \u2014 the `/effort` vocabulary itself is unchanged; 2.1.281\u20132.1.285 are reliability / plugin / gateway / VS Code / Claude Tag / Artifact releases, with 2.1.284 adding Claude Sonnet 5.5 as the default Sonnet on the Anthropic API (1M context, $2/$10 per Mtok) and making Ultracode its own `/effort` toggle, and 2.1.285 adding `claude --desktop` to open the Claude desktop app on the current directory and an `allowedProviders` managed setting). Exposes the full `/effort` dial (low/medium/high/xhigh/max \u2014 Opus 4.6 and Sonnet 4.6 top out at max with no xhigh step; Opus 5, Opus 5.5, Opus 4.7, Opus 4.8, Sonnet 5, Sonnet 5.5, Fable 5, and Fable 5.1 expose the full range; effort levels a model does not support fall back to the highest supported level at or below the requested one; deployments may set `maxEffortLevel` to cap the maximum reachable level on every provider), the Option+T/Alt+T, `alwaysThinkingEnabled`, and `MAX_THINKING_TOKENS=0` on/off controls, plus Ultracode (session-wide Dynamic Workflows tied to xhigh; since 2.1.284 its own `/effort` toggle \u2014 Tab or `/effort ultracode [on|off]` \u2014 that keeps the current effort level, with only `claude --effort ultracode` also setting xhigh; set via `/effort ultracode` or `\"ultracode\": true`; 2.1.202+ adds a `/config` \"Dynamic workflow size\" advisory guideline, 2.1.219 defaults it to medium (aim for fewer than 15 agents) with the `workflowSizeGuideline` settings key to set it from any settings file, and 2.1.269 adds `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) to raise the per-run concurrent-agent cap for the Workflow tool) and the per-turn `ultrathink` keyword (`think`/`think hard`/`think more` are not recognized)."
+      "best_for": "Default for Claude coding or terminal tasks when a claude.ai Max subscription is active \u2014 $0 marginal cost until the Max budget is exhausted, full tool-use surface, runs as a CLI, IDE extension inside Cursor, native VS Code extension, and as of 2.1.170+ also ships Claude Fable 5 (Mythos-class) plus a first-class Claude in Chrome browser-control integration (GA in 2.1.198), with Claude Sonnet 5 now the default model (2.1.197+) at native 1M-token context; as of 2.1.219 Claude Opus 5 ships as the new default Opus (1M context, fast mode at $10/$50 per Mtok) and Opus 4.7 is removed from fast mode so `/fast` now applies to Opus 5 and Opus 4.8; 2.1.280 ships Claude Opus 5.5 as the new default Opus (1M context, $4/$20 per Mtok with $0.20/Mtok cache reads) and changes the Pro and Team Standard default model from Sonnet to Opus (matching Max / Team Premium / Enterprise); 2.1.220\u20132.1.280 are bug-fix / reliability / self-hosted-runner / UI-polish / plugin-safety / VS Code / Claude apps / AGENTS.md / auto-mode-server-classifier releases with no effort/thinking surface changes beyond the 2.1.267 `maxEffortLevel` cap and the 2.1.269 `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) knob for the Workflow tool's per-run concurrent-agent limit noted below (2.1.224 adds `claude self-hosted-runner` for turning your own machines into places where Claude Code web/mobile/desktop sessions can run, cross-session `SendMessage`, and archive-plugin sources; 2.1.225 adds gateway spend-limit reporting to the usage warning; 2.1.227 polishes the slash-command menu and fixes feature-flag evaluation for expired login tokens; 2.1.257 ships Claude Fable 5.1 as the new default Fable at 1M context and $10/$50 per Mtok; 2.1.259 adds `managedMcpServers` policy and `--permission-prompts none` for unattended headless hosts; 2.1.260 adds an inline `/diff` panel and a headless text form of `/advisor`; 2.1.261 adds `/skill-doctor` and `bashOutputMaxChars` / `taskOutputMaxChars` settings; 2.1.263 is a reliability release; 2.1.265 adds a `--plugin-dir` folder-of-plugins mode and tightens plugin path containment; 2.1.266 restores gateway/proxy behavior when `CLAUDE_CODE_USE_GATEWAY` is set alongside an API key or `apiKeyHelper`; 2.1.267 adds a `maxEffortLevel` setting \u2014 top-level or per model under `modelSettings` \u2014 that CAPS the effort level on every provider including Bedrock, Vertex, and Foundry while still letting users pick any lower level, plus `--system-prompt-snapshot off` for iterating on prompt text and a fix for `effort:` frontmatter on custom commands, skills, and subagents being ignored on models whose default effort is still pinned; 2.1.269 adds `claude plugin eval` for scored plugin eval suites, `/output-style [name]` to list and switch output styles (including over Remote Control and in headless sessions), a Bash-tool file-edit diff (setting `bashEditDiffEnabled`), `OTEL_METRICS_INCLUDE_REPOSITORY` for tagging OpenTelemetry metrics and events with `vcs.*` attributes, `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` to extend the LLM gateway `/v1/models` discovery timeout, and `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) to raise the Workflow tool's per-run concurrent-agent limit for inference-bound fan-outs \u2014 none of which change the `/effort` vocabulary; 2.1.270 fixes read-only git commands in Bash unexpectedly asking for permission after a session had been running for a while, a 2.1.269 regression, with no surface changes; 2.1.271 adds fast mode in Claude Code Remote (cloud and self-hosted runner) sessions where organization policy allows it, mouse support in the `/config` panel, per-command Bash / PowerShell / Monitor `allowed_domains` in auto mode with sandboxing, agent-frontmatter and `--agents` JSON `omitClaudeMd` to let custom / plugin subagents run without CLAUDE.md files (managed policy still loads), and `--accept-command <sha256>` for `claude plugin install` / `update`; 2.1.272 is a bug-fix / reliability release; 2.1.273 adds `x-claude-code-*` LLM-gateway request-hint headers behind `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`, forking a `--remote-control` / `/remote-control` session from the Claude app as a local background session, and MCP-server-disconnected notifications, plus fixes for permission handling, credential/auth error messages, prompt-cache retention across `/login` / `/upgrade` / `/extra-usage`, and gateway 401 messaging \u2014 no effort/thinking surface changes; 2.1.274 adds a critical-memory-usage warning with recovery steps, `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` to bound how long the first non-interactive turn waits for connecting MCP servers, an `effort` attribute on the `claude_code.llm_request` OpenTelemetry trace span, plus assorted VS Code, Claude Code on the web, Claude Tag, and Code Review fixes and improvements \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.275 adds signed-in account confirmation for Claude apps gateway sign-in, a send-now key (ctrl+enter, or ctrl+x ctrl+s) that flushes queued messages mid-turn, syncing of claude.ai-account skills and plugins into terminal sessions (opt out with `syncClaudeAiSkills: false` / `syncClaudeAiPlugins: false`), `/plugin install <plugin> --marketplace <source>`, and a startup warning when `otelHeadersHelper` fails, plus a broad set of reliability and rendering fixes \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.276 is a hotfix for a 2.1.275 regression where every request behind a proxy or gateway failed with `400 \u2026 Input tag 'advisor_20260301'`, with no surface changes; 2.1.277 adds AGENTS.md fallback support (in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead \u2014 configurable under \"Project instructions\" in `/config`; extended by 2.1.281 to Bedrock, Vertex, Foundry, LLM gateways and telemetry-disabled sessions), `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1` for Claude apps gateways whose only egress is a forward proxy, an optional `headers:` map on Claude apps gateway upstreams, plus assorted reliability, plugin, background-task, and VS Code / Claude Code on the web / Claude Tag fixes \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.278 changes auto mode for Claude API and Enterprise users, and on Bedrock, Vertex, Foundry and gateways, to default to the server-side classifier that does not charge for classifier overhead (opt out on Bedrock, Vertex, Foundry and gateways with `CLAUDE_CODE_AUTO_MODE_SERVER=0`; warns on billed fallback) and adds an `Auto mode server` row to `/status` showing whether this session's auto mode classifier runs on the server \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.280 ships Claude Opus 5.5 as the new default Opus model at 1M context and $4/$20 per Mtok, changes the Pro and Team Standard default model from Sonnet to Opus (matching Max / Team Premium / Enterprise), and stops Opus 4.7, Opus 4.8 and Fable 5 from holding their launch-default effort over an explicit `/effort`, `effortLevel`, project or managed setting \u2014 the `/effort` vocabulary itself is unchanged; 2.1.281\u20132.1.285 are reliability / plugin / gateway / VS Code / Claude Tag / Artifact releases, with 2.1.284 adding Claude Sonnet 5.5 as the default Sonnet on the Anthropic API (1M context, $2/$10 per Mtok) and making Ultracode its own `/effort` toggle, and 2.1.285 adding `claude --desktop` to open the Claude desktop app on the current directory and an `allowedProviders` managed setting). Exposes the full `/effort` dial (low/medium/high/xhigh/max \u2014 Opus 4.6 and Sonnet 4.6 top out at max with no xhigh step; Opus 5, Opus 5.5, Opus 4.7, Opus 4.8, Sonnet 5, Sonnet 5.5, Fable 5, and Fable 5.1 expose the full range; effort levels a model does not support fall back to the highest supported level at or below the requested one; deployments may set `maxEffortLevel` to cap the maximum reachable level on every provider), the Option+T/Alt+T, `alwaysThinkingEnabled`, and `MAX_THINKING_TOKENS=0` on/off controls, plus Ultracode (session-wide Dynamic Workflows tied to xhigh; since 2.1.284 its own `/effort` toggle \u2014 Tab or `/effort ultracode [on|off]` \u2014 that keeps the current effort level, with only `claude --effort ultracode` also setting xhigh; set via `/effort ultracode` or `\"ultracode\": true`; 2.1.202+ adds a `/config` \"Dynamic workflow size\" advisory guideline, 2.1.219 defaults it to medium (aim for fewer than 15 agents) with the `workflowSizeGuideline` settings key to set it from any settings file, and 2.1.269 adds `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) to raise the per-run concurrent-agent cap for the Workflow tool) and the per-turn `ultrathink` keyword (`think`/`think hard`/`think more` are not recognized).",
+      "effort_levels": [
+        "low",
+        "medium",
+        "high",
+        "xhigh",
+        "max"
+      ],
+      "effort_levels_by_model": {
+        "claude-fable-5": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "claude-fable-5.1": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "claude-opus-5": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "claude-opus-5-5": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "claude-sonnet-5": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "claude-sonnet-5-5": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "opus-4.7": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "opus-4.8": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "sonnet-4.6": [
+          "low",
+          "medium",
+          "high",
+          "max"
+        ]
+      }
     },
     {
       "id": "claude-web",
@@ -1578,7 +1649,15 @@
       "exposes_max_mode": "no",
       "exposes_thinking": "yes",
       "exposes_orchestration": "no",
-      "best_for": "The same Codex surface driven by an OpenAI API key instead of a ChatGPT sign-in: the ONLY way to run the coding-specialised `-codex` variants (gpt-5.3-codex and the gpt-5.1-codex family), and the fallback for GPT work once the ChatGPT plan&apos;s limits bind. Billed per token at list price, so prefer `codex-cli` while the subscription still has headroom. Exposes the full Codex `reasoning_effort` dial (`low`, `medium`, `high`, `xhigh`, `max`, `ultra`)."
+      "best_for": "The same Codex surface driven by an OpenAI API key instead of a ChatGPT sign-in: the ONLY way to run the coding-specialised `-codex` variants (gpt-5.3-codex and the gpt-5.1-codex family), and the fallback for GPT work once the ChatGPT plan&apos;s limits bind. Billed per token at list price, so prefer `codex-cli` while the subscription still has headroom. Exposes the full Codex `reasoning_effort` dial (`low`, `medium`, `high`, `xhigh`, `max`, `ultra`).",
+      "effort_levels": [
+        "low",
+        "medium",
+        "high",
+        "xhigh",
+        "max",
+        "ultra"
+      ]
     },
     {
       "id": "codex-cli",
@@ -1605,7 +1684,15 @@
       "exposes_max_mode": "no",
       "exposes_thinking": "yes",
       "exposes_orchestration": "no",
-      "best_for": "Default for GPT-driven autonomous coding sessions when a ChatGPT Plus/Pro subscription is active \u2014 pays from the ChatGPT budget instead of the per-token API rate, in the CLI and the IDE extension. A ChatGPT-account sign-in CANNOT run the `-codex` model variants: Codex answers 400 &quot;The &apos;gpt-5.3-codex&apos; model is not supported when using Codex with a ChatGPT account.&quot; Those variants are reachable only through `codex-api` (an OpenAI API key), so recommending one here would name a model the operator&apos;s subscription cannot run. Exposes the full Codex `reasoning_effort` dial (`low`, `medium`, `high`, `xhigh`, `max`, `ultra` \u2014 the top `ultra` step is session-wide multi-agent orchestration on par with Claude Code&apos;s `ultracode`) and no Max Mode."
+      "best_for": "Default for GPT-driven autonomous coding sessions when a ChatGPT Plus/Pro subscription is active \u2014 pays from the ChatGPT budget instead of the per-token API rate, in the CLI and the IDE extension. A ChatGPT-account sign-in CANNOT run the `-codex` model variants: Codex answers 400 &quot;The &apos;gpt-5.3-codex&apos; model is not supported when using Codex with a ChatGPT account.&quot; Those variants are reachable only through `codex-api` (an OpenAI API key), so recommending one here would name a model the operator&apos;s subscription cannot run. Exposes the full Codex `reasoning_effort` dial (`low`, `medium`, `high`, `xhigh`, `max`, `ultra` \u2014 the top `ultra` step is session-wide multi-agent orchestration on par with Claude Code&apos;s `ultracode`) and no Max Mode.",
+      "effort_levels": [
+        "low",
+        "medium",
+        "high",
+        "xhigh",
+        "max",
+        "ultra"
+      ]
     },
     {
       "id": "cursor",
@@ -1677,7 +1764,12 @@
       "exposes_max_mode": "no",
       "exposes_thinking": "yes",
       "exposes_orchestration": "no",
-      "best_for": "Direct DeepSeek API access (provider-direct per-token; OpenAI-format at api.deepseek.com and Anthropic-format at api.deepseek.com/anthropic) for the DeepSeek V4-series models (deepseek-flash = DeepSeek-V4.1-Flash, deepseek-v4-pro) \u2014 cost-conscious coding / reasoning / long-context (1M) work when the cn jurisdiction is acceptable and a deepseek-api-key is configured. Exposes the full thinking dial (toggle + reasoning_effort `low`/`high`/`max`). Not routed via the Cursor pool. cn-jurisdiction: excluded by the default allowed-jurisdictions list unless the user opts into cn."
+      "best_for": "Direct DeepSeek API access (provider-direct per-token; OpenAI-format at api.deepseek.com and Anthropic-format at api.deepseek.com/anthropic) for the DeepSeek V4-series models (deepseek-flash = DeepSeek-V4.1-Flash, deepseek-v4-pro) \u2014 cost-conscious coding / reasoning / long-context (1M) work when the cn jurisdiction is acceptable and a deepseek-api-key is configured. Exposes the full thinking dial (toggle + reasoning_effort `low`/`high`/`max`). Not routed via the Cursor pool. cn-jurisdiction: excluded by the default allowed-jurisdictions list unless the user opts into cn.",
+      "effort_levels": [
+        "low",
+        "high",
+        "max"
+      ]
     },
     {
       "id": "gemini-app",
@@ -1743,7 +1835,57 @@
       "exposes_max_mode": "no",
       "exposes_thinking": "yes",
       "exposes_orchestration": "no",
-      "best_for": "Programmatic / scripted Gemini use with a Google API key. Pay-per-token at Google's published rates. Exposes the discrete Gemini thinking-level dial (`minimal`, `low`, `medium`, `high`) shared across the 3.x and 2.5 generations \u2014 per-model support varies (Gemini 3 Pro is low/high only; Gemini 3.1 Pro / 3.7 Flash / 3.8 Flash / 2.5 Pro / 2.5 Flash / 2.5 Flash-Lite are low/medium/high without `minimal`; `minimal` appears on Flash-line models such as 3.6 Flash, 3.5 Flash, 3.5 Flash-Lite, 3.1 Flash-Lite Image, and 3 Flash). Powers the roadmodel SaaS free-tier surfaces (/recommend on Gemini 2.5 Flash; /roadmap on Gemini 2.5 Flash with 3.1 Pro escalation)."
+      "best_for": "Programmatic / scripted Gemini use with a Google API key. Pay-per-token at Google's published rates. Exposes the discrete Gemini thinking-level dial (`minimal`, `low`, `medium`, `high`) shared across the 3.x and 2.5 generations \u2014 per-model support varies (Gemini 3 Pro is low/high only; Gemini 3.1 Pro / 3.7 Flash / 3.8 Flash / 2.5 Pro / 2.5 Flash / 2.5 Flash-Lite are low/medium/high without `minimal`; `minimal` appears on Flash-line models such as 3.6 Flash, 3.5 Flash, 3.5 Flash-Lite, 3.1 Flash-Lite Image, and 3 Flash). Powers the roadmodel SaaS free-tier surfaces (/recommend on Gemini 2.5 Flash; /roadmap on Gemini 2.5 Flash with 3.1 Pro escalation).",
+      "effort_levels": [
+        "minimal",
+        "low",
+        "medium",
+        "high"
+      ],
+      "effort_levels_by_model": {
+        "gemini-2.5-flash": [
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3-flash": [
+          "minimal",
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3-pro": [
+          "low",
+          "high"
+        ],
+        "gemini-3.1-pro": [
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3.5-flash": [
+          "minimal",
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3.6-flash": [
+          "minimal",
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3.7-flash": [
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3.8-flash": [
+          "low",
+          "medium",
+          "high"
+        ]
+      }
     },
     {
       "id": "groq-api",

{roadmodel-0.2.61 → roadmodel-0.2.63}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "roadmodel"
-version = "0.2.61"
+version = "0.2.63"
 description = "BYO-key CLI that recommends the right AI model, platform, and settings for a prompt."
 readme = "README.md"
 requires-python = ">=3.11"

{roadmodel-0.2.61 → roadmodel-0.2.63}/roadmodel/data/catalog.json

@@ -1,7 +1,7 @@
 {
-  "schema_version": "3",
+  "schema_version": "4",
   "output_contract_version": 2,
-  "generated_at_utc": "2026-10-02T17:12:09Z",
+  "generated_at_utc": "2026-10-02T18:08:21Z",
   "source_doc_sha256": {
     "model-selector.txt": "81c5530a28521df18ebe14810e56cd72e65f1e30ad93d0522d31dbf362516e93",
     "model-tier-cost-scale.md": "2b3b0eb82237eb5cb5bf468a3fe971bcaf0160ad7d0bc700698d2c16640bc41d"
@@ -1523,7 +1523,78 @@
       "exposes_max_mode": "no",
       "exposes_thinking": "yes",
       "exposes_orchestration": "yes",
-      "best_for": "Default for Claude coding or terminal tasks when a claude.ai Max subscription is active \u2014 $0 marginal cost until the Max budget is exhausted, full tool-use surface, runs as a CLI, IDE extension inside Cursor, native VS Code extension, and as of 2.1.170+ also ships Claude Fable 5 (Mythos-class) plus a first-class Claude in Chrome browser-control integration (GA in 2.1.198), with Claude Sonnet 5 now the default model (2.1.197+) at native 1M-token context; as of 2.1.219 Claude Opus 5 ships as the new default Opus (1M context, fast mode at $10/$50 per Mtok) and Opus 4.7 is removed from fast mode so `/fast` now applies to Opus 5 and Opus 4.8; 2.1.280 ships Claude Opus 5.5 as the new default Opus (1M context, $4/$20 per Mtok with $0.20/Mtok cache reads) and changes the Pro and Team Standard default model from Sonnet to Opus (matching Max / Team Premium / Enterprise); 2.1.220\u20132.1.280 are bug-fix / reliability / self-hosted-runner / UI-polish / plugin-safety / VS Code / Claude apps / AGENTS.md / auto-mode-server-classifier releases with no effort/thinking surface changes beyond the 2.1.267 `maxEffortLevel` cap and the 2.1.269 `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) knob for the Workflow tool's per-run concurrent-agent limit noted below (2.1.224 adds `claude self-hosted-runner` for turning your own machines into places where Claude Code web/mobile/desktop sessions can run, cross-session `SendMessage`, and archive-plugin sources; 2.1.225 adds gateway spend-limit reporting to the usage warning; 2.1.227 polishes the slash-command menu and fixes feature-flag evaluation for expired login tokens; 2.1.257 ships Claude Fable 5.1 as the new default Fable at 1M context and $10/$50 per Mtok; 2.1.259 adds `managedMcpServers` policy and `--permission-prompts none` for unattended headless hosts; 2.1.260 adds an inline `/diff` panel and a headless text form of `/advisor`; 2.1.261 adds `/skill-doctor` and `bashOutputMaxChars` / `taskOutputMaxChars` settings; 2.1.263 is a reliability release; 2.1.265 adds a `--plugin-dir` folder-of-plugins mode and tightens plugin path containment; 2.1.266 restores gateway/proxy behavior when `CLAUDE_CODE_USE_GATEWAY` is set alongside an API key or `apiKeyHelper`; 2.1.267 adds a `maxEffortLevel` setting \u2014 top-level or per model under `modelSettings` \u2014 that CAPS the effort level on every provider including Bedrock, Vertex, and Foundry while still letting users pick any lower level, plus `--system-prompt-snapshot off` for iterating on prompt text and a fix for `effort:` frontmatter on custom commands, skills, and subagents being ignored on models whose default effort is still pinned; 2.1.269 adds `claude plugin eval` for scored plugin eval suites, `/output-style [name]` to list and switch output styles (including over Remote Control and in headless sessions), a Bash-tool file-edit diff (setting `bashEditDiffEnabled`), `OTEL_METRICS_INCLUDE_REPOSITORY` for tagging OpenTelemetry metrics and events with `vcs.*` attributes, `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` to extend the LLM gateway `/v1/models` discovery timeout, and `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) to raise the Workflow tool's per-run concurrent-agent limit for inference-bound fan-outs \u2014 none of which change the `/effort` vocabulary; 2.1.270 fixes read-only git commands in Bash unexpectedly asking for permission after a session had been running for a while, a 2.1.269 regression, with no surface changes; 2.1.271 adds fast mode in Claude Code Remote (cloud and self-hosted runner) sessions where organization policy allows it, mouse support in the `/config` panel, per-command Bash / PowerShell / Monitor `allowed_domains` in auto mode with sandboxing, agent-frontmatter and `--agents` JSON `omitClaudeMd` to let custom / plugin subagents run without CLAUDE.md files (managed policy still loads), and `--accept-command <sha256>` for `claude plugin install` / `update`; 2.1.272 is a bug-fix / reliability release; 2.1.273 adds `x-claude-code-*` LLM-gateway request-hint headers behind `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`, forking a `--remote-control` / `/remote-control` session from the Claude app as a local background session, and MCP-server-disconnected notifications, plus fixes for permission handling, credential/auth error messages, prompt-cache retention across `/login` / `/upgrade` / `/extra-usage`, and gateway 401 messaging \u2014 no effort/thinking surface changes; 2.1.274 adds a critical-memory-usage warning with recovery steps, `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` to bound how long the first non-interactive turn waits for connecting MCP servers, an `effort` attribute on the `claude_code.llm_request` OpenTelemetry trace span, plus assorted VS Code, Claude Code on the web, Claude Tag, and Code Review fixes and improvements \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.275 adds signed-in account confirmation for Claude apps gateway sign-in, a send-now key (ctrl+enter, or ctrl+x ctrl+s) that flushes queued messages mid-turn, syncing of claude.ai-account skills and plugins into terminal sessions (opt out with `syncClaudeAiSkills: false` / `syncClaudeAiPlugins: false`), `/plugin install <plugin> --marketplace <source>`, and a startup warning when `otelHeadersHelper` fails, plus a broad set of reliability and rendering fixes \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.276 is a hotfix for a 2.1.275 regression where every request behind a proxy or gateway failed with `400 \u2026 Input tag 'advisor_20260301'`, with no surface changes; 2.1.277 adds AGENTS.md fallback support (in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead \u2014 configurable under \"Project instructions\" in `/config`; extended by 2.1.281 to Bedrock, Vertex, Foundry, LLM gateways and telemetry-disabled sessions), `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1` for Claude apps gateways whose only egress is a forward proxy, an optional `headers:` map on Claude apps gateway upstreams, plus assorted reliability, plugin, background-task, and VS Code / Claude Code on the web / Claude Tag fixes \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.278 changes auto mode for Claude API and Enterprise users, and on Bedrock, Vertex, Foundry and gateways, to default to the server-side classifier that does not charge for classifier overhead (opt out on Bedrock, Vertex, Foundry and gateways with `CLAUDE_CODE_AUTO_MODE_SERVER=0`; warns on billed fallback) and adds an `Auto mode server` row to `/status` showing whether this session's auto mode classifier runs on the server \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.280 ships Claude Opus 5.5 as the new default Opus model at 1M context and $4/$20 per Mtok, changes the Pro and Team Standard default model from Sonnet to Opus (matching Max / Team Premium / Enterprise), and stops Opus 4.7, Opus 4.8 and Fable 5 from holding their launch-default effort over an explicit `/effort`, `effortLevel`, project or managed setting \u2014 the `/effort` vocabulary itself is unchanged; 2.1.281\u20132.1.285 are reliability / plugin / gateway / VS Code / Claude Tag / Artifact releases, with 2.1.284 adding Claude Sonnet 5.5 as the default Sonnet on the Anthropic API (1M context, $2/$10 per Mtok) and making Ultracode its own `/effort` toggle, and 2.1.285 adding `claude --desktop` to open the Claude desktop app on the current directory and an `allowedProviders` managed setting). Exposes the full `/effort` dial (low/medium/high/xhigh/max \u2014 Opus 4.6 and Sonnet 4.6 top out at max with no xhigh step; Opus 5, Opus 5.5, Opus 4.7, Opus 4.8, Sonnet 5, Sonnet 5.5, Fable 5, and Fable 5.1 expose the full range; effort levels a model does not support fall back to the highest supported level at or below the requested one; deployments may set `maxEffortLevel` to cap the maximum reachable level on every provider), the Option+T/Alt+T, `alwaysThinkingEnabled`, and `MAX_THINKING_TOKENS=0` on/off controls, plus Ultracode (session-wide Dynamic Workflows tied to xhigh; since 2.1.284 its own `/effort` toggle \u2014 Tab or `/effort ultracode [on|off]` \u2014 that keeps the current effort level, with only `claude --effort ultracode` also setting xhigh; set via `/effort ultracode` or `\"ultracode\": true`; 2.1.202+ adds a `/config` \"Dynamic workflow size\" advisory guideline, 2.1.219 defaults it to medium (aim for fewer than 15 agents) with the `workflowSizeGuideline` settings key to set it from any settings file, and 2.1.269 adds `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) to raise the per-run concurrent-agent cap for the Workflow tool) and the per-turn `ultrathink` keyword (`think`/`think hard`/`think more` are not recognized)."
+      "best_for": "Default for Claude coding or terminal tasks when a claude.ai Max subscription is active \u2014 $0 marginal cost until the Max budget is exhausted, full tool-use surface, runs as a CLI, IDE extension inside Cursor, native VS Code extension, and as of 2.1.170+ also ships Claude Fable 5 (Mythos-class) plus a first-class Claude in Chrome browser-control integration (GA in 2.1.198), with Claude Sonnet 5 now the default model (2.1.197+) at native 1M-token context; as of 2.1.219 Claude Opus 5 ships as the new default Opus (1M context, fast mode at $10/$50 per Mtok) and Opus 4.7 is removed from fast mode so `/fast` now applies to Opus 5 and Opus 4.8; 2.1.280 ships Claude Opus 5.5 as the new default Opus (1M context, $4/$20 per Mtok with $0.20/Mtok cache reads) and changes the Pro and Team Standard default model from Sonnet to Opus (matching Max / Team Premium / Enterprise); 2.1.220\u20132.1.280 are bug-fix / reliability / self-hosted-runner / UI-polish / plugin-safety / VS Code / Claude apps / AGENTS.md / auto-mode-server-classifier releases with no effort/thinking surface changes beyond the 2.1.267 `maxEffortLevel` cap and the 2.1.269 `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) knob for the Workflow tool's per-run concurrent-agent limit noted below (2.1.224 adds `claude self-hosted-runner` for turning your own machines into places where Claude Code web/mobile/desktop sessions can run, cross-session `SendMessage`, and archive-plugin sources; 2.1.225 adds gateway spend-limit reporting to the usage warning; 2.1.227 polishes the slash-command menu and fixes feature-flag evaluation for expired login tokens; 2.1.257 ships Claude Fable 5.1 as the new default Fable at 1M context and $10/$50 per Mtok; 2.1.259 adds `managedMcpServers` policy and `--permission-prompts none` for unattended headless hosts; 2.1.260 adds an inline `/diff` panel and a headless text form of `/advisor`; 2.1.261 adds `/skill-doctor` and `bashOutputMaxChars` / `taskOutputMaxChars` settings; 2.1.263 is a reliability release; 2.1.265 adds a `--plugin-dir` folder-of-plugins mode and tightens plugin path containment; 2.1.266 restores gateway/proxy behavior when `CLAUDE_CODE_USE_GATEWAY` is set alongside an API key or `apiKeyHelper`; 2.1.267 adds a `maxEffortLevel` setting \u2014 top-level or per model under `modelSettings` \u2014 that CAPS the effort level on every provider including Bedrock, Vertex, and Foundry while still letting users pick any lower level, plus `--system-prompt-snapshot off` for iterating on prompt text and a fix for `effort:` frontmatter on custom commands, skills, and subagents being ignored on models whose default effort is still pinned; 2.1.269 adds `claude plugin eval` for scored plugin eval suites, `/output-style [name]` to list and switch output styles (including over Remote Control and in headless sessions), a Bash-tool file-edit diff (setting `bashEditDiffEnabled`), `OTEL_METRICS_INCLUDE_REPOSITORY` for tagging OpenTelemetry metrics and events with `vcs.*` attributes, `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` to extend the LLM gateway `/v1/models` discovery timeout, and `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) to raise the Workflow tool's per-run concurrent-agent limit for inference-bound fan-outs \u2014 none of which change the `/effort` vocabulary; 2.1.270 fixes read-only git commands in Bash unexpectedly asking for permission after a session had been running for a while, a 2.1.269 regression, with no surface changes; 2.1.271 adds fast mode in Claude Code Remote (cloud and self-hosted runner) sessions where organization policy allows it, mouse support in the `/config` panel, per-command Bash / PowerShell / Monitor `allowed_domains` in auto mode with sandboxing, agent-frontmatter and `--agents` JSON `omitClaudeMd` to let custom / plugin subagents run without CLAUDE.md files (managed policy still loads), and `--accept-command <sha256>` for `claude plugin install` / `update`; 2.1.272 is a bug-fix / reliability release; 2.1.273 adds `x-claude-code-*` LLM-gateway request-hint headers behind `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`, forking a `--remote-control` / `/remote-control` session from the Claude app as a local background session, and MCP-server-disconnected notifications, plus fixes for permission handling, credential/auth error messages, prompt-cache retention across `/login` / `/upgrade` / `/extra-usage`, and gateway 401 messaging \u2014 no effort/thinking surface changes; 2.1.274 adds a critical-memory-usage warning with recovery steps, `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` to bound how long the first non-interactive turn waits for connecting MCP servers, an `effort` attribute on the `claude_code.llm_request` OpenTelemetry trace span, plus assorted VS Code, Claude Code on the web, Claude Tag, and Code Review fixes and improvements \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.275 adds signed-in account confirmation for Claude apps gateway sign-in, a send-now key (ctrl+enter, or ctrl+x ctrl+s) that flushes queued messages mid-turn, syncing of claude.ai-account skills and plugins into terminal sessions (opt out with `syncClaudeAiSkills: false` / `syncClaudeAiPlugins: false`), `/plugin install <plugin> --marketplace <source>`, and a startup warning when `otelHeadersHelper` fails, plus a broad set of reliability and rendering fixes \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.276 is a hotfix for a 2.1.275 regression where every request behind a proxy or gateway failed with `400 \u2026 Input tag 'advisor_20260301'`, with no surface changes; 2.1.277 adds AGENTS.md fallback support (in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead \u2014 configurable under \"Project instructions\" in `/config`; extended by 2.1.281 to Bedrock, Vertex, Foundry, LLM gateways and telemetry-disabled sessions), `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1` for Claude apps gateways whose only egress is a forward proxy, an optional `headers:` map on Claude apps gateway upstreams, plus assorted reliability, plugin, background-task, and VS Code / Claude Code on the web / Claude Tag fixes \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.278 changes auto mode for Claude API and Enterprise users, and on Bedrock, Vertex, Foundry and gateways, to default to the server-side classifier that does not charge for classifier overhead (opt out on Bedrock, Vertex, Foundry and gateways with `CLAUDE_CODE_AUTO_MODE_SERVER=0`; warns on billed fallback) and adds an `Auto mode server` row to `/status` showing whether this session's auto mode classifier runs on the server \u2014 no changes to the `/effort` vocabulary or extended-thinking controls; 2.1.280 ships Claude Opus 5.5 as the new default Opus model at 1M context and $4/$20 per Mtok, changes the Pro and Team Standard default model from Sonnet to Opus (matching Max / Team Premium / Enterprise), and stops Opus 4.7, Opus 4.8 and Fable 5 from holding their launch-default effort over an explicit `/effort`, `effortLevel`, project or managed setting \u2014 the `/effort` vocabulary itself is unchanged; 2.1.281\u20132.1.285 are reliability / plugin / gateway / VS Code / Claude Tag / Artifact releases, with 2.1.284 adding Claude Sonnet 5.5 as the default Sonnet on the Anthropic API (1M context, $2/$10 per Mtok) and making Ultracode its own `/effort` toggle, and 2.1.285 adding `claude --desktop` to open the Claude desktop app on the current directory and an `allowedProviders` managed setting). Exposes the full `/effort` dial (low/medium/high/xhigh/max \u2014 Opus 4.6 and Sonnet 4.6 top out at max with no xhigh step; Opus 5, Opus 5.5, Opus 4.7, Opus 4.8, Sonnet 5, Sonnet 5.5, Fable 5, and Fable 5.1 expose the full range; effort levels a model does not support fall back to the highest supported level at or below the requested one; deployments may set `maxEffortLevel` to cap the maximum reachable level on every provider), the Option+T/Alt+T, `alwaysThinkingEnabled`, and `MAX_THINKING_TOKENS=0` on/off controls, plus Ultracode (session-wide Dynamic Workflows tied to xhigh; since 2.1.284 its own `/effort` toggle \u2014 Tab or `/effort ultracode [on|off]` \u2014 that keeps the current effort level, with only `claude --effort ultracode` also setting xhigh; set via `/effort ultracode` or `\"ultracode\": true`; 2.1.202+ adds a `/config` \"Dynamic workflow size\" advisory guideline, 2.1.219 defaults it to medium (aim for fewer than 15 agents) with the `workflowSizeGuideline` settings key to set it from any settings file, and 2.1.269 adds `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` (1\u2013256) to raise the per-run concurrent-agent cap for the Workflow tool) and the per-turn `ultrathink` keyword (`think`/`think hard`/`think more` are not recognized).",
+      "effort_levels": [
+        "low",
+        "medium",
+        "high",
+        "xhigh",
+        "max"
+      ],
+      "effort_levels_by_model": {
+        "claude-fable-5": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "claude-fable-5.1": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "claude-opus-5": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "claude-opus-5-5": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "claude-sonnet-5": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "claude-sonnet-5-5": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "opus-4.7": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "opus-4.8": [
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
+        "sonnet-4.6": [
+          "low",
+          "medium",
+          "high",
+          "max"
+        ]
+      }
     },
     {
       "id": "claude-web",
@@ -1578,7 +1649,15 @@
       "exposes_max_mode": "no",
       "exposes_thinking": "yes",
       "exposes_orchestration": "no",
-      "best_for": "The same Codex surface driven by an OpenAI API key instead of a ChatGPT sign-in: the ONLY way to run the coding-specialised `-codex` variants (gpt-5.3-codex and the gpt-5.1-codex family), and the fallback for GPT work once the ChatGPT plan&apos;s limits bind. Billed per token at list price, so prefer `codex-cli` while the subscription still has headroom. Exposes the full Codex `reasoning_effort` dial (`low`, `medium`, `high`, `xhigh`, `max`, `ultra`)."
+      "best_for": "The same Codex surface driven by an OpenAI API key instead of a ChatGPT sign-in: the ONLY way to run the coding-specialised `-codex` variants (gpt-5.3-codex and the gpt-5.1-codex family), and the fallback for GPT work once the ChatGPT plan&apos;s limits bind. Billed per token at list price, so prefer `codex-cli` while the subscription still has headroom. Exposes the full Codex `reasoning_effort` dial (`low`, `medium`, `high`, `xhigh`, `max`, `ultra`).",
+      "effort_levels": [
+        "low",
+        "medium",
+        "high",
+        "xhigh",
+        "max",
+        "ultra"
+      ]
     },
     {
       "id": "codex-cli",
@@ -1605,7 +1684,15 @@
       "exposes_max_mode": "no",
       "exposes_thinking": "yes",
       "exposes_orchestration": "no",
-      "best_for": "Default for GPT-driven autonomous coding sessions when a ChatGPT Plus/Pro subscription is active \u2014 pays from the ChatGPT budget instead of the per-token API rate, in the CLI and the IDE extension. A ChatGPT-account sign-in CANNOT run the `-codex` model variants: Codex answers 400 &quot;The &apos;gpt-5.3-codex&apos; model is not supported when using Codex with a ChatGPT account.&quot; Those variants are reachable only through `codex-api` (an OpenAI API key), so recommending one here would name a model the operator&apos;s subscription cannot run. Exposes the full Codex `reasoning_effort` dial (`low`, `medium`, `high`, `xhigh`, `max`, `ultra` \u2014 the top `ultra` step is session-wide multi-agent orchestration on par with Claude Code&apos;s `ultracode`) and no Max Mode."
+      "best_for": "Default for GPT-driven autonomous coding sessions when a ChatGPT Plus/Pro subscription is active \u2014 pays from the ChatGPT budget instead of the per-token API rate, in the CLI and the IDE extension. A ChatGPT-account sign-in CANNOT run the `-codex` model variants: Codex answers 400 &quot;The &apos;gpt-5.3-codex&apos; model is not supported when using Codex with a ChatGPT account.&quot; Those variants are reachable only through `codex-api` (an OpenAI API key), so recommending one here would name a model the operator&apos;s subscription cannot run. Exposes the full Codex `reasoning_effort` dial (`low`, `medium`, `high`, `xhigh`, `max`, `ultra` \u2014 the top `ultra` step is session-wide multi-agent orchestration on par with Claude Code&apos;s `ultracode`) and no Max Mode.",
+      "effort_levels": [
+        "low",
+        "medium",
+        "high",
+        "xhigh",
+        "max",
+        "ultra"
+      ]
     },
     {
       "id": "cursor",
@@ -1677,7 +1764,12 @@
       "exposes_max_mode": "no",
       "exposes_thinking": "yes",
       "exposes_orchestration": "no",
-      "best_for": "Direct DeepSeek API access (provider-direct per-token; OpenAI-format at api.deepseek.com and Anthropic-format at api.deepseek.com/anthropic) for the DeepSeek V4-series models (deepseek-flash = DeepSeek-V4.1-Flash, deepseek-v4-pro) \u2014 cost-conscious coding / reasoning / long-context (1M) work when the cn jurisdiction is acceptable and a deepseek-api-key is configured. Exposes the full thinking dial (toggle + reasoning_effort `low`/`high`/`max`). Not routed via the Cursor pool. cn-jurisdiction: excluded by the default allowed-jurisdictions list unless the user opts into cn."
+      "best_for": "Direct DeepSeek API access (provider-direct per-token; OpenAI-format at api.deepseek.com and Anthropic-format at api.deepseek.com/anthropic) for the DeepSeek V4-series models (deepseek-flash = DeepSeek-V4.1-Flash, deepseek-v4-pro) \u2014 cost-conscious coding / reasoning / long-context (1M) work when the cn jurisdiction is acceptable and a deepseek-api-key is configured. Exposes the full thinking dial (toggle + reasoning_effort `low`/`high`/`max`). Not routed via the Cursor pool. cn-jurisdiction: excluded by the default allowed-jurisdictions list unless the user opts into cn.",
+      "effort_levels": [
+        "low",
+        "high",
+        "max"
+      ]
     },
     {
       "id": "gemini-app",
@@ -1743,7 +1835,57 @@
       "exposes_max_mode": "no",
       "exposes_thinking": "yes",
       "exposes_orchestration": "no",
-      "best_for": "Programmatic / scripted Gemini use with a Google API key. Pay-per-token at Google's published rates. Exposes the discrete Gemini thinking-level dial (`minimal`, `low`, `medium`, `high`) shared across the 3.x and 2.5 generations \u2014 per-model support varies (Gemini 3 Pro is low/high only; Gemini 3.1 Pro / 3.7 Flash / 3.8 Flash / 2.5 Pro / 2.5 Flash / 2.5 Flash-Lite are low/medium/high without `minimal`; `minimal` appears on Flash-line models such as 3.6 Flash, 3.5 Flash, 3.5 Flash-Lite, 3.1 Flash-Lite Image, and 3 Flash). Powers the roadmodel SaaS free-tier surfaces (/recommend on Gemini 2.5 Flash; /roadmap on Gemini 2.5 Flash with 3.1 Pro escalation)."
+      "best_for": "Programmatic / scripted Gemini use with a Google API key. Pay-per-token at Google's published rates. Exposes the discrete Gemini thinking-level dial (`minimal`, `low`, `medium`, `high`) shared across the 3.x and 2.5 generations \u2014 per-model support varies (Gemini 3 Pro is low/high only; Gemini 3.1 Pro / 3.7 Flash / 3.8 Flash / 2.5 Pro / 2.5 Flash / 2.5 Flash-Lite are low/medium/high without `minimal`; `minimal` appears on Flash-line models such as 3.6 Flash, 3.5 Flash, 3.5 Flash-Lite, 3.1 Flash-Lite Image, and 3 Flash). Powers the roadmodel SaaS free-tier surfaces (/recommend on Gemini 2.5 Flash; /roadmap on Gemini 2.5 Flash with 3.1 Pro escalation).",
+      "effort_levels": [
+        "minimal",
+        "low",
+        "medium",
+        "high"
+      ],
+      "effort_levels_by_model": {
+        "gemini-2.5-flash": [
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3-flash": [
+          "minimal",
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3-pro": [
+          "low",
+          "high"
+        ],
+        "gemini-3.1-pro": [
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3.5-flash": [
+          "minimal",
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3.6-flash": [
+          "minimal",
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3.7-flash": [
+          "low",
+          "medium",
+          "high"
+        ],
+        "gemini-3.8-flash": [
+          "low",
+          "medium",
+          "high"
+        ]
+      }
     },
     {
       "id": "groq-api",

{roadmodel-0.2.61 → roadmodel-0.2.63}/src/roadmodel/__init__.py

@@ -1,2 +1,2 @@
 # src/roadmodel/__init__.py
-__version__ = "0.2.61"
+__version__ = "0.2.63"

{roadmodel-0.2.61 → roadmodel-0.2.63}/src/roadmodel/recommend.py

@@ -501,8 +501,10 @@ _SAAS_LADDER_TABLE_HEADER: Final = (
     "gives both the same settings because a lower effort saves this user nothing or "
     "the dial has no lower level; say which in that block's RATIONALE, and never "
     "invent another difference.\n"
-    "- BACKUP obeys the Step 7 HARD cross-provider rule and names a model this user "
-    "can reach.\n"
+    "- Each block's BACKUP is the model the row names after `backup` in that tier's "
+    "cell, copied verbatim; code checks it against the row and replaces one that "
+    "differs. Where a cell names no backup, BACKUP obeys the Step 7 HARD "
+    "cross-provider rule and names a model this user can reach.\n"
     "- Each RATIONALE is three labelled segments (TASK: / PICK: / EFFORT:), one crisp "
     "sentence each. PICK says why the row's model fits its tier in the table's terms "
     "(where it sits on the user's frontier, its AA Index); EFFORT says why the setting "
@@ -1230,16 +1232,25 @@ def _ladder_tier_guard(picks: dict[str, dict[str, Any]]) -> dict[str, Any]:
     }
 
 
-# The scorer's effort levels as the selector's output format writes them.
+# Effort levels as the selector's output format writes them: the scorer's
+# five and the native words some dials add (scoring.LEVEL_ORDER).
 _EFFORT_WORDS: Final = {
+    "none": "None",
+    "minimal": "Minimal",
     "low": "Low",
     "medium": "Medium",
     "high": "High",
     "xhigh": "XHigh",
     "max": "Max",
+    "ultra": "Ultra",
 }
 
 
+def _effort_word(level: str) -> str:
+    """A rung's level (native or scorer) as the EFFORT line writes it."""
+    return _EFFORT_WORDS.get(scoring.normalize_level(level), level)
+
+
 def _model_key(ref: str) -> str:
     """A spelling-free key for a model reference: "Claude Opus 5.5",
     "Opus 5.5" and "claude-opus-5-5" all key the same."""
@@ -1304,7 +1315,7 @@ def _enforce_table_row(ladder: dict[str, dict[str, str]], row: scoring.Ladder) -
             continue
         rewritten.append(tier)
         c = rung.candidate
-        effort = _EFFORT_WORDS.get(rung.effort, rung.effort)
+        effort = _effort_word(rung.level)
         sections = _split_rationale_sections(base.get("rationale", ""))
         task = (
             sections["task"]
@@ -1322,35 +1333,79 @@ def _enforce_table_row(ladder: dict[str, dict[str, str]], row: scoring.Ladder) -
     return rewritten
 
 
-# Surfaces whose effort dial reads exactly the scorer's levels, so code can set
-# the row's level verbatim. Claude Code's ladder is Low / Medium / High / XHigh /
-# Max, with Ultracode above Max. Elsewhere the dial has its own words (Codex's
-# Intelligence, Gemini's thinking levels) and the engine maps to the nearest.
-_NATIVE_EFFORT_PLATFORMS: Final = frozenset({"claude-code"})
+def _enforce_table_backup(ladder: dict[str, dict[str, str]], row: scoring.Ladder) -> list[str]:
+    """Make every rung's BACKUP the row's: the best model from another maker
+    the user can run at no higher list price (scoring._backup_for). A rung
+    whose row names no backup (no other maker funded) keeps the engine's,
+    under the Step 7 guard. Returns the tiers whose backup it set."""
+    adjusted: list[str] = []
+    for tier in _LADDER_TIERS:
+        backup = row.rungs[tier].backup
+        if backup is None:
+            continue
+        b = backup.candidate
+        written = ladder[tier].get("backup", "")
+        if written and (
+            cost.model_id_of(written) == b.model_id
+            or _model_key(written) in {_model_key(b.model_id), _model_key(b.model_name)}
+        ):
+            continue
+        ladder[tier]["backup"] = b.model_name
+        adjusted.append(tier)
+    return adjusted
 
 
-def _effort_level(value: str) -> str:
-    level = re.sub(r"[\s_-]+", "", value.strip().lower())
-    return {"extrahigh": "xhigh"}.get(level, level)
+def _attach_backup_plans(picks: dict[str, dict[str, Any]], row: scoring.Ladder) -> None:
+    """Give each pick whose BACKUP is the row's a ``backup_plan``: the
+    platform and effort the row runs that backup at, so a caller can show the
+    backup on the surface the scorer chose (the user's subscription surface
+    where one reaches it) instead of guessing one. A backup the guard replaced
+    gets none."""
+    for tier in _LADDER_TIERS:
+        backup = row.rungs[tier].backup
+        if backup is None:
+            continue
+        b = backup.candidate
+        if picks[tier].get("backup") != cost.canonical_model_name(b.model_name):
+            continue
+        picks[tier]["backup_plan"] = {
+            "model": picks[tier]["backup"],
+            "platform": b.platform_name,
+            "effort": _effort_word(backup.level),
+        }
+
+
+# Claude Code's Ultracode is a session setting above its Max level: it stands
+# where the row says max.
+_ULTRACODE_PLATFORM: Final = "claude-code"
 
 
 def _enforce_table_effort(ladder: dict[str, dict[str, str]], row: scoring.Ladder) -> list[str]:
-    """On a surface whose dial reads the scorer's levels, make every rung's
-    EFFORT the row's (Ultracode stands where the row says Max) and rewrite its
-    EFFORT segment to match. Two rungs on one model are told apart by effort
-    alone, so an engine that copies the model but not the effort makes them
-    identical. Returns the tiers whose effort it set."""
+    """On every surface whose dial the catalog documents (the rung carries a
+    native level), make the rung's EFFORT the row's level in that dial's own
+    words and rewrite its EFFORT segment to match; on Claude Code, Ultracode
+    stands where the row says max. Two rungs on one model are told apart by
+    effort alone, so an engine that copies the model but not the effort makes
+    them identical. A surface with no documented dial keeps the engine's
+    mapping. Returns the tiers whose effort it set."""
     adjusted: list[str] = []
     for tier in _LADDER_TIERS:
         base = ladder[tier]
         rung = row.rungs[tier]
-        if rung.candidate.platform_id not in _NATIVE_EFFORT_PLATFORMS:
+        if rung.native is None:
+            continue
+        written = scoring.normalize_level(base.get("effort", ""))
+        want = scoring.normalize_level(rung.native)
+        if written == want:
             continue
-        written = _effort_level(base.get("effort", ""))
-        if written == rung.effort or (rung.effort == "max" and written == "ultracode"):
+        if (
+            rung.candidate.platform_id == _ULTRACODE_PLATFORM
+            and want == "max"
+            and written == "ultracode"
+        ):
             continue
         adjusted.append(tier)
-        effort = _EFFORT_WORDS.get(rung.effort, rung.effort)
+        effort = _effort_word(rung.native)
         base["effort"] = effort
         sections = _split_rationale_sections(base.get("rationale", ""))
         if sections:
@@ -1398,11 +1453,14 @@ def recommend_structured_ladder(
     The picks come from this user's own cost/quality frontier: the scorer's
     ladder table (scoring.ladder_table) goes into the prompt, the engine
     classifies the task and copies its row, and every rung is then made the
-    row's (:func:`_enforce_table_row`), effort included where the surface's
-    dial reads the scorer's levels (:func:`_enforce_table_effort`). ``guard``
-    then reports ``mode: "frontier"``, the row, how it was found, the tiers
-    rewritten and the tiers whose effort was set, and is healthy: two rungs on
-    one model are the table's answer, not a collapse.
+    row's (:func:`_enforce_table_row`), effort included on every surface
+    whose dial the catalog documents (:func:`_enforce_table_effort`), and
+    BACKUP included where the row names one (:func:`_enforce_table_backup`;
+    such a pick also carries a ``backup_plan`` with the backup's platform and
+    effort). ``guard`` then reports ``mode: "frontier"``, the row, how it was
+    found, the tiers rewritten, the tiers whose effort was set and the tiers
+    whose backup was set, and is healthy: two rungs on one model are the
+    table's answer, not a collapse.
     Without a table, or a response the table cannot place, the engine's own
     picks stand under the tier-distinctness guard as before.
 
@@ -1449,6 +1507,7 @@ def recommend_structured_ladder(
                 "found": found,
                 "rewritten": _enforce_table_row(ladder, row),
                 "effort_set": _enforce_table_effort(ladder, row),
+                "backup_set": _enforce_table_backup(ladder, row),
                 "frontier": [p.candidate.model_name for p in row.frontier],
             }
         else:
@@ -1463,6 +1522,8 @@ def recommend_structured_ladder(
         )
         for tier in _LADDER_TIERS
     }
+    if frontier_guard is not None and frontier_guard["classification"] is not None:
+        _attach_backup_plans(picks, table[frontier_guard["classification"]])
     guard = _ladder_tier_guard(picks)
     if frontier_guard is not None:
         guard.update(frontier_guard)

{roadmodel-0.2.61 → roadmodel-0.2.63}/src/roadmodel/scoring.py

@@ -56,7 +56,7 @@ from __future__ import annotations
 import json
 import math
 import re
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass, field, replace
 from datetime import datetime, timedelta, timezone
 from importlib import resources
 from typing import Any, Final
@@ -79,6 +79,21 @@ CATEGORIES: Final[tuple[str, ...]] = (
 COMPLEXITIES: Final[tuple[str, ...]] = ("low", "medium", "high")
 BUDGETS: Final[tuple[str, ...]] = ("cheap", "balanced", "best")
 EFFORT_LADDER: Final[tuple[str, ...]] = ("low", "medium", "high", "xhigh", "max")
+# Level names across every documented effort dial, lowest first: the scorer's
+# five plus the words some surfaces add below or above them (Gemini's
+# `minimal`, Codex's `ultra`). Orders and compares native levels; each
+# surface's own list comes from the catalog's `effort_levels`, which
+# update/build_catalog.py reads from the trackers' snapshots of its docs.
+LEVEL_ORDER: Final[tuple[str, ...]] = (
+    "none",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+    "ultra",
+)
 
 # The Artificial Analysis evidence figure per category. For the five derived
 # categories it is the evidence update/derive_ratings.py letters from, and the
@@ -621,6 +636,71 @@ def effort_for(task: Task, headroom: str, scarcity: float) -> str:
     return EFFORT_LADDER[rung]
 
 
+def normalize_level(value: str) -> str:
+    """An effort level name compared case- and spacing-free: "XHigh",
+    "x-high" and "Extra high" are all ``xhigh``."""
+    level = re.sub(r"[\s_-]+", "", value.strip().lower())
+    return {"extrahigh": "xhigh"}.get(level, level)
+
+
+def native_levels(
+    platform: str, model: str, *, catalog: dict[str, Any] | None = None
+) -> list[str] | None:
+    """The levels ``platform``'s effort dial offers for ``model``, lowest
+    first, as the catalog records them from that surface's own docs: the
+    method's ``effort_levels_by_model`` entry where its docs distinguish
+    models (a model they leave out has no documented dial), else its
+    ``effort_levels``. None when the catalog documents no dial; the engine
+    then maps the scorer's level to the surface itself."""
+    cat = catalog if catalog is not None else _cost._load_catalog()
+    for method in cat.get("access_methods", []):
+        if not isinstance(method, dict) or method.get("id") != platform:
+            continue
+        by_model = method.get("effort_levels_by_model")
+        levels = by_model.get(model) if isinstance(by_model, dict) else method.get("effort_levels")
+        if isinstance(levels, list) and levels and all(isinstance(x, str) for x in levels):
+            return list(levels)
+        return None
+    return None
+
+
+def native_level(
+    platform: str, model: str, scorer_level: str, *, catalog: dict[str, Any] | None = None
+) -> str | None:
+    """The level to set on ``platform``'s dial for ``model`` when the scorer
+    says ``scorer_level``: the native level of that name, else the highest
+    native level below it, else the dial's lowest. None when the catalog
+    documents no dial for the pair."""
+    levels = native_levels(platform, model, catalog=catalog)
+    if not levels:
+        return None
+    want = normalize_level(scorer_level)
+    for level in levels:
+        if normalize_level(level) == want:
+            return level
+    order = {name: i for i, name in enumerate(LEVEL_ORDER)}
+    if want in order:
+        below = [lv for lv in levels if order.get(normalize_level(lv), len(order)) < order[want]]
+        if below:
+            return max(below, key=lambda lv: order[normalize_level(lv)])
+    return levels[0]
+
+
+def _scorer_level(native: str) -> str:
+    """The scorer level a native level stands for: the highest of
+    EFFORT_LADDER at or below it, floored at ``low`` (Gemini's ``minimal``)
+    and capped at ``max`` (Codex's ``ultra``)."""
+    level = normalize_level(native)
+    if level in EFFORT_LADDER:
+        return level
+    order = {name: i for i, name in enumerate(LEVEL_ORDER)}
+    rank = order.get(level)
+    if rank is None:
+        return EFFORT_LADDER[0]
+    at_or_below = [e for e in EFFORT_LADDER if order[e] <= rank]
+    return at_or_below[-1] if at_or_below else EFFORT_LADDER[0]
+
+
 def _quality(
     model: dict[str, Any],
     task: Task,
@@ -944,16 +1024,46 @@ class FrontierPoint:
     price_usd: float
 
 
+@dataclass(frozen=True)
+class Backup:
+    """A rung's cross-maker substitute, read off the frontier of the other
+    makers' models (see :func:`ladder`)."""
+
+    point: FrontierPoint
+    effort: str
+    native: str | None = None
+
+    @property
+    def candidate(self) -> Candidate:
+        return self.point.candidate
+
+    @property
+    def level(self) -> str:
+        return self.native or self.effort
+
+
 @dataclass(frozen=True)
 class Rung:
     tier: str
     point: FrontierPoint
+    # The scorer's level (EFFORT_LADDER) this rung runs at.
     effort: str
+    # The same level as the platform's own dial names it (native_level), or
+    # None when the catalog documents no dial for the platform and model.
+    native: str | None = None
+    # The best cross-maker substitute at no higher list price; None when the
+    # pool holds no other maker's model.
+    backup: Backup | None = None
 
     @property
     def candidate(self) -> Candidate:
         return self.point.candidate
 
+    @property
+    def level(self) -> str:
+        """The level the operator sets: the native word, else the scorer's."""
+        return self.native or self.effort
+
 
 @dataclass
 class Ladder:
@@ -963,6 +1073,8 @@ class Ladder:
     # complexity's requirement, cheapest first.
     adequate: list[FrontierPoint]
     rungs: dict[str, Rung]
+    # Why a rung has no backup: the pool holds no other maker's model.
+    backup_warning: str | None = None
 
     def to_dict(self) -> dict[str, Any]:
         def point(p: FrontierPoint) -> dict[str, Any]:
@@ -982,7 +1094,24 @@ class Ladder:
             "task": asdict(self.task),
             "frontier": [point(p) for p in self.frontier],
             "adequate": [p.candidate.model_id for p in self.adequate],
-            "rungs": {t: {**point(r.point), "effort": r.effort} for t, r in self.rungs.items()},
+            "rungs": {
+                t: {
+                    **point(r.point),
+                    "effort": r.effort,
+                    "native_effort": r.native,
+                    "backup": (
+                        {
+                            **point(r.backup.point),
+                            "effort": r.backup.effort,
+                            "native_effort": r.backup.native,
+                        }
+                        if r.backup is not None
+                        else None
+                    ),
+                }
+                for t, r in self.rungs.items()
+            },
+            "backup_warning": self.backup_warning,
         }
 
 
@@ -1030,12 +1159,16 @@ def ladder(
       at the balanced posture; with none between, the COST or QUALITY model at
       the balanced posture's effort, whichever differs from both other rungs.
     - Each rung runs at :func:`effort_for` its posture (cheap / balanced /
-      best) on its platform. A lower rung on the same model and platform as
+      best), set on its platform's own dial (:func:`native_level`) where the
+      catalog documents one. A lower rung on the same model and platform as
       the rung above runs at least one effort level below it
       (:func:`_below`), so the three picks stay distinct; at the dial's lowest
       level they may converge. On an `uncapped` pool every free rung runs at
       the top effort and two rungs on one model converge: a lower effort saves
       that operator nothing.
+    - Each rung carries a BACKUP from another maker (:func:`_backup_for`):
+      the best adequate point on the other makers' frontier at no higher list
+      price. ``backup_warning`` says why a rung has none.
 
     None when no pool model carries an AA Index (no frontier to read)."""
     cat = catalog if catalog is not None else _cost._load_catalog()
@@ -1065,10 +1198,12 @@ def ladder(
 
     def rung(tier: str, p: FrontierPoint) -> Rung:
         t = Task(task.category, task.complexity, task.novel, TIER_BUDGET[tier])
-        return Rung(tier, p, effort_for(t, headroom, p.candidate.scarcity))
+        effort = effort_for(t, headroom, p.candidate.scarcity)
+        c = p.candidate
+        return Rung(tier, p, effort, native_level(c.platform_id, c.model_id, effort, catalog=cat))
 
     def same(a: Rung, b: Rung) -> bool:
-        return a.candidate.model_id == b.candidate.model_id and a.effort == b.effort
+        return a.candidate.model_id == b.candidate.model_id and a.level == b.level
 
     cost_rung = rung("cost", span[0])
     quality_rung = rung("quality", top)
@@ -1086,23 +1221,78 @@ def ladder(
             (r for r in options if not same(r, cost_rung) and not same(r, quality_rung)),
             options[0],
         )
-    balanced_rung = _below(balanced_rung, quality_rung)
-    cost_rung = _below(cost_rung, balanced_rung)
-    rungs = {"cost": cost_rung, "balanced": balanced_rung, "quality": quality_rung}
-    return Ladder(task=base, frontier=front, adequate=adequate, rungs=rungs)
+    balanced_rung = _below(balanced_rung, quality_rung, cat)
+    cost_rung = _below(cost_rung, balanced_rung, cat)
+    pool = funded or ranking.candidates
+    rungs = {
+        r.tier: replace(r, backup=_backup_for(r, pool, task, headroom, bench, cat))
+        for r in (cost_rung, balanced_rung, quality_rung)
+    }
+    warning: str | None = None
+    if any(r.backup is None for r in rungs.values()):
+        makers = sorted({c.provider for c in pool})
+        warning = (
+            f"No cross-provider backup: the models this user can run come from "
+            f"{', '.join(makers) or 'no maker'} only. Add a second maker's subscription or "
+            "API key so an outage or an exhausted pool has somewhere to go."
+        )
+    return Ladder(task=base, frontier=front, adequate=adequate, rungs=rungs, backup_warning=warning)
+
+
+def _backup_for(
+    rung: Rung,
+    pool: list[Candidate],
+    task: Task,
+    headroom: str,
+    bench: dict[str, Any],
+    catalog: dict[str, Any],
+) -> Backup | None:
+    """The rung's backup: the best substitute from another maker the operator
+    can run, at no higher list price.
+
+    Over the pool's models from a maker other than the rung model's, draw the
+    frontier and keep its adequate points. The backup is the adequate point
+    with the highest list price at or below the rung's; else the cheapest
+    adequate point above it; else, with no adequate point, the frontier's
+    strongest for the category. It runs at the rung's posture's effort on its
+    own platform. None when the pool holds no other maker's model."""
+    front = frontier([c for c in pool if c.provider != rung.candidate.provider], bench)
+    if not front:
+        return None
+    adequate = [p for p in front if p.candidate.requirement_penalty == 0]
+    if adequate:
+        within = [p for p in adequate if p.price_usd <= rung.point.price_usd]
+        chosen = within[-1] if within else adequate[0]
+    else:
+        chosen = max(front, key=lambda p: (p.candidate.quality, p.aa_index, -p.price_usd))
+    t = Task(task.category, task.complexity, task.novel, TIER_BUDGET[rung.tier])
+    c = chosen.candidate
+    effort = effort_for(t, headroom, c.scarcity)
+    return Backup(chosen, effort, native_level(c.platform_id, c.model_id, effort, catalog=catalog))
 
 
-def _below(lower: Rung, upper: Rung) -> Rung:
+def _below(lower: Rung, upper: Rung, catalog: dict[str, Any]) -> Rung:
     """``lower`` run at least one effort level below ``upper`` when both name
     the same model on the same platform and that path costs something
     (scarcity > 0); floored at the dial's lowest level, where the two may
     converge. Three columns that read the same offer no choice, and on a
     capped pool a lower effort is a real, cheaper option. On a free path
     (`uncapped`) a lower effort saves nothing, so the rungs keep their
-    posture's effort and converge."""
+    posture's effort and converge.
+
+    Levels are compared on the platform's own dial where the catalog
+    documents one, since two scorer levels can land on one native level
+    (Gemini's dial tops out at high, where the scorer's xhigh and max land
+    too); elsewhere on the scorer's ladder."""
     lc, uc = lower.candidate, upper.candidate
     if (lc.model_id, lc.platform_id) != (uc.model_id, uc.platform_id) or lc.scarcity == 0:
         return lower
+    levels = native_levels(lc.platform_id, lc.model_id, catalog=catalog)
+    if levels and lower.native in levels and upper.native in levels:
+        cap = max(0, levels.index(upper.native) - 1)
+        if levels.index(lower.native) <= cap:
+            return lower
+        return Rung(lower.tier, lower.point, _scorer_level(levels[cap]), levels[cap])
     cap = max(0, EFFORT_LADDER.index(upper.effort) - 1)
     if EFFORT_LADDER.index(lower.effort) <= cap:
         return lower
@@ -1165,14 +1355,19 @@ def render_ladder_table(table: dict[str, Ladder]) -> str:
             for p in any_ladder.frontier
         ),
         "Rows: <category>/<complexity>[/novel]: COST | BALANCED | QUALITY, each "
-        "<model> @ <platform> · <effort>.",
+        "<model> @ <platform> · <effort>, the effort in the platform's own level words, "
+        "then `backup <model> @ <platform>`: that pick's BACKUP.",
     ]
+
+    def cell(t: str, r: Rung) -> str:
+        text = f"{t.upper()} = {r.candidate.model_name} @ {r.candidate.platform_name} · {r.level}"
+        if r.backup is not None:
+            b = r.backup.candidate
+            text += f", backup {b.model_name} @ {b.platform_name}"
+        return text
+
     for key, lad in table.items():
-        cells = " | ".join(
-            f"{t.upper()} = {r.candidate.model_name} @ {r.candidate.platform_name} · {r.effort}"
-            for t in LADDER_TIERS
-            for r in [lad.rungs[t]]
-        )
+        cells = " | ".join(cell(t, lad.rungs[t]) for t in LADDER_TIERS)
         lines.append(f"{key}: {cells}")
     lines.append("</ladder-table>")
     return "\n".join(lines)