@bastani/atomic 0.9.10 → 0.9.11-alpha.10

package/docs/models/model-selection.md

@@ -0,0 +1,63 @@
+---
+title: "Model Selection"
+description: "Practical guidance for choosing models by workflow role, grounded in live coding-agent benchmarks (DeepSWE) and intelligence benchmarks (Artificial Analysis)."
+---
+
+# Model Selection
+
+This page gives workflow authors and runtime policy code a practical way to answer:
+
+- Which model should a workflow use by default?
+- Which model should it use for judgment gates, debugging, planning, research, cheap worker loops, and fallback diversity?
+- Which models are dominated on cost/accuracy and should be avoided unless they have a specific role fit?
+
+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, best effort per model), a long-horizon coding-agent benchmark reporting `pass@1` and average dollars per task. 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-07-17.**
+</Note>
+
+## Recommendation chart
+
+The Pareto frontier — models where nothing else is both cheaper and more accurate — is currently **gpt-5.6-sol** (accuracy ceiling), **gpt-5.6-terra**, **kimi-k3**, **gpt-5.6-luna**, **grok-4.5**, and **muse-spark-1.1**. Everything else is dominated and earns a place only through role fit or provider diversity. For the frontier reasoning, see [Pareto Efficiency](/models/pareto-efficiency).
+
+| Model [level] | pass@1 | $/task | Verdict | Use it for |
+| --- | --- | --- | --- | --- |
+| gpt-5.6-sol [max] | 73% | $8.39 | Accuracy ceiling / frontier | Judgment gates where a wrong verdict wastes a whole loop, and the hardest debugging; current top scorer |
+| gpt-5.6-terra [max] | 70% | $4.95 | Frontier — best top-tier value | High-accuracy default for reviewers and planners; matches fable-5's accuracy at ~4× lower cost |
+| kimi-k3 [max] | 69% | $4.65 | Frontier | Near-top accuracy at the lowest top-tier cost; open weights, so also a provider-diversity pick |
+| gpt-5.6-luna [max] | 67% | $3.03 | Frontier — best value on the board | The workhorse: research, orchestrator, worker + code-simplifier subagents |
+| gpt-5.5 [xhigh] | 67% | $7.23 | Superseded | luna matches 67% for $3.03 — less than half the cost |
+| claude-fable-5 [max] | 70% | $21.63 | Drop | terra matches 70% for $4.95; kept only where Anthropic-family behavior is specifically wanted |
+| claude-opus-4.8 [max] | 59% | $13.22 | Fallback only | Dominated on cost/accuracy, but retained for Anthropic provider diversity and its long-context niche |
+| grok-4.5 [high] | 54% | $2.42 | Frontier (budget) | Cheap, capable worker; adds xAI provider diversity |
+| claude-sonnet-5 [max] | 54% | $26.40 | Drop everywhere | Worst value on the chart; 268 steps of meandering |
+| muse-spark-1.1 [xhigh] | 53% | $2.36 | Frontier (cheapest defensible) | Cheapest model still on the frontier; open weights diversity |
+| gpt-5.4 [xhigh] | 52% | $5.65 | Superseded | grok-4.5 and luna dominate it on cost and accuracy |
+| glm-5.2 [max] | 44% | $3.92 | Diversity only | Reviewer-C primary (a third model family decorrelates review errors); budget fallback elsewhere |
+| gemini-3.5-flash [medium] | 37% | $7.34 | Drop from reasoning | Token hose (276k output tokens); kept only at :low in retrieval chains where token price rules |
+| kimi-k2.7-code | 31% | $2.82 | Drop | Dominated by muse-spark-1.1 (both cheaper reach); superseded by kimi-k3 |
+| claude-sonnet-4.6 [high] | 30% | $5.52 | Drop everywhere | Removed from all chains |
+| gemini-3.1-pro [high] | 12% | $9.48 | Drop everywhere | Value destruction; removed from all chains |
+
+<Note>
+Scores above are DeepSWE `pass@1` with ±CI omitted for readability; see the [live leaderboard](https://deepswe.datacurve.ai/) for confidence intervals, output-token, and step counts. A model absent from both DeepSWE and Artificial Analysis should be marked **unmeasured** rather than assigned a guessed score — unmeasured models may still remain operational defaults.
+</Note>
+
+## 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)).
+
+- **Reviewer / judgment gates** — a wrong verdict discards an entire loop, so pay for accuracy: `gpt-5.6-sol [max]` primary, `gpt-5.6-terra` as reviewer-B, and a different family (`kimi-k3` or `glm-5.2`) as reviewer-C for decorrelated errors. Benchmark to weight: DeepSWE pass@1 and the AA Agentic Index.
+- **Planner** — `gpt-5.6-terra [max]` for high-accuracy planning at reasonable cost; `gpt-5.6-sol` when the plan gates an expensive loop.
+- **Debugger** — `gpt-5.6-sol [max]` primary; deep reasoning pays off where root-causing is expensive. Benchmark to weight: DeepSWE pass@1, Terminal-Bench.
+- **Research** — `gpt-5.6-luna [max]` as the workhorse, with `kimi-k3` in the fallback chain for provider diversity. Benchmark to weight: AA-LCR (long context), AA-Omniscience (factual reliability).
+- **Orchestrator / worker / cheap loops** — `gpt-5.6-luna [max]` for the main worker and code-simplifier subagents; `grok-4.5 [high]` or `muse-spark-1.1 [xhigh]` for trivial mechanical one-shots.
+- **Design** — a quality-first, unbenchmarked domain; keep a top-tier model (`gpt-5.6-sol` or `claude-fable-5`) here and rely on human judgment rather than a score.
+- **Interactive coding sessions** — `gpt-5.6-terra [max]` as a balanced default.
+
+## 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.
+- [Custom models](/models) — how to add model entries for supported provider APIs.

package/docs/models/pareto-efficiency.md

@@ -0,0 +1,64 @@
+---
+title: "Pareto Efficiency"
+description: "Cost-vs-accuracy frontier for model selection: which models dominate, which are dominated, and when diversity overrides efficiency."
+---
+
+# Pareto Efficiency
+
+A model is **Pareto-efficient** (on the frontier) if no other model is both cheaper and more accurate. Everything not on the frontier is **dominated** — some other option matches or beats it on accuracy for less money — and should be avoided unless it earns a slot through a specific role fit or provider diversity.
+
+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 (best effort per model). The frontier moves whenever a new model ships or prices change — 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-07-17.**
+</Note>
+
+## The frontier
+
+Six models currently sit on the frontier, spanning "cheapest defensible worker" to "accuracy ceiling":
+
+- **gpt-5.6-sol [max]** — the accuracy axis (73% pass@1, $8.39). Nothing scores higher.
+- **gpt-5.6-terra [max]** — 70% for $4.95. Matches claude-fable-5's accuracy at roughly a quarter of the cost.
+- **kimi-k3 [max]** — 69% for $4.65. Near-top accuracy at the lowest top-tier price; open weights.
+- **gpt-5.6-luna [max]** — 67% for $3.03. The best value on the board for high-accuracy work.
+- **grok-4.5 [high]** — 54% for $2.42. A cheap, capable mid-tier worker.
+- **muse-spark-1.1 [xhigh]** — 53% for $2.36. The cheapest model still on the frontier.
+
+## What changed — the frontier moved
+
+The previous generation's frontier (gpt-5.5 and claude-fable-5) is now **dominated** by the gpt-5.6 family:
+
+- **claude-fable-5 [max]** (70%, $21.63) — matched on accuracy by **gpt-5.6-terra** (70%, $4.95) at ~4× lower cost.
+- **gpt-5.5 [xhigh]** (67%, $7.23) — matched on accuracy by **gpt-5.6-luna** (67%, $3.03) at less than half the cost.
+
+This is the reason to key these docs to the live benchmarks: a single release cycle reshaped the entire recommendation.
+
+## Dominated models — and why
+
+- **claude-fable-5 [max]** — superseded by gpt-5.6-terra on cost for equal accuracy.
+- **gpt-5.5 [xhigh]** and **gpt-5.4 [xhigh]** — superseded by gpt-5.6-luna / grok-4.5.
+- **claude-opus-4.8 [max]**, **claude-sonnet-5 [max]** — dominated on cost/accuracy; sonnet-5 is the worst value on the chart.
+- **kimi-k2.7-code** — superseded by kimi-k3 and undercut by muse-spark-1.1.
+- **claude-sonnet-4.6 [high]**, **gemini-3.1-pro [high]** — dominated; not in any chain.
+- **gemini-3.5-flash [medium]** — dropped from reasoning roles (token hose at 276k output tokens); retained only at `[low]` in retrieval chains where token price dominates.
+
+## Diversity and role-fit exceptions
+
+Efficiency is not the only axis. A dominated model can still earn a slot when it decorrelates errors or fills a niche:
+
+- **glm-5.2** — kept as reviewer-C because a third model family decorrelates review errors, even though it is dominated on raw efficiency.
+- **kimi-k3** — frontier on efficiency *and* an open-weights provider-diversity option; a strong reviewer-C or fallback.
+- **claude-opus-4.8 [max]** — retained for Anthropic provider diversity and its long-context niche.
+- **claude-fable-5** — kept where Anthropic-family behavior is specifically wanted, e.g. the quality-first, unbenchmarked design chain.
+- **Unmeasured models** — any family in use on `main` without DeepSWE or Artificial Analysis coverage should be marked unmeasured. Being unmeasured is not the same as being dominated; such models may remain operational defaults until measured.
+
+## How to use this
+
+1. Default to a frontier model for the role's accuracy needs (see [Model Selection](/models/model-selection)).
+2. Only reach for a dominated model when you have an explicit reason — provider diversity, a long-context or token-price niche, or an unbenchmarked domain like design.
+3. Re-read the frontier off the [DeepSWE live chart](https://deepswe.datacurve.ai/) when prices or benchmarks change, and update the timestamp on these pages.
+
+## Related
+
+- [Model Selection](/models/model-selection)
+- [Benchmark sources & when to reference each](/models/artificial-analysis-index)

package/docs/models.md

@@ -1,12 +1,11 @@
 # Custom Models
 
-Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.atomic/agent/models.json` (legacy `~/.pi/agent/models.json` is also read).
+Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via the single `models.json` in the active Atomic agent directory, normally `~/.atomic/agent/models.json`, or the directory selected by `ATOMIC_CODING_AGENT_DIR`/`PI_CODING_AGENT_DIR`. Atomic reads only that file: it does not read project-scoped `.atomic/models.json`, fall back to `~/.pi/agent/models.json`, or merge `.pi` and `.atomic` model configuration files. The legacy `.pi` read fallback remains available for configuration surfaces that explicitly use layered config paths, such as `auth.json`; it does not apply to `models.json`.
 
-When both files exist, Atomic reads the legacy `.pi` file first and the primary `.atomic` file second. For `modelOverrides`, entries are layered by provider and model ID: disjoint legacy entries remain available, while an exact primary provider/model entry replaces the complete legacy override entry. Atomic does not field-merge one override entry across files; use `{}` in the primary file to restore the built-in model values for that exact entry.
+The interactive `/model` selector renders the current authenticated snapshot immediately and refreshes network-backed catalogs in the background for up to 15 seconds. The terminal owns that deadline: it stops waiting and replaces `Refreshing model catalogs…` with a cached-model timeout or error status even when lower-level work rejects or ignores cancellation. In isolated-engine sessions the same deadline covers both credential reload and catalog work inside the engine, and model selection does not queue behind the refresh. Login and logout publish credential changes independently of catalog refresh, and a refresh that started against an older credential generation is discarded instead of restoring stale provider availability. A slow catalog therefore falls back to cached models without requiring an `auth.json` or `~/.atomic` reset.
 
-Built-in subscription providers such as Cursor (experimental) are selected with the same `provider/model` syntax, for example `cursor/composer-2`. Cursor image input is scoped to known multimodal Cursor Claude, Composer, Gemini, GPT, and Kimi model families (`claude-`, `composer-`, `gemini-`, `gpt-`, `kimi-`), plus `grok-4.3`; text-only Cursor models still reject images. Cursor image payloads must be non-empty standard base64, with MIME-style line wrapping whitespace accepted and stripped before serialization. Live private-API model metadata may fall back to estimated labels. Because Cursor support targets undocumented private endpoints with Cursor CLI-compatible headers, maintainers and users should explicitly accept the risk that it may conflict with Cursor's terms, break without notice, or affect the Cursor account used to authenticate.
+A complete `defaultProvider`/`defaultModel` pair in `settings.json` is resolved after built-in, configured, and extension providers register. If the provider remains unsupported, interactive mode reports a generic saved-configuration warning and leaves model selection open instead of routing the session to a different provider. Print and JSON modes write that diagnostic to stderr and exit nonzero before prompting, keeping JSON stdout JSONL-clean. RPC rejects `prompt` with the same correlated diagnostic until an explicit successful `set_model` selects an available model or an explicit model cycle returns a different available model. A null or unchanged cycle result does not clear the condition. If the provider is supported but the model is unknown or lacks authentication, normal automatic selection of an available authenticated model continues. Valid custom- and extension-provider defaults resolve once their provider registration is available. See [Settings](/settings#model--thinking).
 
-When Cursor omits token limits, Atomic derives them from its bundled `@earendil-works/pi-ai` model catalog and treats explicit `1M` Cursor labels as a 1,000,000-token context floor; unmatched Cursor-only models keep conservative estimates instead of disappearing from `/model`.
 
 ## Table of Contents
 
@@ -96,7 +95,7 @@ Override defaults when you need specific values:
 }
 ```
 
-The file reloads each time you open `/model`. Edit during session; no restart needed.
+Atomic reloads the active agent directory's single `models.json` each time you open `/model`. Provider definitions, per-model overrides, dynamic catalogs, and isolated-engine model state are rebuilt from that fresh configuration, so edits take effect without restarting. Invalid edits report an error.
 
 ## Google AI Studio Example
 
@@ -136,18 +135,22 @@ The `baseUrl` is required when adding custom models to the `google-generative-ai
 
 Set `api` at provider level (default for all models) or model level (override per model).
 
+These four values are the generic custom-provider APIs supported by `models.json`. Atomic's installed native provider runtime also implements provider-owned APIs including `mistral-conversations`, `azure-openai-responses`, `openai-codex-responses`, `bedrock-converse-stream`, `google-vertex`, and `pi-messages`; those native APIs are not implied to be stable generic custom-provider contracts.
+
 ## Provider Configuration
 
 | Field            | Description                                                      |
 | ---------------- | ---------------------------------------------------------------- |
-| `baseUrl`        | API endpoint URL                                                 |
-| `api`            | API type (see above)                                             |
-| `apiKey`         | API key (see value resolution below)                             |
+| `baseUrl`        | API endpoint or gateway URL                                      |
+| `api`            | Generic custom-provider API type (see above)                     |
+| `apiKey`         | Optional API key (see value resolution below); omit when auth comes from `/login`, `auth.json`, or `--api-key` |
+| `oauth`          | Dynamic OAuth provider type. Currently `"radius"`; requires the gateway `baseUrl` |
 | `headers`        | Custom headers (see value resolution below)                      |
 | `authHeader`     | Set `true` to add `Authorization: Bearer <apiKey>` automatically |
 | `models`         | Array of model configurations                                    |
 | `modelOverrides` | Per-model overrides for matching built-in or extension-registered models on this provider |
 
+For a custom Radius gateway, set `"oauth": "radius"` and its `baseUrl`. Atomic uses Radius OAuth credentials and the gateway's dynamic `pi-messages` catalog.
 ### Value Resolution
 
 The `apiKey` and `headers` fields support three formats:
@@ -204,15 +207,17 @@ If your command is slow, expensive, rate-limited, or should keep using a previou
 | `thinkingLevelMap` | No       | omitted           | Maps Atomic thinking levels to provider values and marks unsupported levels (see below)                    |
 | `input`            | No       | `["text"]`        | Input types: `["text"]` or `["text", "image"]`                                                             |
 | `contextWindow`    | No       | `128000`          | Default/effective context window size in tokens                                                            |
-| `contextWindowOptions` | No   | omitted           | Additional/selectable context windows in tokens (see below)                                                |
 | `maxTokens`        | No       | `16384`           | Maximum output tokens                                                                                      |
 | `cost`             | No       | all zeros         | Complete base rates per million tokens plus optional request-wide `tiers` (see below)                    |
 | `compat`           | No       | provider `compat` | Provider compatibility overrides. Merged with provider-level `compat` when both are set.                   |
+| `deferredToolsMode` | No | omitted | Deferred tool-loading protocol; set to `"kimi"` for Kimi-compatible deferred tools |
 
 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.
 
+
+Model references resolve the complete, unmodified ID before Atomic interprets thinking suffixes or glob syntax. For example, if the catalog contains the literal ID `provider/literal[free]:high`, that complete model wins and `:high` remains part of its ID; it does not become a thinking-level suffix and `[free]` is not treated as a character class. Only when the complete ID is absent does Atomic parse a valid thinking suffix, try the stripped exact ID, then apply glob/fuzzy matching. This preserves literal provider IDs without changing ordinary `*`, `?`, bracket-glob, ambiguity, ordering, or deduplication behavior.
 ### Request-wide Cost Tiers
 
 Custom models can declare request-wide long-context pricing under `cost.tiers`. The base `cost` and every tier must provide all four rates: `input`, `output`, `cacheRead`, and `cacheWrite`, in cost per million tokens. Each tier also requires `inputTokensAbove`.
@@ -304,43 +309,21 @@ Example for a model where thinking cannot be disabled:
 
 Migration: older configs that used `compat.reasoningEffortMap` should move that mapping to model-level `thinkingLevelMap`. Use `null` for levels that should not appear in the UI.
 
-### Context Window Options
+### Context Window
 
-`contextWindow` remains the scalar default and is always valid. Models that support multiple context sizes can also declare `contextWindowOptions` as positive token counts. Atomic hides unsupported choices in the `/model` selection flow and rejects unsupported `--context-window` values for the selected model. The active selection changes Atomic's effective `model.contextWindow`, so local budgeting, compaction, footer/stats, session replay, RPC/SDK state, and extensions all use the selected token budget while the model's scalar default remains unchanged.
+`contextWindow` is the model's context size in tokens and drives local budgeting,
+compaction thresholds, footer/stats, session replay, and RPC/SDK state.
 
 ```json
 {
   "id": "long-context-model",
   "reasoning": true,
-  "contextWindow": 400000,
-  "contextWindowOptions": [400000, 1000000]
+  "contextWindow": 400000
 }
 ```
 
-Users can select a supported context window independently from thinking level:
-
-```bash
-atomic --model custom/long-context-model --thinking high --context-window 1m
-```
-
-In interactive mode, run `/model` and pick a model; when the chosen model exposes more than one window, Atomic immediately prompts for the context window as a follow-up step — a GitHub Copilot CLI-style picker that lists numbered `Default` and `Long context` tiers with their token counts (for example `272k tokens` / `922k tokens` for `github-copilot/gpt-5.5`, or `200k tokens` / `936k tokens` for Claude/Gemini long-context models such as `github-copilot/claude-sonnet-5`) — so you can choose one of the active model's supported budgets. Persisted interactive selections are stored per model under `defaultContextWindows["provider/modelId"]` (raw token counts and compact labels such as `400k` or `1m` are accepted), so a Copilot-specific prompt cap does not leak into Anthropic, Cursor, or other providers. GitHub Copilot long-context requests treat `1m` as a branded budget request and resolve it to the model's largest advertised long-context tier not exceeding the request (for example `936k` for Copilot Claude models), while other providers continue to require one of their own exact supported windows or use their natural scalar default. Successful explicit startup selections are recorded as `context_window_change` entries even when the chosen value equals the scalar default, preserving the user's explicit budget choice across future settings changes and resume.
-
-Use larger context windows deliberately. Some providers charge more for larger windows, and Atomic preserves each model's default unless the user explicitly opts in through `--context-window`, the `/model` selection flow, per-model `defaultContextWindows`, or the optional global `defaultContextWindow` fallback.
-
-#### GitHub Copilot context windows
-
-GitHub Copilot context windows are measured in **input (prompt) tokens**, exactly like every other provider's `contextWindow`, and are derived **dynamically from GitHub's live CAPI model catalog** (`GET {baseUrl}/models`) rather than a hardcoded model list — so plain Copilot model ids GitHub adds, removes, or retiers are reflected automatically. Atomic fetches the catalog only when you actually have the GitHub Copilot provider authenticated, caches it on disk for 30 minutes, and refreshes the active interactive session's model metadata as soon as that catalog is applied. Dynamic model creation is intentionally limited to picker-enabled, non-disabled `chat` entries with plain, non-namespaced ids; enterprise/org-deployed catalog ids containing `/` (for example `octodemo/Octodemo_Foundry/DeepSeek-V3.2`) are skipped instead of being exposed as `github-copilot/*` models. The same catalog also supplies Copilot output-token caps and selectable thinking levels: when CAPI advertises `capabilities.limits.max_output_tokens`, Atomic uses that live value as the model's `maxTokens` instead of the bundled fallback; when CAPI advertises `capabilities.supports.reasoning_effort` as an array, Atomic hides unsupported thinking levels for both dynamically synthesized Copilot models and bundled `pi-ai` Copilot models. Models that only advertise thinking budgets or a boolean reasoning-effort flag keep their existing thinking-level behavior.
-
-Each selectable Copilot window is a prompt/input budget. Atomic reads `capabilities.limits.max_prompt_tokens` for the full prompt cap, `capabilities.limits.max_output_tokens` for the maximum response/output cap, and treats `capabilities.limits.max_context_window_tokens` as the model's total context capacity (prompt plus output reserve) and a compatibility fallback only when the prompt cap is absent. Models with tiered pricing expose their per-tier prompt budgets through `billing.token_prices.<tier>.context_max`: the `default` tier becomes the base window and a larger `long_context` tier is offered as a selectable option. For example `github-copilot/gpt-5.5` resolves to a `272k` default / `922k` long prompt budget, `github-copilot/mai-code-1-flash-picker` advertises a `128k` prompt cap with a `256k` total context window, and `github-copilot/claude-sonnet-5` plus other Claude/Gemini long-context models resolve to `200k` default / `936k` long. When the request is a rounded budget such as `1m`, Atomic selects the largest advertised Copilot long-context prompt tier at or below that budget instead of falling back to the base `200k`/`272k` window. Offline, unauthenticated, or non-Copilot sessions leave the built-in scalar window and output-token cap untouched and show no picker.
-
-Selecting the long-context window does two client-side things:
-
-1. Raises Atomic's local token budget (e.g. `922_000` for `gpt-5.5`) for context collection, compaction thresholds, footer/stats, session replay, and SDK/RPC metadata.
-2. Sends `X-GitHub-Api-Version: 2026-06-01` on Copilot requests so GitHub returns/enforces the absolute long-context limits for eligible accounts.
-
-Atomic does **not** send a request body field, `contextTier`, or model-id variant for Copilot long context. GitHub chooses the larger `long_context` billing tier server-side automatically when the prompt token count exceeds the model's default budget. That tier consumes more Copilot AI credits and requires the account/actor to have Copilot long-context/usage-based billing entitlement enabled. If the account or selected model is still capped by GitHub's server-side limit, the request is rejected (for example, `prompt token count of N exceeds the limit of M`) and Atomic surfaces a friendly entitlement/cost/server-cap hint instead of silently truncating context.
-
-Custom `models.json` entries remain the escape hatch for providers, proxies, or Copilot accounts where the live catalog is unavailable. To adjust an existing built-in model, use `modelOverrides`:
+Built-in models take their `contextWindow` from the bundled `pi-ai` catalog. To
+change one, use `modelOverrides`:
 
 ```json
 {
@@ -348,10 +331,7 @@ Custom `models.json` entries remain the escape hatch for providers, proxies, or
     "github-copilot": {
       "modelOverrides": {
         "gpt-5.5": {
-          "contextWindowOptions": [272000, 922000]
-        },
-        "gemini-3.1-pro-preview": {
-          "contextWindowOptions": [200000, 936000]
+          "contextWindow": 272000
         }
       }
     }
@@ -359,7 +339,7 @@ Custom `models.json` entries remain the escape hatch for providers, proxies, or
 }
 ```
 
-To add a new Copilot model id under the built-in provider, define it in `models`:
+To add a new model id under a built-in provider, define it in `models`:
 
 ```json
 {
@@ -368,8 +348,7 @@ To add a new Copilot model id under the built-in provider, define it in `models`
       "models": [
         {
           "id": "my-copilot-model",
-          "contextWindow": 400000,
-          "contextWindowOptions": [1000000]
+          "contextWindow": 400000
         }
       ]
     }
@@ -377,8 +356,6 @@ To add a new Copilot model id under the built-in provider, define it in `models`
 }
 ```
 
-SDK and extension consumers can import the public helper API from the package root: `parseContextWindowValue()`, `formatContextWindow()`, `getSupportedContextWindows()`, `getModelDefaultContextWindow()`, `withContextWindowOptions()`, and `selectContextWindow()` are exported from `@bastani/atomic` alongside their TypeScript helper types. The root export also carries the `Model<Api>` augmentation for `contextWindowOptions` and `defaultContextWindow`.
-
 ## Overriding Built-in Providers
 
 Route a built-in provider through a proxy without redefining models:
@@ -439,15 +416,15 @@ Use `modelOverrides` to customize specific models without replacing the provider
 }
 ```
 
-`modelOverrides` supports these fields per model: `name`, `reasoning`, `thinkingLevelMap`, `input`, `cost` (partial scalar rates plus optional full tier-array replacement), `contextWindow`, `contextWindowOptions`, `maxTokens`, `headers`, `compat`.
+`modelOverrides` supports these fields per model: `name`, `reasoning`, `thinkingLevelMap`, `input`, `cost` (partial scalar rates plus optional full tier-array replacement), `contextWindow`, `maxTokens`, `headers`, `compat`.
 
-When both `~/.pi/agent/models.json` and `~/.atomic/agent/models.json` define `modelOverrides`, Atomic merges their nested provider/model maps in that order. Different model IDs survive from both files. For the same provider and model ID, the primary `.atomic` entry replaces the entire legacy `.pi` override entry rather than deep-merging individual fields. This complete-entry rule includes `headers`: a primary exact override without headers removes headers that came from the legacy override, but does not erase a surviving custom model definition's own headers. An empty primary override (`{}`) therefore restores the model's built-in values for that entry.
+Atomic reads one `models.json` from the active agent directory. It does not layer model overrides from `.pi` and `.atomic` files.
 
 Within a single file, custom model definitions replace matching built-in entries after built-in overrides are applied. `modelOverrides` composes only with built-in and extension-registered models; it does not modify a same-ID custom model definition.
 
 Behavior notes:
 - Atomic retains the parsed override map even when an extension registers the matching provider/model after `models.json` is loaded.
-- Layered primary/legacy compatibility merges override maps by provider and model ID; disjoint entries survive, while a primary exact entry replaces the complete legacy entry without cross-file field-level merging.
+- Model overrides come from the active agent directory's single `models.json`; no cross-file layering or merging is performed.
 - For matching built-in and extension-registered models, the model definition is the base and `modelOverrides` wins configured fields. Extension-registered model headers are shallow-merged with override headers, with override headers winning duplicate names. A same-ID custom model replaces the built-in override result, including its complete header record.
 - A scalar-only `cost` override preserves inherited tiers. Supplying `cost.tiers` replaces the complete tier array, including `[]` to clear it; omitted scalar cost fields remain inherited.
 - Provider-level request headers remain a separate provider layer and are combined at request time.
@@ -525,11 +502,25 @@ For providers with partial OpenAI compatibility, use the `compat` field.
 | `thinkingFormat`                              | Use `reasoning_effort`, `openrouter`, `deepseek`, `together`, `zai`, `qwen`, `chat-template`, or `qwen-chat-template` thinking parameters                                                                                            |
 | `chatTemplateKwargs`                          | `chat_template_kwargs` values for `thinkingFormat: "chat-template"`; use `{ "$var": "thinking.enabled" }` or `{ "$var": "thinking.effort" }` for Atomic-controlled thinking values                                          |
 | `cacheControlFormat`                          | Use Anthropic-style `cache_control` markers on the system prompt, last tool definition, and last user/assistant text content. Currently only `anthropic` is supported.                                                               |
-| `supportsStrictMode`                          | Include the `strict` field in tool definitions                                                                                                                                                                                       |
+| `supportsStrictMode`                          | OpenAI-compatible strict JSON-schema function tools. This is not a general guarantee for every API. |
+| `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`. |
 | `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`)                                                                                                                                                            |
 
+### Constrained tool sampling
+
+Tools may request `{ type: "json_schema", strict: "prefer" | "require" }` or `{ type: "grammar", variants: { openai_lark?: string, openai_regex?: string } }`. `prefer` may fall back to ordinary tool calling; `require` must fail if the active provider/model cannot enforce the schema. Grammar tools use OpenAI custom-tool syntax and fall back to normal function handling when grammar capability is absent. Do not infer support from a provider name: Atomic carries the model's explicit capability metadata through built-in catalogs, dynamic catalogs, overrides, SDK/RPC model objects, and isolated execution.
+
+Strict JSON-schema support currently includes OpenAI, Anthropic, capable Bedrock Converse models, Mistral, and Gemini 3 through Google/Vertex. Earlier Gemini models cannot enforce required parameters: `prefer` falls back and `require` fails. OpenAI grammar tools are limited to capable GPT-5+ models on endpoints known to preserve custom tools; gateways such as OpenRouter may normalize and break them.
+
+### Catalog freshness and precedence
+
+Authenticated remote catalogs are cached in `models-store.json`. Atomic revalidates pi.dev catalogs with the stored ETag through `If-None-Match`; an empty `304 Not Modified` is success and retains the cached body while updating its check time. A newer bundled catalog wins over an older persisted overlay even when package file mtimes are misleading. Final visibility is built-ins, persisted/remote data subject to freshness, configured `.pi` then `.atomic` layers, and live provider catalogs/overrides. Provider failures retain the last usable provider-specific snapshot.
+
+Claude Opus 5 is present in the generated Anthropic and Amazon Bedrock catalogs. Its metadata enables adaptive thinking, including `xhigh` where advertised. Bedrock uses its generated inference-profile ID, prompt-caching and strict-tool metadata, and preserves provider/AWS validation errors. Custom entries must reproduce those capabilities honestly rather than copying a display name alone.
 `openrouter` uses `reasoning: { effort }`. `together` uses `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` uses top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that require `chat_template_kwargs.enable_thinking` and `preserve_thinking`. Use `chat-template` for vLLM/Hugging Face chat templates that need configurable `chat_template_kwargs`, such as `chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }` for DeepSeek V3.x templates.
 
 `cacheControlFormat: "anthropic"` is for OpenAI-compatible providers that expose Anthropic-style prompt caching through `cache_control` markers on text content and tool definitions.

package/docs/packages.md

@@ -47,6 +47,8 @@ atomic update --extension npm:@foo/bar
 
 These commands manage Atomic packages and `atomic update` can update the Atomic CLI installation. To uninstall Atomic itself, see [Quickstart](/quickstart#uninstall).
 
+Self-update resolves an exact advertised package/version target and installs that pinned spec, so the update cannot drift to a newer registry release during installation. Any release note supplied by the update service is shown before installation. Atomic only updates installations it can verify are writable and managed by the detected global package manager; otherwise it prints a manual command. On Windows, loaded native dependencies are temporarily quarantined during replacement and stale quarantine directories are cleaned on later update attempts.
+
 By default, `install` and `remove` write to user settings (`~/.atomic/agent/settings.json`). Use `-l` to write to project settings (`.atomic/settings.json`; legacy `.pi/settings.json` is also read) instead. Project settings can be shared with your team, and Atomic installs any missing packages automatically on startup after the project is trusted.
 
 To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
@@ -237,11 +239,11 @@ Filter what a package loads using the object form in settings:
 
 ## Enable and Disable Resources
 
-Use `atomic config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.atomic/agent`) and project (`.atomic/`) scopes. Workflow package filters can be configured in settings with `workflows` patterns.
+Use `atomic config` to enable or disable extensions, skills, prompt templates, and themes. It starts in global settings (`~/.atomic/agent/settings.json`); press Tab to switch global/project scope. Use `atomic config -l` to start in project overrides (`.atomic/settings.json`) with inherited global resources dimmed. Workflow package filters can be configured with `workflows` patterns.
 
 ## Scope and Deduplication
 
-Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by:
+Packages can appear in both global and project settings. The project entry normally wins. A project entry with `autoload: false` instead acts as a delta over the global entry: it starts with no newly auto-discovered resources while explicit include/exclude patterns adjust the inherited package resources. Identity is determined by:
 
 - npm: package name
 - git: repository URL without ref

package/docs/prompt-templates.md

@@ -69,6 +69,7 @@ Templates support positional arguments, defaults, and simple slicing:
 - `$1`, `$2`, ... positional args
 - `$@` or `$ARGUMENTS` for all args joined
 - `${1:-default}` uses arg 1 when present/non-empty, otherwise `default`
+- `${@:-default}` or `${ARGUMENTS:-default}` uses all arguments when present/non-empty, otherwise `default`
 - `${@:N}` for args from the Nth position (1-indexed)
 - `${@:N:L}` for `L` args starting at N