@bastani/atomic 0.9.18-alpha.4 → 0.9.18-alpha.6

package/docs/models/model-selection.md

@@ -14,12 +14,14 @@ This page gives workflow authors and runtime policy code a practical way to answ
 It is a **static reference**. It does not change runtime model routing — routing is configured elsewhere. Treat these recommendations as a starting point and validate against your own workflow evals.
 
 <Note>
-The table below is a snapshot of the [DeepSWE](https://deepswe.datacurve.ai/) leaderboard (v1.1, highest published thinking level per model), a long-horizon coding-agent benchmark reporting `pass@1` and average dollars per task. The source reports 113 tasks and was updated August 26, 2026. Benchmarks and pricing drift and new models ship constantly, so **treat the live leaderboards as authoritative** and refresh this page from them rather than hand-maintaining scores. See [Benchmark sources & when to reference each](/models/artificial-analysis-index). **Last compiled: 2026-09-01.**
+The table below is a snapshot of the [DeepSWE](https://deepswe.datacurve.ai/) leaderboard (v1.1, highest published thinking level per model), a long-horizon coding-agent benchmark reporting `pass@1` and average dollars per task. The source reports 113 tasks and was updated September 3, 2026. DeepSWE's own default table view is **Best** — the best-scoring configuration per model — so four models show a different row there than the highest-effort row used here; the snapshot note below the table names them. Benchmarks and pricing drift and new models ship constantly, so **treat the live leaderboards as authoritative** and refresh this page from them rather than hand-maintaining scores. See [Evals](/models/evals). **Last compiled: 2026-09-03.**
 </Note>
 
+Artificial Analysis was reviewed separately on **2026-09-05** against its September 4 Intelligence Index v4.2 revision. The DeepSWE table remains the September 3 snapshot; an independent September 5 browser check confirmed its update date and Gemini 3.8 Flash row, not every configuration.
+
 ## Benchmark levels are measurement settings
 
-The thinking level in brackets in the chart is the **measurement configuration used for that benchmark result**, not a universal workflow default. A score measured at `max` does not mean every stage using that model should use `max`; benchmark model identity and production thinking effort are separate choices. When authoring a workflow, choose effort from the stage role and cost of being wrong, then verify that the configured model catalog supports the level.
+The thinking level in brackets in the chart is the **measurement configuration used for that benchmark result**, not a universal workflow default. A score measured at `max` does not mean every stage using that model should use `max`; benchmark model identity and production thinking effort are separate choices. When authoring a workflow, choose effort from the stage role and cost of being wrong, then check the returned `availableThinkingLevels` for the configured catalog model.
 
 ## Pin model identity
 
@@ -28,41 +30,74 @@ bare model ID: the same exact model ID can belong to more than one provider. For
 uses the sole matching provider with configured authentication; if none or more than one match is authenticated, it
 reports the ambiguity. Use `--provider <provider> --model <id>` or `--model <provider>/<id>` to choose explicitly.
 
+## AA cross-check for current candidates
+
+These are selected candidates, not a replacement DeepSWE frontier. The linked model pages and [rendered AA highlights](https://artificialanalysis.ai/) were retrieved **2026-09-05** under Intelligence Index **v4.2**, announced **2026-09-04**. Model-page metrics have no separate visible update timestamp. Scores are index points, not pass percentages; cost is weighted USD per **AA Intelligence Index task**, not DeepSWE cost. Speed is the model-page summary in standardized output tokens per second, not full-task latency.
+
+| Model and AA measurement configuration | Intelligence Index | AA $/task | Output tokens/s | Candidate role and tradeoff |
+| --- | --- | --- | --- | --- |
+| [Claude Fable 5.1, Adaptive Reasoning, Max Effort, Default Fallback](https://artificialanalysis.ai/models/claude-fable-5-1) | 57 | $6.12 | 68.7 | Quality-first planning and judgment candidate; leads AA's displayed intelligence highlights, but has the highest task cost of this shortlist |
+| [GPT-6 Astra, max](https://artificialanalysis.ai/models/gpt-6-astra) | 55 | $2.57 | 87.5 | High-stakes planning and document-reasoning candidate with lower AA task cost than Fable 5.1 |
+| [Gemini 3.8 Flash, high](https://artificialanalysis.ai/models/gemini-3-8-flash) | 47 | $0.74 | Not reported | Cost-conscious coding candidate with strong separate DeepSWE evidence; do not invent API speed from its token price |
+| [GPT-5.6 Luna, max](https://artificialanalysis.ai/models/gpt-5-6-luna) | 43 | $0.10 | 134.8 | Budget research and worker candidate when its lower measured quality is acceptable |
+
+AA's [v4.2 announcement](https://artificialanalysis.ai/articles/artificial-analysis-intelligence-index-v4-2) places Fable 5.1 and Opus 5 ahead on AA-Briefcase, while Astra leads GDP.pdf. The measured numbers behind that: Fable 5.1 max and Opus 5 max score 58% on AA-Briefcase and 63% and 62% on GDPval-AA v2, against 53% and 54% for Astra max; Astra max scores 33% on GDP.pdf against 26% for Fable 5.1 max and 22% for Opus 5 max. Use those task-specific signals for knowledge-work planning versus document research; the full per-evaluation tables for every catalog model are in [Evals](/models/evals#per-evaluation-scores-for-catalog-models), with a [task-type picker](/models/evals#pick-by-task-type) at the top of that page. An aggregate lead does not establish security-review reliability or the best model for every role. Keep Fable's **Default Fallback** qualifier: this is not evidence for an arbitrary no-fallback configuration.
+
+The separate [Coding Agent Index v1.4](https://artificialanalysis.ai/agents/coding-agents), also retrieved 2026-09-05, reports **Claude Code - Fable 5.1 (max) (with fallback)** at **70**, **$9.18/task** and **24.0 minutes agent wall time/task**, versus **Opencode - Gemini 3.8 Flash (high)** at **61**, **$2.04/task** and **11.9 minutes**, and **Codex - GPT-5.6 Luna (max)** at **57**, **$0.29/task** and **8.0 minutes**. Those agent-specific measurements illustrate a quality/cost/time tradeoff; neither is an Atomic result or a base-model score. Fable 5.1 is measured there even though it is absent from the Datacurve snapshot below. All fourteen rows, with their DeepSWE, Terminal-Bench and SWE-Atlas-QnA components, are tabulated in [Evals](/models/evals#coding-agent-index-v14-is-a-different-comparison); read the methodology and units there before combining evidence.
+
 ## Recommendation chart
 
-The current highest-effort-config Pareto frontier is **claude-opus-5** (accuracy ceiling), **gpt-5.6-sol**, **glm-5.3**, **gpt-5.6-luna**, and **glm-5.3-flash** (cheapest point). Everything else displayed on the live DeepSWE leaderboard is dominated on cost and accuracy and earns a place only through role fit or provider diversity. For the frontier reasoning, see [Pareto Efficiency](/models/pareto-efficiency).
+The current highest-effort-config Pareto frontier is **gemini-3.8-flash** (accuracy ceiling), **gpt-5.6-luna**, and **glm-5.3-flash** (cheapest point). It collapsed from five members to three when Gemini 3.8 Flash landed on September 1, 2026: at 73.83% unrounded it edges out claude-opus-5's 73.65% — both display 74% — for $2.36 against $11.84, which pushes claude-opus-5, gpt-5.6-sol, and glm-5.3 off the frontier. Everything else displayed on the live DeepSWE leaderboard is dominated on cost and accuracy and earns a place only through role fit or provider diversity. For the frontier reasoning, see [Pareto Efficiency](/models/pareto-efficiency).
 
 | Model [benchmark measurement level] | pass@1 | $/task | Verdict | Use it for |
 | --- | --- | --- | --- | --- |
-| claude-opus-5 [max] | 74% | $11.84 | Accuracy ceiling / frontier | Final approval and the hardest debugging when one more point can justify the cost |
-| gpt-5.6-sol [max] | 73% | $6.46 | Frontier | High-cost judgment gates; nearly the top score for about half the task cost of Opus 5 |
-| gpt-5.6-terra [max] | 70% | $3.96 | Historical — off the live board | Last published measurement; not displayed on the August 26 leaderboard, so re-verify before relying on it |
-| claude-fable-5 [max] | 70% | $21.63 | Drop | Sol matches or beats its score for much less |
-| glm-5.3 [max] | 69% | $3.99 | Frontier — open-weights value | Best open-weights mid-tier cost/accuracy point; matches Kimi K3's rounded score for less |
+| gemini-3.8-flash [high] | 74% | $2.36 | Frontier — accuracy ceiling and best value | Judgment gates, hard debugging, and any role that wants top accuracy without top-tier cost; budget for 166 average steps and 143k output tokens per task |
+| claude-opus-5 [max] | 74% | $11.84 | Dominated — top-tier role fit | Final approval and the hardest debugging when Anthropic-family behavior is specifically wanted; it matches Gemini 3.8 Flash's rounded 74% but costs $9.48 more per task |
+| gpt-6-astra [max] | 73% | $12.37 | Dominated — new arrival | Added September 3, 2026 at DeepSWE's expected launch pricing rather than billed rates; its 28 average steps are the fewest of any row in this table, but Opus 5 scores higher for less |
+| gpt-5.6-sol [max] | 73% | $6.46 | Near-peer, no longer on the frontier | High-cost judgment gates where OpenAI-family behavior is wanted; still about half Opus 5's task cost, but Gemini 3.8 Flash is more accurate at just over a third of Sol's task cost |
+| gpt-5.6-terra [max] | 70% | $3.96 | Historical — outside the default selection | Last published measurement, re-verified unchanged in the September 3, 2026 artifact; DeepSWE deselects it by default, so re-enable it on the live page before relying on it |
+| claude-fable-5 [max] | 70% | $21.63 | Drop | Sol matches or beats its score for much less, and Gemini 3.8 Flash is four rounded points better for about a ninth of the task cost |
+| glm-5.3 [max] | 69% | $3.99 | Best open-weights value, off the frontier | Best open-weights mid-tier cost/accuracy point; matches Kimi K3's rounded score for less, though Gemini 3.8 Flash is five rounded points better for $1.63 less |
 | kimi-k3 [max] | 69% | $4.65 | Dominated | GLM-5.3 matches its rounded score for $0.66 less; Moonshot-family diversity only |
-| gpt-5.6-luna [max] | 67% | $0.61 | Frontier — best general value | Research, orchestration, workers, and code simplification |
+| gpt-5.6-luna [max] | 67% | $0.61 | Frontier — cheapest broadly-capable point | Research, orchestration, workers, and code simplification |
 | gpt-5.5 [xhigh] | 67% | $7.23 | Superseded | Luna matches its score for less than one tenth of the task cost |
 | grok-4.6 [xhigh] | 67% | $5.50 | Provider fallback | xAI diversity; Luna has the same rounded score at lower DeepSWE task cost |
-| gemini-3.7-flash [high] | 65% | $2.18 | Provider fallback | Strong Google-family result, but Luna is cheaper and more accurate |
+| gemini-3.7-flash [high] | 65% | $2.18 | Provider fallback | Strong Google-family result, but Luna is cheaper and more accurate, and Gemini 3.8 Flash supersedes it inside the Google family at 74% for $2.36 |
 | glm-5.3-flash [max] | 63% | $0.24 | Frontier — cheapest | Budget worker loops that can accept lower accuracy and 123 average steps |
 | deepseek-v4-pro [max] | 63% | $1.67 | Dominated / provider fallback | DeepSeek diversity only; GLM-5.3 Flash has a higher unrounded score, fewer steps, and about one seventh of the cost |
 | claude-opus-4.8 [max] | 59% | $13.22 | Fallback only | Anthropic diversity and long-context behavior, not cost efficiency |
 | qwen3.8-max [xhigh] | 57% | $3.73 | Provider fallback | Qwen diversity only; GLM-5.3 Flash and Luna dominate it |
 | muse-spark-1.2 [xhigh] | 55% | $3.70 | Drop | GLM-5.3 Flash is cheaper and more accurate |
 | claude-sonnet-5 [max] | 54% | $26.40 | Drop everywhere | Highest task cost and 268 average steps for a mid-table score |
-| grok-4.5 [high] | 54% | $2.42 | Historical — off the live board | Last published measurement; superseded by Grok 4.6 and dominated by current frontier models |
+| grok-4.5 [high] | 54% | $2.42 | Historical — outside the default selection | Last published measurement, re-verified unchanged; superseded by Grok 4.6 and dominated by current frontier models |
 | deepseek-v4-flash [max] | 53% | $0.46 | Dominated / provider fallback | DeepSeek diversity only; GLM-5.3 Flash is ten points more accurate for about half the cost |
-| muse-spark-1.1 [xhigh] | 53% | $2.36 | Historical — off the live board | Last published measurement; replaced by Muse Spark 1.2 and dominated by current frontier models |
-| gpt-5.4 [xhigh] | 52% | $5.65 | Historical — off the live board | Last published measurement; Luna is cheaper and 15 points more accurate |
+| muse-spark-1.1 [xhigh] | 53% | $2.36 | Historical — outside the default selection | Last published measurement, re-verified unchanged; replaced by Muse Spark 1.2 and dominated by current frontier models |
+| gpt-5.4 [xhigh] | 52% | $5.65 | Historical — outside the default selection | Last published measurement, re-verified unchanged; Luna is cheaper and 15 points more accurate |
 | gemini-3.6-flash [high] | 47% | $2.21 | Drop from reasoning | Superseded by Gemini 3.7 Flash |
 | glm-5.2 [max] | 44% | $3.92 | Superseded | Measured predecessor only; do not relabel this as GLM-5.3 |
 | gemini-3.5-flash [high] | 36% | $3.45 | Drop from reasoning | Retain only where a low-effort retrieval role has separate evidence |
-| kimi-k2.7-code | 31% | $2.82 | Historical — off the live board | Last published measurement had no effort level; Kimi K3 is the current family fallback |
-| claude-sonnet-4.6 [high] | 30% | $5.52 | Historical — off the live board | Last published measurement; removed from all chains |
-| gemini-3.1-pro-preview [high] | 12% | $2.14 | Historical — off the live board | Last published measurement; removed from all chains |
+| kimi-k2.7-code | 31% | $2.82 | Historical — outside the default selection | Last published measurement had no effort level; Kimi K3 is the current family fallback |
+| claude-sonnet-4.6 [high] | 30% | $5.52 | Historical — outside the default selection | Last published measurement, re-verified unchanged; removed from all chains |
+| gemini-3.1-pro-preview [high] | 12% | $2.14 | Historical — outside the default selection | Last published measurement, re-verified unchanged; the live page labels it `gemini-3.1-pro`; removed from all chains |
 
 <Note>
-DeepSWE values above use the v1.1 results displayed on the August 26, 2026 leaderboard, including the August 21 pricing corrections for GPT-5.6 Sol and DeepSeek V4. Sol's cost reflects OpenAI's promotional input and output price cut through at least November 21, 2026. DeepSWE uses DeepSeek's peak rates; its off-peak rates are half as much. `pass@1` is rounded as on the live leaderboard and confidence intervals are omitted here. The highest published thinking level is a measurement choice, not a production default. Seven historical configurations are retained with their last published values because they are no longer displayed: GPT-5.6 Terra, Grok 4.5, Muse Spark 1.1, GPT-5.4, Kimi K2.7 Code, Claude Sonnet 4.6, and Gemini 3.1 Pro Preview. See the live page for intervals, output tokens, steps, lower-effort configurations, and later corrections.
+DeepSWE values above use the v1.1 results published in the September 3, 2026 snapshot, including the August 21 pricing corrections for GPT-5.6 Sol and DeepSeek V4. Sol's cost reflects OpenAI's promotional input and output price cut through at least November 21, 2026. DeepSWE uses DeepSeek's peak rates; its off-peak rates are half as much. GPT-6 Astra's DeepSWE costs are expected-launch-pricing estimates rather than billed rates; that caveat does not describe the separately sourced AA costs above. `pass@1` is rounded as on the live leaderboard and confidence intervals are omitted here — but note that the top of the board is a cluster: the top three rows span less than a point unrounded, well inside DeepSWE's published run-to-run intervals, so read a one-row lead as a tie. The highest published thinking level is a measurement choice, not a production default, and DeepSWE's own data shows effort saturation: for GPT-6 Astra, Claude Fable 5, Grok 4.6, and Gemini 3.7 Flash the best-scoring configuration is *not* the highest one. That is why DeepSWE's default "Best" table view displays four rows this table does not: `gpt-6-astra [xhigh]` at 74% for $6.52 with 29 average steps, `claude-fable-5 [xhigh]` at 70% for $13.41, `grok-4.6 [medium]` at 67% for $3.45, and `gemini-3.7-flash [medium]` at 65% for $2.03. Seven measured configurations are retained here with their last published values because DeepSWE excludes them from its default model selection, not because they were withdrawn; each was re-verified unchanged against the September 3, 2026 artifact and can be re-enabled in the site's model picker: GPT-5.6 Terra, Grok 4.5, Muse Spark 1.1, GPT-5.4, Kimi K2.7 Code, Claude Sonnet 4.6, and Gemini 3.1 Pro Preview. Atomic now ships GPT-6 Astra through its built-in OpenAI, OpenAI Codex, and Amazon Bedrock catalogs. A benchmark row still does not prove that the current account has provider access, so run `workflow({ action: "models" })` or `--list-models` before pinning Astra or another catalog model. See the live page for intervals, output tokens, steps, lower-effort configurations, and later corrections.
+</Note>
+
+<Note>
+**Claude Fable 5.1 is in Atomic's catalog and is not in the DeepSWE table above.** It was released September 1, 2026 and is absent from the September 3, 2026 Datacurve DeepSWE snapshot, so it has no measured `pass@1` or `$/task` in that snapshot. It does have AA Intelligence Index and Coding Agent Index measurements, described above. Do not read the `claude-fable-5` row as a Fable 5.1 result or transfer its score. Evaluate Fable 5.1 on your own workflow before promoting it into a stage.
+
+What is source-backed for `claude-fable-5-1` today, from [Anthropic's model overview](https://platform.claude.com/docs/en/models/fable-5-1/overview): a 1M-token context window and 128K maximum output; adaptive thinking that is always on, with effort `low`, `medium`, `high`, `xhigh`, and `max` and an Anthropic default of `high`; a June 2026 knowledge cutoff; and $10 input, $50 output, $12.50 five-minute cache write, $20 one-hour cache write, and $0.25 cache read per million tokens. The cache read is a quarter of Fable 5's $1.00, which is the main pricing reason to prefer it for long agentic sessions that re-read a cached prefix. Non-default `temperature`, `top_p`, and `top_k` return a 400 on every request, so Atomic omits `temperature` for this model.
+
+Atomic generates Fable 5.1 for the providers it has a matching runtime integration for. At the time of writing that is Anthropic, GitHub Copilot, three Amazon Bedrock inference profiles (`anthropic.`, `global.`, and `us.`), OpenRouter, and the Vercel AI Gateway. GitHub Copilot includes Fable 5 and Fable 5.1 in its static catalog from models.dev metadata, but its authenticated picker still decides which models each account may select. A provider "latest" alias such as OpenRouter's `~anthropic/claude-fable-latest` may also route to Fable 5.1 without naming it. That set genuinely moves — opencode zen published the model and then withdrew it while this page was being written — so run `workflow({ action: "models" })` or `--list-models` for the current list rather than trusting this one. Published catalogs also list the model on Google Vertex, Google Vertex (Anthropic), Azure, and Azure Cognitive Services; Atomic has no Claude runtime integration for those providers and generates no entries for them, which is a current limitation rather than a roadmap commitment. What does *not* vary is the invariant that matters: **Atomic's preserved-thinking handling is scoped to `provider: "anthropic"` on the `anthropic-messages` API and applies to none of the other mirrors** — including GitHub Copilot and the Vercel AI Gateway, which ride `anthropic-messages` but are deliberately excluded. See [Preserved thinking and model switches](/models#preserved-thinking-and-model-switches).
+</Note>
+
+<Note>
+**Gemini 3.8 Flash is in Atomic's catalog and is measured in the DeepSWE table above.** A separate read of [Datacurve's rendered leaderboard](https://deepswe.datacurve.ai/) on **2026-09-05** confirmed its September 3, 2026 snapshot and the `gemini-3.8-flash [high]` row at **74% pass@1, $2.36/task, 143k output tokens and 166 steps**. These are its own measurements, not Gemini 3.7 Flash's. Its AA measurements above are a separate experiment, and neither benchmark proves access through your configured provider.
+
+For `gemini-3.8-flash`, [Google's model page](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/3-8-flash) and [developer's guide](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/guides/gemini-3-8-flash), both updated September 3 and retrieved 2026-09-05, report a 1,048,576-token context window, 65,536 maximum output tokens, multimodal input with text output, and thinking levels `low`, `medium`, and `high`. The [September 2 model card](https://deepmind.google/models/model-cards/gemini-3-8-flash/), retrieved 2026-09-05, states a March 2026 knowledge cutoff, with some domains limited to January 2025. AA's model page above lists $0.75 input and $3.75 output per million tokens; Google's published cache-read rate is $0.075. These are token prices, not the measured task costs above. Atomic advertises `text` and `image` input because those are the inputs it can serialize on the Gemini path. Thinking cannot be turned off, and Google's guide states that `MINIMAL` is unsupported, so the Google, Google Vertex, and opencode zen entries offer `low`, `medium`, and `high`. Google stopped publishing `MINIMAL` from Gemini 3.7 Flash onward; Atomic's 3.7 Flash entries still offer it, which is a separate pre-existing gap.
+
+Atomic generates entries only from the upstream provider catalogs it supports, so the exact provider set and metadata can change. Run `workflow({ action: "models" })` or `--list-models` for the current result. The current models.dev GitHub Copilot row advertises a 1,000,000-token context window, 64,000 maximum output tokens, and `low`, `medium`, and `high` reasoning efforts. Atomic consumes that row without supplementing or overriding it and routes it through Copilot's OpenAI-compatible endpoint. Copilot availability still depends on GitHub's rollout and administrator policy. The Vercel AI Gateway currently advertises a 1,000,000-token context window and no per-model thinking levels, so its entry offers `off` and `minimal` alongside the three Google levels.
 </Note>
 
 ## Role-based thinking effort
@@ -80,20 +115,20 @@ Reserve `max` for a high-cost-of-error role or an explicit user request. An expl
 
 ## Scenario-based guidance
 
-Pick by the cost of being wrong in each role, not by raw accuracy. Match the role to the benchmark that best measures it (see [Benchmark sources](/models/artificial-analysis-index)).
+Pick by the cost of being wrong in each role, not by raw accuracy. Match the role to the benchmark that best measures it (see [Evals](/models/evals) and its [task-type picker](/models/evals#pick-by-task-type)). The percentages below are AA per-evaluation scores read on 2026-09-05 for the named configuration.
 
-- **Reviewer / judgment gates** — use `max` when the reviewer makes a security, identity, adversarial, or final-approval decision whose wrong verdict discards an entire loop. `claude-opus-5` is the DeepSWE accuracy ceiling; `gpt-5.6-sol` is the lower-cost near-peer. Use another family when decorrelated errors matter.
-- **Codebase mapping / planner** — start at `high` for repository mapping, lifecycle analysis, compatibility, and plans. `gpt-5.6-sol` is the strongest top-tier value at its measured `max` configuration, and `glm-5.3` holds the open-weights mid tier; raise production effort to `max` only when the plan gates a high-cost loop or the user asks for it.
-- **Debugger / triage / repair** — start at `high`; deep reasoning pays off when root-causing or repairing is costly. Weight DeepSWE and Terminal-Bench together rather than treating either as a complete measure.
-- **Research / synthesis** — use `high` for demanding research and evidence reconciliation; use `medium` for routine synthesis when the evidence is already strong. `gpt-5.6-luna` remains the workhorse. Benchmark to weight: AA-LCR and AA-Omniscience.
-- **Orchestrator / worker / cheap loops** — Luna offers the best broad cost/accuracy balance. GLM-5.3 Flash is the cheapest live frontier point at 63% for $0.24 with 123 average steps. DeepSeek V4 Pro and Flash are provider-diversity options, not budget-frontier choices.
+- **Reviewer / judgment gates** — use `max` when the reviewer makes a security, identity, adversarial, or final-approval decision whose wrong verdict discards an entire loop. `gemini-3.8-flash` is the DeepSWE accuracy ceiling and reaches it at a fraction of top-tier cost; `claude-opus-5` and `gpt-5.6-sol` are the near-peers when a different family is wanted. For code-reading judgments, the Anthropic rows separate: Claude Code + Fable 5.1 and + Opus 5 score 56% and 55% on SWE-Atlas-QnA against 51% for Codex + Astra and 38% for Opencode + Gemini 3.8 Flash. Use another family when decorrelated errors matter.
+- **Codebase mapping / planner** — start at `high` for repository mapping, lifecycle analysis, compatibility, and plans. Gemini 3.8 Flash is a cost-conscious coding candidate but near the bottom of the catalog on AA-Briefcase (35%; only Gemini 3.7 Flash is lower at 31%); for plans that resemble knowledge work, Fable 5.1 max and Opus 5 max (58%) or, on a budget, GLM-5.3-Flash (48% for $0.18 per AA task) measure better. Raise production effort only when the plan gates a high-cost loop or the user asks, and only to a level advertised by that exact catalog entry.
+- **Debugger / triage / repair** — start at `high`; deep reasoning pays off when root-causing or repairing is costly. Weight DeepSWE and Terminal-Bench together rather than treating either as a complete measure: Terminal-Bench v2.1 is flat at 88–91% across Fable 5.1 max, Astra at every effort, Sol max and xhigh, Opus 5 max through high, Terra max and Gemini 3.8 Flash high, so DeepSWE cost and steps decide among them.
+- **Research / synthesis** — use `high` for demanding research and evidence reconciliation; use `medium` for routine synthesis when the evidence is already strong. `gpt-5.6-luna` is the budget starting point for long-context work (84% on AA-LCR v1.1 for $0.10 per AA task), but it abstains only 7% of the time on AA-Omniscience, so back it with verification tool nodes; evaluate Astra (33% GDP.pdf All-pass, the leader) when document-reasoning failures justify more cost, and GLM-5.3-Flash or GLM-5.3 (72% and 70% non-hallucination) when a wrong fact is worse than an abstention. Weight AA-LCR v1.1, GDP.pdf and AA-Omniscience rather than general intelligence alone.
+- **Orchestrator / worker / cheap loops** — Luna offers the best broad cost/accuracy balance for code, but scores 31% on 𝜏³-Banking, the lowest catalog row, so prefer GLM-5.3-Flash (47%) or Muse Spark 1.3 (52%) when the loop is tool-call heavy. GLM-5.3 Flash is the cheapest live frontier point at 63% for $0.24 with 123 average steps. Gemini 3.8 Flash is the most accurate frontier point but averages 166 steps and 143k output tokens per task, which makes it a judgment-gate choice rather than an automatic worker default. DeepSeek V4 Pro and Flash are provider-diversity options, not budget-frontier choices.
 - **User-impact review / final reporting** — use `medium` for impact summaries and reports that preserve the evidence needed by the user. Do not spend `max` here unless the user explicitly requests it or the role has become a high-cost-of-error approval.
-- **Design** — a quality-first, unbenchmarked domain; keep a top-tier model (`gpt-5.6-sol` or `claude-fable-5`) when the design decision has high failure cost, and choose effort by the review or approval role rather than by the benchmark row.
+- **Design** — a quality-first domain not directly measured by these coding tables. Choose effort by the review or approval role. Fable 5.1's AA-Briefcase results make it a candidate for knowledge-work deliverables, not proof of product-design quality; evaluate it on the intended design tasks and do not carry Fable 5's DeepSWE row over to it.
 - **Interactive coding sessions** — use `high` for complex, multi-step coding and `medium` for routine edits; reserve `max` for a high-cost-of-error judgment or an explicit user request.
 - **Deterministic checks** — make typechecks, tests, schema validation, runtime probes, and artifact inspection tool nodes with no model call. Model self-report is not verification evidence.
 
 ## Related
 
 - [Pareto Efficiency](/models/pareto-efficiency) — cost-vs-accuracy frontier, dominated models, and provider-diversity exceptions.
-- [Benchmark sources & when to reference each](/models/artificial-analysis-index) — what Artificial Analysis and DeepSWE measure, per benchmark, and how to keep these docs fresh from the live source.
+- [Evals](/models/evals) — what Artificial Analysis and DeepSWE measure, per benchmark, and how to keep these docs fresh from the live source.
 - [Custom models](/models) — how to add model entries for supported provider APIs.

package/docs/models/pareto-efficiency.md

@@ -10,43 +10,56 @@ A model is **Pareto-efficient** (on the frontier) if no other model is both chea
 The axes here are `pass@1` (accuracy) and `average dollars per task` (cost), taken from the [DeepSWE](https://deepswe.datacurve.ai/) coding-agent leaderboard. For the full table and role guidance, see [Model Selection](/models/model-selection).
 
 <Note>
-Figures are a snapshot of DeepSWE v1.1 using the highest published thinking level for each of the 19 models displayed on the August 26, 2026 leaderboard. They include the August 21 pricing corrections for GPT-5.6 Sol and DeepSeek V4. DeepSWE publishes a live cost-vs-score scatter, so **read the frontier off the live chart** rather than trusting a static list. **Last compiled: 2026-09-01.**
+Figures are a snapshot of DeepSWE v1.1 using the highest published thinking level for each of the 21 models displayed on the September 3, 2026 leaderboard. They include the August 21 pricing corrections for GPT-5.6 Sol and DeepSeek V4, and GPT-6 Astra's costs are DeepSWE's expected launch pricing rather than billed rates. DeepSWE's own default table view is **Best** — the best-scoring configuration per model — which picks a different row for four models; the frontier under that reading is stated below. DeepSWE publishes a live cost-vs-score scatter, so **read the frontier off the live chart** rather than trusting a static list. **Last compiled: 2026-09-03.**
 </Note>
 
+The [AA review](/models/evals) is separately dated **2026-09-05**. AA Intelligence Index v4.2 uses weighted intelligence and its own cost per task; AA Coding Agent Index v1.4 uses agent-specific runs across several benchmarks. Neither defines the Datacurve frontier on this page. A September 5 browser check confirmed the September 3 DeepSWE update and Gemini 3.8 Flash's measured row, without recomputing this entire snapshot.
+
 ## The frontier
 
-Five displayed highest-effort model configurations sit on the frontier, from the cheapest measured task cost to the accuracy ceiling:
+Three displayed highest-effort model configurations sit on the frontier, from the cheapest measured task cost to the accuracy ceiling:
 
 - **glm-5.3-flash [max]**: 63% for $0.24 with 123 average steps. This is the cheapest point.
-- **gpt-5.6-luna [max]**: 67% for $0.61. This is the best broad value on the board.
-- **glm-5.3 [max]**: 69% for $3.99 with 124 average steps. This is the open-weights mid-tier point and matches Kimi K3's rounded score for less.
-- **gpt-5.6-sol [max]**: 73% for $6.46 with 61 average steps. This is the lower-cost near-peer to the accuracy leader.
-- **claude-opus-5 [max]**: 74% for $11.84 with 99 average steps. This is the current accuracy ceiling.
+- **gpt-5.6-luna [max]**: 67% for $0.61 with 102 average steps. This is the cheapest broadly-capable point.
+- **gemini-3.8-flash [high]**: 74% for $2.36 with 166 average steps and 143k output tokens. This is the current accuracy ceiling, and also the step-heaviest point on the frontier — weigh that before making it a worker default.
+
+Under DeepSWE's default **Best** view, which selects each model's best-scoring configuration instead of its highest effort, these three points still hold and `gpt-6-astra [xhigh]` joins as a fourth member and the accuracy ceiling, at 74.12% unrounded for $6.52 with 29 average steps. That is a frontier position under that reading only: at its highest published effort (`max`, 73.23% for $12.37) GPT-6 Astra is dominated by both Gemini 3.8 Flash and Claude Opus 5. The same view also shows `claude-fable-5 [xhigh]` at 70% for $13.41, `grok-4.6 [medium]` at 67% for $3.45, and `gemini-3.7-flash [medium]` at 65% for $2.03, none of which reach the frontier.
 
 ## What changed
 
-The August 26 snapshot moves the budget end of the frontier and lowers the cost of its upper end:
+The September 3 snapshot collapses the frontier from five members to three:
+
+- **Gemini 3.8 Flash [high]**, added September 1, 2026, arrives at 74% for $2.36 and takes the accuracy ceiling. Rounded scores cannot settle the top of this board: Gemini 3.8 Flash and Claude Opus 5 both display 74%, and only the unrounded rates — 73.83% against 73.65% — order them. The dominance holds either way, because the cheaper model is also $9.48 less per task, about one fifth of Opus 5's cost.
+- **claude-opus-5 [max]**, **gpt-5.6-sol [max]**, and **glm-5.3 [max]** leave the frontier. None of their numbers moved; a cheaper and more accurate point simply appeared above all three.
+- **GPT-6 Astra**, added September 3, 2026 across low, medium, high, xhigh, and max effort, does not join at its highest published effort: `[max]` scores 73% for $12.37 and is dominated by both Gemini 3.8 Flash and Claude Opus 5. DeepSWE priced it at the expected launch rate card, so treat every Astra dollar figure as projected rather than billed.
+- **glm-5.3-flash [max]** and **gpt-5.6-luna [max]** are unchanged and keep the budget end of the frontier.
+
+The August pricing corrections still stand and still explain that budget end:
 
-- **GLM-5.3 Flash [max]** now appears at 63% for $0.24 with 123 average steps. It replaces both DeepSeek V4 configurations on the budget frontier.
-- **DeepSeek V4 Pro [max]** now costs $1.67 per task after DeepSeek's August 16 price change. GLM-5.3 Flash has a higher unrounded score (63.4% versus 62.8%), costs about one seventh as much, and averages 32 fewer steps.
-- **DeepSeek V4 Flash [max]** now costs $0.46 per task. GLM-5.3 Flash is ten rounded points more accurate and costs about half as much.
-- **GPT-5.6 Sol [max]** now costs $6.46 per task after OpenAI's August 20 promotional price cut, down from $8.39 in the previous snapshot. The reduced input and output rates run through at least November 21, 2026.
+- **GLM-5.3 Flash [max]** appears at 63% for $0.24 with 123 average steps. It replaced both DeepSeek V4 configurations on the budget frontier.
+- **DeepSeek V4 Pro [max]** costs $1.67 per task after DeepSeek's August 16 price change. GLM-5.3 Flash has a higher unrounded score (63.4% versus 62.8%), costs about one seventh as much, and averages 32 fewer steps.
+- **DeepSeek V4 Flash [max]** costs $0.46 per task. GLM-5.3 Flash is ten rounded points more accurate and costs about half as much.
+- **GPT-5.6 Sol [max]** costs $6.46 per task after OpenAI's August 20 promotional price cut, down from $8.39 in the earlier snapshot. The reduced input and output rates run through at least November 21, 2026.
 
 DeepSWE's August 21, 2026 changelog says these DeepSeek costs use peak rates and off-peak rates are half as much. DeepSeek V4 Pro remains dominated at either rate. At the off-peak rate, DeepSeek V4 Flash costs about $0.23, marginally less than GLM-5.3 Flash's $0.24, but remains ten rounded points less accurate; these pages report the frontier from DeepSWE's published peak-rate costs.
 
 ## Dominated models and why
 
+- **claude-opus-5 [max]**: Gemini 3.8 Flash is more accurate unrounded (73.83% versus 73.65%; both display 74%) and costs $9.48 less per task. Opus 5 keeps a role only as the Anthropic entry in the accuracy-ceiling class.
+- **gpt-6-astra [max]**: dominated twice over — Claude Opus 5 scores higher for $0.53 less, and Gemini 3.8 Flash scores higher for $10.01 less. Its costs are expected launch pricing, not billed rates.
+- **gpt-5.6-sol [max]**: Gemini 3.8 Flash is more accurate and costs just over a third as much. Sol remains the OpenAI-family near-peer at about half of Opus 5's task cost.
+- **glm-5.3 [max]**: Gemini 3.8 Flash is five rounded points more accurate and costs $1.63 less. GLM-5.3 stays the best open-weights point on the board.
 - **deepseek-v4-pro [max]**: GLM-5.3 Flash has a higher unrounded score, costs $1.43 less, and averages 123 steps instead of 155.
 - **deepseek-v4-flash [max]**: GLM-5.3 Flash is ten rounded points more accurate and costs $0.22 less.
-- **claude-fable-5 [max]**: Sol is more accurate and much cheaper; GLM-5.3 comes within a point for less than one fifth of the task cost.
+- **claude-fable-5 [max]**: Sol is more accurate and much cheaper; GLM-5.3 comes within a point for less than one fifth of the task cost. This row is Fable 5 only; `claude-fable-5-1` is still unmeasured in the September 3, 2026 snapshot and has no measured position on the frontier.
 - **kimi-k3 [max]**: GLM-5.3 matches its rounded score and is $0.66 cheaper; Kimi remains useful for Moonshot-family diversity.
 - **gpt-5.5 [xhigh]** and **grok-4.6 [xhigh]**: Luna matches their rounded 67% for $0.61.
-- **gemini-3.7-flash [high]**: Luna is two points more accurate and costs less than one third as much.
+- **gemini-3.7-flash [high]**: Luna is two points more accurate and costs less than one third as much. This row is Gemini 3.7 Flash only. Gemini 3.8 Flash has its own measured `[high]` row and frontier position above; it does not inherit its predecessor's result.
 - **muse-spark-1.2 [xhigh]**: GLM-5.3 Flash is eight points more accurate and costs $3.46 less.
 - **claude-opus-4.8 [max]** and **claude-sonnet-5 [max]**: each is dominated on both cost and accuracy.
 - **qwen3.8-max [xhigh]**, **gemini-3.6-flash [high]**, **gemini-3.5-flash [high]**, and **glm-5.2 [max]**: each has a cheaper, more accurate displayed alternative.
 
-Seven measured configurations are no longer displayed on the live leaderboard and are excluded from this current frontier calculation. [Model Selection](/models/model-selection) keeps their last published values as clearly labeled history: GPT-5.6 Terra, Grok 4.5, Muse Spark 1.1, GPT-5.4, Kimi K2.7 Code, Claude Sonnet 4.6, and Gemini 3.1 Pro Preview.
+Seven measured configurations are excluded from DeepSWE's default model selection and therefore from this frontier calculation. They are still in the current v1.1 artifact and can be re-enabled in the site's model picker, so this is a display default rather than a withdrawal. [Model Selection](/models/model-selection) keeps their last published values as clearly labeled history, each re-verified unchanged against the September 3, 2026 artifact: GPT-5.6 Terra, Grok 4.5, Muse Spark 1.1, GPT-5.4, Kimi K2.7 Code, Claude Sonnet 4.6, and Gemini 3.1 Pro Preview.
 
 ## Diversity and role-fit exceptions
 
@@ -57,7 +70,12 @@ Efficiency is not the only axis. A dominated model can still earn a slot when it
 - **glm-5.2 [max]** remains only as a measured predecessor; its results are never relabeled as GLM-5.3 or GLM-5.3 Flash.
 - **kimi-k3** remains a Moonshot-family provider-diversity option despite GLM-5.3's strict DeepSWE dominance.
 - **claude-opus-4.8 [max]** remains useful where Anthropic diversity or its long-context behavior has separate value.
+- **claude-opus-5 [max]** is dominated now but remains the Anthropic model in the accuracy-ceiling class, which matters when a judgment gate needs decorrelated errors from a different family than the frontier ceiling.
+- **gpt-5.6-sol [max]** is the OpenAI-family near-peer to the ceiling and stays the top-tier choice when Google-family routing is unavailable or unwanted.
+- **glm-5.3 [max]** remains the best open-weights point; the new frontier ceiling is closed-weights, so the open-weights niche survives the frontier change intact.
+- **gemini-3.8-flash [high]** holds the frontier ceiling but is Google-family and step-heavy at 166 average steps; pair it with a model from another family for fallback diversity rather than routing every stage through one provider.
 - **claude-fable-5** remains useful where Anthropic-family behavior is specifically wanted, such as the quality-first, unbenchmarked design chain.
+- **claude-fable-5-1** is available in Atomic's catalog but is absent from the September 3, 2026 Datacurve snapshot, so it has no position on this frontier. It is measured by AA Intelligence Index and by AA with Claude Code, as detailed in the [September 5 AA cross-check](/models/model-selection#aa-cross-check-for-current-candidates). Those results justify evaluation for quality-first work, not importing an AA score or cost into this DeepSWE chart. Its cache pricing may matter for long sessions, but a token-price discount is not a measured cost-per-task saving or accuracy result.
 - **Unmeasured models** may remain operational defaults when a family lacks current DeepSWE or Artificial Analysis coverage, but they should not inherit a predecessor's score.
 
 ## How to use this
@@ -69,4 +87,4 @@ Efficiency is not the only axis. A dominated model can still earn a slot when it
 ## Related
 
 - [Model Selection](/models/model-selection)
-- [Benchmark sources & when to reference each](/models/artificial-analysis-index)
+- [Evals](/models/evals)

package/docs/models.md

@@ -14,9 +14,11 @@ A complete `defaultProvider`/`defaultModel` pair in `settings.json` is resolved
 - [Supported APIs](#supported-apis)
 - [Provider Configuration](#provider-configuration)
 - [Model Configuration](#model-configuration)
+- [GPT-6-Astra Built-in Models](#gpt-6-astra-built-in-models)
 - [Request-wide Cost Tiers](#request-wide-cost-tiers)
 - [Overriding Built-in Providers](#overriding-built-in-providers)
 - [Per-model Overrides](#per-model-overrides)
+- [Derived Fast Model Variants](#derived-fast-model-variants)
 - [Anthropic Messages Compatibility](#anthropic-messages-compatibility)
 - [OpenAI Compatibility](#openai-compatibility)
 
@@ -218,8 +220,28 @@ In `models.json`, `headers` values must be strings. A `null` suppression marker
 Current behavior:
 - `/model`, `--list-models`, and the interactive footer display entries by model `id`.
 - The configured `name` is used for model matching and secondary model detail text. It does not replace the footer/status-bar model id.
+- `input` lists the modalities **Atomic can send**. `["text"]`, `["text", "image"]`, and `["text", "image", "pdf"]` are the possible values. PDF is a platform capability rather than a per-model one — Anthropic documents that ["All active models support PDF processing"](https://platform.claude.com/docs/en/build-with-claude/pdf-support), routed through the same vision path as images — so upstream metadata carries it on every Claude entry. Atomic advertises it only where a runtime can serialize a document block: the Anthropic Messages and Amazon Bedrock Converse paths. A Claude mirror on any other provider stays at `["text", "image"]`, and a document sent to such a model is replaced by a visible placeholder rather than dropped silently. Note that Bedrock's Converse API needs citations enabled for full visual PDF understanding; without them it falls back to text extraction. `"pdf"` means PDF specifically: a document block's media type must be `application/pdf`, and any other value is rejected by name rather than sent mislabelled, because both request builders hardcode PDF rather than reading the field.
 
 
+### GPT-6-Astra Built-in Models
+
+Atomic ships `openai/gpt-6-astra` and `openai-codex/gpt-6-astra`. Both accept text and image input, expose tool search and additional tools, and offer exactly `low`, `medium`, `high`, `xhigh`, and `max` reasoning. `off`, `minimal`, and Codex's client-side `ultra` orchestration preset are not API reasoning levels and do not appear in Atomic's selector.
+
+The built-in OpenAI and Codex entries use a 272,000-token default input/context limit and a 128,000-token maximum output. OpenAI documents a 1,050,000-token API maximum, but requests above 272,000 aggregate input tokens enter the long-context price tier for the whole request. Override `contextWindow` only when the larger window and its price are intentional.
+
+| Aggregate input | Input | Cached input | Cache write | Output |
+| --- | ---: | ---: | ---: | ---: |
+| Up to 272,000 | $10 | $1 | $12.50 | $50 |
+| Above 272,000 | $20 | $2 | $25 | $75 |
+
+Rates are per million tokens. `openai/gpt-6-astra-fast` and `openai-codex/gpt-6-astra-fast` are derived canonical choices that keep these base catalog rates; the OpenAI adapters apply Fast's 2x multiplier at request time. The Codex fast choice sends upstream ID `gpt-6-astra` with `service_tier: priority` while Atomic records `gpt-6-astra-fast`.
+
+Amazon Bedrock exposes `openai.gpt-6-astra`, `global.openai.gpt-6-astra`, and `us.openai.gpt-6-astra` through the `amazon-bedrock` provider. These entries keep the same 272,000 input and 128,000 output limits, text and image input, and five reasoning levels; Atomic sends the selected effort as Bedrock's OpenAI `reasoning_effort` field. They do not get Fast or OpenAI tool-search metadata. Atomic sends each Bedrock ID unchanged and records all four price fields as zero because AWS had not published Astra pricing. Zero means unknown here, not free.
+
+Atomic does not synthesize Azure OpenAI Astra entries. Live-provider catalogs remain authoritative: the current OpenRouter catalog publishes `openai/gpt-6-astra` and `openai/gpt-6-astra-pro`, while the Vercel AI Gateway publishes `openai/gpt-6-astra` and `openai/gpt-6-astra-fast`. Atomic imports those exact IDs and their request-wide long-context prices. Vercel owns its suffixed ID, so it remains route-less and does not gain Atomic's first-party fast-route behavior.
+
+On OpenAI Responses, Astra uses the newer prompt-cache payload. `cacheRetention: "long"` sends `prompt_cache_options.ttl: "30m"` instead of the legacy `prompt_cache_retention: "24h"`; `none` sends explicit mode without a cache key, and `short` sends neither cache option. Earlier Responses models keep the 24-hour field for long retention.
+
 ### Sampling Parameters
 
 `samplingParams` is a free-form object merged into every request body for an OpenAI-compatible model after the fields Atomic sets, so its keys win. Use it to send parameters that Atomic does not model, including server-specific values such as llama.cpp's `min_p` or vLLM's `top_k`:
@@ -458,6 +480,17 @@ Behavior notes:
 - Unknown model IDs are ignored unless a matching model is subsequently registered by an extension.
 - If `models` is also defined for a provider in `models.json`, those custom models are merged after built-in overrides. A custom model with the same `id` replaces the overridden built-in model entry.
 
+## Derived Fast Model Variants
+
+For providers that support fast inference, Atomic adds a second selectable model whose ID is the base model ID plus `-fast` (for example `openai-codex/gpt-5.6-sol-fast`). Derivation runs **after** built-in composition, `models.json` custom models, extension model lists, and `modelOverrides` on those models, so it sees the final catalog. A `modelOverrides` entry keyed on a derived `-fast` ID is then applied to the derived entry itself. See [Providers](/providers#fast-models) for eligibility and what each provider sends upstream.
+
+Two rules matter when you write `models.json`:
+
+- **Your exact ID wins.** If a provider, a custom model in `models`, or an extension already defines that exact `<base>-fast` ID, Atomic keeps yours untouched, does not derive a duplicate, and prints a warning naming the model to rename or remove if you wanted the derived variant instead. A model you define is an ordinary model: the `-fast` suffix alone never gives it fast routing behavior.
+- **`modelOverrides` applies to derived variants.** A derived entry is a real catalog model, so `modelOverrides["gpt-5.6-sol-fast"]` customizes it exactly like any other model, and its routing metadata survives the override. Overriding the *base* model still flows through to the derived entry by inheritance; a fast-specific override wins over that inherited value.
+
+A derived variant inherits the base model's `cost`. The provider adapter applies the fast-tier multiplier at request time, so do not pre-multiply cost in an override.
+
 ## Anthropic Messages Compatibility
 
 For providers or proxies using `api: "anthropic-messages"`, use `compat.supportsEagerToolInputStreaming` to control Anthropic fine-grained tool streaming compatibility.
@@ -491,6 +524,51 @@ By default, Atomic sends per-tool `eager_input_streaming: true`. If a proxy or A
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `supportsEagerToolInputStreaming` | Whether the provider accepts per-tool `eager_input_streaming`. Default: `true`. Set to `false` to omit that field and use the legacy fine-grained tool streaming beta header on tool-enabled requests. |
 | `supportsLongCacheRetention`      | Whether the provider accepts Anthropic long cache retention (`cache_control.ttl: "1h"`) when cache retention is `long`. Default: `true`.                                                               |
+| `delegatesThinkingModelBinding`   | Whether the API decides for itself which thinking blocks the target model may read, dropping the rest. Default: `false`. See [Preserved thinking and model switches](#preserved-thinking-and-model-switches).                                    |
+| `enforcesPreservedThinkingBinding` | Whether the model rejects a thinking block replayed behind a changed conversation prefix. Default: `false`. When `true`, Atomic sends the `thinking-binding-controls-2026-08-01` beta header and `prefix_mismatch_behavior: "drop_block"`.  |
+| `supportsMidConvoEffort` | Whether the exact Claude model transport supports per-turn effort system messages. Atomic persists native effort levels and sends `drop_block` when enabled. Default: `false`. |
+| `supportsForcedToolChoice`        | Whether the model accepts forced tool use (`tool_choice` `any` or a named tool). Default: `true`. When `false`, Atomic rejects a forced choice with an error rather than sending a request the model refuses. `auto` and `none` are never altered.  |
+
+`supportsMidConvoEffort` and `enforcesPreservedThinkingBinding` compose rather than replace one another. The former is restricted to exact provider/model transports that accept effort-only system messages and adds the two per-turn-effort betas. It also enables `drop_block`, because historical effort changes can invalidate a signed prefix. The latter remains a separate Atomic compatibility flag for transports that enforce preserved-thinking prefixes but do not accept effort-only messages. Do not enable `supportsMidConvoEffort` for an API that merely imitates the Messages shape.
+
+`supportsForcedToolChoice` and `supportsTemperature` also exist on the Amazon Bedrock and OpenAI-compatible completions `compat` objects, with the same meanings and the same `true` defaults. Unlike the two preserved-thinking flags, which describe Anthropic's first-party endpoint, these describe the **model**, so Atomic applies them to every mirror that reaches it rather than only to `provider: "anthropic"`.
+
+On the completions adapter, `supportsTemperature: false` also strips `temperature`, `top_p`, and `top_k` out of `samplingParams`. That merge is documented as last-wins so its keys override the named request fields, which means it would otherwise reopen exactly the parameters the model rejects. The strip runs after the merge, so it also covers a model-level `samplingParams` default, and it removes only those three keys — every other custom key you pass still overrides as before.
+
+### Forced tool use on Claude Fable 5.1
+
+Claude Fable 5.1 rejects forced tool use — `tool_choice: {"type": "any"}` and `{"type": "tool", ...}` — on every request with a 400, whichever platform serves it. Anthropic's guidance is to use `tool_choice: {"type": "auto"}` with strict tool use or structured outputs instead.
+
+Atomic's own agent loop only ever asks for `auto` or `none`, so no interactive session can reach this. It is reachable through the `@bastani/pi-ai` library's Anthropic, Bedrock, and OpenAI-completions entry points, which accept the wider tool-choice shape. For a model marked `supportsForcedToolChoice: false`, all three **fail the request with an error naming the model and the remedy**, before the round trip. That matters most on a gateway: OpenRouter drops parameters a model does not support, so an unguarded forced choice would vanish silently and return a plausible answer that ignored the instruction.
+
+Atomic deliberately does not substitute `auto` on your behalf. Asking the model to call a specific tool and asking it to decide for itself are different requests, and silently swapping one for the other would discard an instruction you gave explicitly. If the substitution is what you want, make it yourself — branch on `compat.supportsForcedToolChoice` to decide. Every other model passes forced choices through unchanged, and `auto` and `none` are never altered on any model.
+
+On the OpenAI-completions path the tool-choice union is wider than Anthropic's, and four of its members force a call: `"required"`, `{"type": "function", ...}`, `{"type": "custom", ...}`, and `{"type": "allowed_tools", "allowed_tools": {"mode": "required", ...}}`. All four are rejected. `allowed_tools` with `"mode": "auto"` is **not** rejected: OpenAI documents that mode as letting the model pick from the allowed tools *and generate a message*, so it narrows the candidate set rather than forcing a call, and it reaches the provider unchanged.
+
+Two scoping details are worth knowing. **Claude Fable 5 is not restricted** — Anthropic names Fable 5.1 and Mythos 5.1 as the exceptions to forced tool use working, and OpenRouter's own metadata agrees, so the guard is version-scoped rather than family-scoped. That is the opposite of `supportsTemperature`, which Anthropic's sampling-parameter sentence applies to both Fable generations. And a provider "latest" alias such as OpenRouter's `~anthropic/claude-fable-latest` is **not** covered: its id names no version, so no rule keyed on the id can stay true if the alias re-points at a model that accepts forced tool use. If you use such an alias and need a forced choice guarded, pin the versioned id instead.
+
+### Preserved thinking and model switches
+
+Anthropic binds every `thinking` and `redacted_thinking` block to the model that produced it, and on Claude Fable 5.1 also to the conversation prefix — the `system` prompt, the `tools` array, and every earlier message — that it was produced from. See [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking).
+
+Two separate checks follow from that, and Atomic handles them differently.
+
+**The model check is the API's job.** A block is readable by the model that produced it or a newer one. Claude Fable 5.1 reads every earlier Claude model's blocks; no earlier model reads Fable 5.1's. A block the target model cannot read is always dropped by the API before the prompt reaches the model, unbilled, and the request succeeds. For first-party Anthropic models, Atomic therefore replays signed thinking blocks unchanged when you switch models mid-conversation and lets the API adjudicate:
+
+- **Switching up** to Claude Fable 5.1 from another Claude model keeps the conversation's reasoning, because Fable 5.1 is allowed to read it.
+- **Switching down** from Claude Fable 5.1 to an earlier Claude model drops that reasoning server-side, and the earlier model reasons again from the visible messages.
+
+In both directions the visible assistant text, tool calls, and tool results are preserved exactly, so the conversation stays coherent. Atomic no longer rewrites another Claude model's reasoning into visible assistant text on a switch: that both discarded reasoning the newer model was entitled to read and destabilized the prefix later blocks are bound to.
+
+**The conversation check can fail the request, so Atomic opts out of failing.** On Claude Fable 5.1, replaying a thinking block behind a changed prefix returns a 400. Anthropic enforces this by default for organizations created on or after August 31, 2026, which is why a session could fail on a new account but not an older one. Atomic sends the `thinking-binding-controls-2026-08-01` beta header with `thinking.block_binding.prefix_mismatch_behavior: "drop_block"` for that model, so a changed system prompt, a tool that appeared or disappeared, or a model switch drops the affected thinking blocks and the turn still answers. The field is sent on every request for that model, including turns with no reasoning level: the header alone would leave `prefix_mismatch_behavior` at its `"error"` default, which is the failure being avoided. When the API reports drops, Atomic records them on the assistant message's `diagnostics` array as an `anthropic_input_transformations` entry with the count, reasons, and block paths.
+
+**Compaction is handled structurally, not by `drop_block`.** Atomic's client-side `preserve_recent` compaction serializes the protected tail into a single boundary message rather than replaying it as structured assistant and tool-result messages, so no signed thinking block survives a boundary to be replayed behind it. Compaction therefore **intentionally resets the signed reasoning chain**: reasoning produced before a boundary is not carried across it, while the tail's text, tool calls, and tool results are preserved losslessly. This is exactly the first remedy Anthropic documents for keep-tail compaction — strip `thinking` and `redacted_thinking` from turns you carry across and keep `text` and `tool_use` — reached by Atomic's transcript design rather than by a stripping pass. `drop_block` covers live prefix mismatches *between* boundaries; it is not what makes compaction safe. See [Compaction](/compaction).
+
+**Server-side fallback leaves a boundary marker in the turn.** Claude Fable 5.1 is generated with the fallback targets Anthropic publishes for it — Claude Opus 4.8 and Claude Opus 5 — so a classifier refusal can be retried server-side on the same stream. When the decline happens partway through a response, the API emits a `fallback` content block marking where one model's output gives way to the next, then the fallback model continues. Atomic keeps that marker in the assistant turn as a `fallback` content block, and re-attributes the message to the serving model so usage is costed at that model's rates rather than the requested model's.
+
+On the next turn the marker's **position** is load-bearing: Anthropic validates the surrounding thinking blocks against it, and a request that echoes thinking from both sides of the boundary is rejected if the marker is missing or moved. Atomic therefore replays the marker exactly where it appeared, drops the declining model's `thinking`, `redacted_thinking`, and unexecuted client-side tool calls that precede it, and keeps all visible text plus everything after it. A turn with no fallback boundary is unaffected.
+
+**Provider restriction.** Both behaviors are scoped to first-party Anthropic models on the `anthropic-messages` API, which is where Anthropic documents the signature adjudication. Claude on Amazon Bedrock, Google Vertex, and Anthropic-compatible proxies keep the previous behavior: their thinking blocks are not replayed across a model switch, and Atomic does not send the block-binding beta on those paths. This includes two mirrors that could look eligible — opencode zen and the Vercel AI Gateway both ride `anthropic-messages`, and neither receives either capability. If you run Claude Fable 5.1 through one of those providers on a new Anthropic-backed account, a prefix change can still surface as a provider error. Custom providers known to adjudicate signatures the same way can opt in with the two `compat` fields above.
 
 ## OpenAI Compatibility
 
@@ -537,7 +615,8 @@ For providers with partial OpenAI compatibility, use the `compat` field.
 | `supportsStrictTools`                         | Anthropic/Bedrock strict-tool capability, normally generated from verified model metadata. |
 | `supportsOpenAIGrammarTools`                  | Canonical Pi capability for OpenAI Lark/regex custom tools. Keep false unless the endpoint passes custom tools through unchanged. |
 | `supportsGrammarTools`                        | Atomic compatibility alias for `supportsOpenAIGrammarTools`; the canonical field wins if both disagree. |
-| `supportsLongCacheRetention`                  | Whether the provider accepts long cache retention when cache retention is `long`: `prompt_cache_retention: "24h"` for OpenAI prompt caching, or `cache_control.ttl: "1h"` when `cacheControlFormat` is `anthropic`. Default: `true`. |
+| `supportsLongCacheRetention`                  | Whether the provider accepts long cache retention when cache retention is `long`: `prompt_cache_options.ttl: "30m"` for GPT-5.6+ Responses models, `prompt_cache_retention: "24h"` for earlier OpenAI models, or `cache_control.ttl: "1h"` when `cacheControlFormat` is `anthropic`. Default: `true`. |
+| `vllmPriority`                                | vLLM scheduler priority sent as the top-level `priority` request field. Lower values are handled earlier and the server default is `0`, so it only takes effect when vLLM runs with `--scheduling-policy priority`. Off by default; not set on the generated catalog. |
 | `openRouterRouting`                           | OpenRouter provider routing preferences. This object is sent as-is in the `provider` field of the [OpenRouter API request](https://openrouter.ai/docs/guides/routing/provider-selection).                                            |
 | `vercelGatewayRouting`                        | Vercel AI Gateway routing config for provider selection (`only`, `order`)                                                                                                                                                            |
 

package/docs/packages.md

@@ -177,7 +177,7 @@ If no app manifest (`atomic`, or legacy `pi`) is present, Atomic auto-discovers
 - `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
 - `prompts/` loads `.md` files
 - `themes/` loads `.json` files
-- `workflows/` loads workflow SDK files (`.ts`, `.js`, `.mjs`, `.cjs`); `workflow/` is also accepted as a singular alias. Workflow files import `workflow` from `@bastani/atomic/workflows`, import `Type` from `typebox`, and export the definition returned by `workflow({ ... })`. TypeScript resolves the published `@bastani/atomic/workflows` specifier through the `@bastani/atomic` package. Atomic resolves that workflow specifier and the supported TypeBox root, `typebox/compile`, `typebox/value`, and legacy `@sinclair/typebox` aliases to in-memory host modules when it loads the workflow at runtime. See Programmatic Usage in the workflows guide.
+- `workflows/` loads workflow SDK files (`.ts`, `.js`, `.mjs`, `.cjs`); `workflow/` is also accepted as a singular alias. Workflow files import `workflow` from `@bastani/atomic/workflows`, import `Type` from `typebox`, and export the definition returned by `workflow({ ... })`. TypeScript resolves the published `@bastani/atomic/workflows` specifier through the `@bastani/atomic` package. Atomic resolves that workflow specifier and the supported TypeBox root, `typebox/compile`, `typebox/value`, and legacy `@sinclair/typebox` aliases to in-memory host modules when it loads the workflow at runtime. See [Programmatic usage](/workflows/api-reference#programmatic-usage).
 
 When a package manifest exists, declared resource arrays normally define what loads. Workflows are the exception: if `atomic.workflows` / legacy `pi.workflows` is omitted, Atomic still checks conventional `workflows/` and `workflow/` directories.
 
@@ -189,7 +189,7 @@ Atomic bundles core packages for extensions and skills. If you import any of the
 
 Workflow packages import `workflow` from `@bastani/atomic/workflows`, import `Type` from `typebox`, and export definitions returned by `workflow({ ... })`. List `@bastani/atomic` and `typebox` in `peerDependencies` so package consumers receive the workflow SDK and schema library.
 
-Package-authored workflows should follow the same guiding principles as project workflows mentioned in docs/workflows.md.
+Package-authored workflows should follow the same [guiding principles](/workflows/authoring#guiding-principles) as project workflows.
 
 Other Atomic packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Atomic loads packages with separate module roots, so separate installs do not collide or share modules.