@bastani/atomic 0.9.13 → 0.9.14-alpha.2

package/docs/models/model-selection.md

@@ -14,7 +14,7 @@ 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, 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.**
+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. 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-08-16.**
 </Note>
 
 ## Benchmark levels are measurement settings
@@ -30,29 +30,38 @@ reports the ambiguity. Use `--provider <provider> --model <id>` or `--model <pro
 
 ## 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).
+The current highest-effort-config Pareto frontier is **claude-opus-5** (accuracy ceiling), **gpt-5.6-sol**, **gpt-5.6-terra**, **gpt-5.6-luna**, **deepseek-v4-pro**, and **deepseek-v4-flash**. Everything else is dominated on DeepSWE 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 |
 | --- | --- | --- | --- | --- |
-| 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-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% | $8.39 | Frontier | High-cost judgment gates; nearly the top score at lower cost than Opus 5 |
+| gpt-5.6-terra [max] | 70% | $3.96 | Frontier — best top-tier value | High-accuracy reviewers and planners |
+| claude-fable-5 [max] | 70% | $21.63 | Drop | Sol and Terra match or beat its score for much less |
+| kimi-k3 [max] | 69% | $4.65 | Diversity fallback | Open-weights diversity, though Terra is cheaper and more accurate on DeepSWE |
+| gpt-5.6-luna [max] | 67% | $0.61 | Frontier — best general value | 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 |
+| deepseek-v4-pro [max] | 63% | $0.24 | Frontier (budget) | Low-cost work where its 155-step average remains acceptable |
+| 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; DeepSeek Pro and Luna dominate it |
+| muse-spark-1.2 [xhigh] | 55% | $3.70 | Drop | DeepSeek Pro 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 | Superseded | Grok 4.6 adds 13 points; cheaper frontier models still dominate both generations |
+| deepseek-v4-flash [max] | 53% | $0.10 | Frontier (cheapest) | Very cheap mechanical loops that can tolerate lower accuracy and 153 average steps |
+| muse-spark-1.1 [xhigh] | 53% | $2.36 | Superseded | Replaced by Muse Spark 1.2 and dominated by DeepSeek Pro |
+| gpt-5.4 [xhigh] | 52% | $5.65 | Superseded | 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 [low] | 31% | $2.19 | Superseded | Kimi K3 is the current family fallback |
 | 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 |
+| gemini-3.1-pro [high] | 12% | $2.14 | Drop everywhere | Removed from all chains |
+| glm-5.3 [high] | unmeasured | unmeasured | Diversity fallback | Current direct Z.AI fallback; GLM-5.2 measurements are not relabeled |
 
 <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.
+DeepSWE values above use the v1.1 results and reporting corrections published through August 14, 2026; `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. See the live page for intervals, output tokens, steps, lower-effort configurations, and later corrections.
 </Note>
 
 ## Role-based thinking effort
@@ -72,11 +81,11 @@ Reserve `max` for a high-cost-of-error role or an explicit user request. An expl
 
 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** — use `max` when the reviewer makes a security, identity, adversarial, or final-approval decision whose wrong verdict discards an entire loop. `gpt-5.6-sol` remains the accuracy-first model recommendation; use a different family for reviewer-B/C when decorrelated errors matter. Benchmark to weight: DeepSWE pass@1 and the AA Agentic Index.
-- **Codebase mapping / planner** — start at `high` for repository mapping, lifecycle analysis, compatibility, and plans. `gpt-5.6-terra` is a strong fit; raise to `max` only when the plan itself 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, but `max` is not the blanket debugger setting. Benchmark to weight: DeepSWE pass@1 and Terminal-Bench.
-- **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 workhorse model recommendation. Benchmark to weight: AA-LCR (long context) and AA-Omniscience (factual reliability).
-- **Orchestrator / worker / cheap loops** — use `high` for demanding workers and `medium` or lower for routine or mechanical loops when their evidence remains sufficient. `gpt-5.6-luna`, `grok-4.5`, and `muse-spark-1.1` are role-fit choices; their bracketed chart levels are measurements, not defaults.
+- **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-terra` is the strongest top-tier value at its measured `max` configuration; 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. DeepSeek V4 Pro and Flash occupy the budget frontier but take 155 and 153 steps on average; use them only when that longer path fits. Use another family when provider diversity matters.
 - **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.
 - **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.

package/docs/models/pareto-efficiency.md

@@ -10,47 +10,48 @@ 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 (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.**
+Figures are a snapshot of DeepSWE v1.1 using the highest published thinking level per model and reporting corrections through August 14, 2026. The frontier moves whenever a model, run, or price changes — 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-08-16.**
 </Note>
 
 ## The frontier
 
-Six models currently sit on the frontier, spanning "cheapest defensible worker" to "accuracy ceiling":
+Six highest-effort model configurations currently sit on the frontier, from the cheapest measured task cost to the 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.
+- **deepseek-v4-flash [max]** — 53% for $0.10. The cheapest point, with lower accuracy and 153 average steps.
+- **deepseek-v4-pro [max]** — 63% for $0.24. A large accuracy gain for another $0.14 per task, with 155 average steps.
+- **gpt-5.6-luna [max]** — 67% for $0.61. The best broad value on the board.
+- **gpt-5.6-terra [max]** — 70% for $3.96. The best top-tier value after the July price correction.
+- **gpt-5.6-sol [max]** — 73% for $8.39. The lower-cost near-peer to the accuracy leader.
+- **claude-opus-5 [max]** — 74% for $11.84. The current accuracy ceiling.
 
 ## 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:
+The August results and reporting fixes changed both ends of the frontier:
 
-- **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.
+- **Claude Opus 5 [max]** set a new 74% ceiling, one point above Sol, at $11.84 per task.
+- **DeepSeek V4 Flash and Pro [max]** added $0.10 and $0.24 budget-frontier points. Their 153–155 average steps remain a separate latency and loop-length cost.
+- **GPT-5.6 Luna and Terra [max]** now cost $0.61 and $3.96 per task after corrected pricing, strengthening both positions.
 
 ## 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.
+- **claude-fable-5 [max]** — Sol is more accurate and much cheaper; Terra matches its rounded score for less than one fifth of the task cost.
+- **kimi-k3 [max]** — Terra is one point more accurate and $0.69 cheaper; Kimi remains useful for open-weights 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 less than one third of its task cost.
+- **grok-4.5 [high]**, **muse-spark-1.1 [xhigh]**, **muse-spark-1.2 [xhigh]**, and **gpt-5.4 [xhigh]** — the new DeepSeek and GPT-5.6 points dominate these former budget choices.
+- **claude-opus-4.8 [max]** and **claude-sonnet-5 [max]** — dominated on both cost and accuracy.
+- **qwen3.8-max [xhigh]**, **gemini-3.6-flash [high]**, **gemini-3.5-flash [high]**, **glm-5.2 [max]**, **kimi-k2.7-code [low]**, **claude-sonnet-4.6 [high]**, and **gemini-3.1-pro [high]** — each has a cheaper, more accurate measured alternative.
 
 ## 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.
+- **grok-4.6** — retained as the operational xAI and OpenRouter provider-diversity fallback.
+- **glm-5.3 [high]** — unmeasured in the current DeepSWE snapshot; retained as a direct Z.AI provider-diversity fallback. GLM-5.2 results are not relabeled as GLM-5.3.
+- **kimi-k3** — retained as a strong open-weights provider-diversity option despite Terra's strict DeepSWE dominance.
+- **claude-opus-4.8 [max]** — retained where Anthropic diversity or its long-context behavior has separate value.
+- **claude-fable-5** — kept where Anthropic-family behavior is specifically wanted, such as the quality-first, unbenchmarked design chain.
+- **Unmeasured models** — a family without current DeepSWE or Artificial Analysis coverage may remain an operational default, but should not inherit a predecessor's score.
 
 ## How to use this
 

package/docs/providers.md

@@ -51,7 +51,9 @@ If the Codex backend reports that an OAuth/auth token was invalidated or revoked
 
 ### Codex Fast Mode
 
-Run `/fast` in interactive mode to enable OpenAI priority service tier separately for normal chat and workflow-stage sessions. The command is shown only when the current model scope includes a supported `openai/*` or `openai-codex/*` model. Workflow stages, nested `ctx.workflow(...)` stages, and subagents launched by those stages use the workflow setting, not the chat setting. Each fallback attempt is evaluated against its effective model, so an eligible fallback gets the tier and an ineligible provider does not. When enabled for the active supported model, the UI appends `fast` after the model name in the chat footer, workflow stage model labels, and stage-launched subagent results. Fast mode intentionally does not apply to `github-copilot/*`, Azure OpenAI, OpenRouter, or custom OpenAI-compatible providers. Use workflow fast mode deliberately because parallel workflow fan-out can multiply priority-tier usage.
+Run `/fast` in interactive mode to enable OpenAI priority service tier separately for normal chat and workflow-stage sessions. The command is shown when the current model scope includes a supported `openai/*` or `openai-codex/*` model. A resolved provider alias also qualifies when it uses the shared `openai-codex-responses` transport. Workflow stages, nested `ctx.workflow(...)` stages, and subagents launched by those stages use the workflow setting, not the chat setting. Each fallback, retry, compaction-planner, and branch-summary request is evaluated against its effective model, so an eligible fallback gets the tier and an ineligible provider does not. When enabled for the active supported model, the UI appends `fast` after the model name in the chat footer, workflow stage model labels, and stage-launched subagent results. Fast mode intentionally does not apply to `github-copilot/*`, Azure OpenAI, OpenRouter, or generic OpenAI-compatible providers. Use workflow fast mode deliberately because parallel workflow fan-out can multiply priority-tier usage.
+
+The shared ChatGPT Codex transport sends the fast routing contract only after the final request payload contains `service_tier: priority`: `originator: codex_cli_rs` plus `x-codex-routing-hint: model=<effective-model>;tier=priority` on both HTTP/SSE and WebSocket transports. The same rule covers the stock provider, renamed providers, credential-resolved endpoints, and monitoring proxies that retain `api: "openai-codex-responses"`. WebSocket fallback, reconnect, and HTTP retry attempts reuse that identity; a final model or tier change drops a cached socket before reuse. Requests to the standard OpenAI API send only the tier. When Fast Mode is off, or a request hook changes the final tier away from `priority`, Atomic keeps the normal `originator: pi` identity and sends no routing hint.
 
 ### Claude Pro/Max
 
@@ -87,6 +89,8 @@ Business and enterprise tokens sent to the individual host return `421 Misdirect
 
 Run `/login xai`, then select **Use a subscription**. `XAI_API_KEY` remains available through **Use an API key**.
 
+Atomic defaults xAI sessions to `grok-4.6`. Built-in workflow and subagent fallback chains use `xai/grok-4.6:high` and `openrouter/x-ai/grok-4.6`; GitHub Copilot also exposes Grok 4.6 when the account's model policy enables it. Network-backed catalogs refresh and cache these newer entries independently of the bundled catalog snapshot.
+
 ### Radius
 
 Radius is a dynamic `pi-messages` gateway. `/login radius` stores OAuth tokens in `auth.json`; its model catalog refreshes independently and is cached in `models-store.json`. API-key authentication is also available through `/login radius` or `RADIUS_API_KEY`. Custom Radius gateways can be declared in `models.json` with `"oauth": "radius"` and the gateway `baseUrl`.
@@ -151,7 +155,7 @@ Remote pi.dev catalogs persist their ETag and are revalidated with `If-None-Matc
 | Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` | `xiaomi-token-plan-ams` |
 | Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` | `xiaomi-token-plan-sgp` |
 
-Baseten's built-in default is `zai-org/GLM-5.2`; its catalog supplies the provider-specific thinking levels. Qwen Token Plan Individual defaults to `qwen3.8-max` and uses the international `QWEN_TOKEN_PLAN_API_KEY` shared with the existing Qwen Token Plan provider.
+Z.AI and Z.AI Coding Plan (China) default to `glm-5.3` (`zai/glm-5.3` and `zai-coding-cn/glm-5.3`); the generated catalogs expose reasoning without a thinking-level map, so built-in chains use the supported `:high` suffix rather than inventing distinct `:xhigh` or `:max` tiers. OpenRouter currently exposes `z-ai/glm-5.2` but not `z-ai/glm-5.3`, so Atomic does not ship an unavailable OpenRouter GLM-5.3 fallback. Baseten also has no GLM-5.3 catalog entry, so its documented default remains `zai-org/GLM-5.2` and its catalog supplies the provider-specific thinking levels. Qwen Token Plan Individual defaults to `qwen3.8-max` and uses the international `QWEN_TOKEN_PLAN_API_KEY` shared with the existing Qwen Token Plan provider.
 
 Reference for environment variables and `auth.json` keys: `findEnvKeys()` / `getEnvApiKey()` in the installed `@earendil-works/pi-ai` dependency (`node_modules/@earendil-works/pi-ai/dist/env-api-keys.d.ts`). The private provider map those functions use is in `node_modules/@earendil-works/pi-ai/dist/env-api-keys.js`; Atomic does not include a separate `packages/ai` source directory in this monorepo.
 
@@ -319,6 +323,95 @@ AI Gateway authentication uses `CLOUDFLARE_API_KEY` as `cf-aig-authorization`. U
 
 For normal Atomic usage, prefer unified billing or stored BYOK. Inline BYOK requires configuring an additional upstream `Authorization` header for the Cloudflare AI Gateway provider, for example via a `models.json` provider/model override.
 
+#### Workers AI binding (no API token)
+
+When Atomic's engine runs inside a Cloudflare Worker in the gateway's own account, requests can route through the [Workers AI binding](https://developers.cloudflare.com/ai-gateway/usage/workers-ai-binding/) (`env.AI`) instead of HTTPS. Binding calls are pre-authenticated in-account, so this path needs **no `CLOUDFLARE_API_KEY` at all**. Atomic re-exports the transport as `createGatewayBindingFetch` from `@bastani/atomic`.
+
+Declare the binding and the endpoint vars (the vars also satisfy the account/gateway resolution the gateway prefix needs):
+
+```toml
+# wrangler.toml
+[ai]
+binding = "AI"
+
+[vars]
+CLOUDFLARE_ACCOUNT_ID = "your-account-id"
+CLOUDFLARE_GATEWAY_ID = "your-gateway-slug"   # dash.cloudflare.com → AI → AI Gateway
+```
+
+Then register a provider override whose `streamSimple` swaps in the binding transport. The extension must be created where `env` is in scope — an inline extension factory passed to the resource loader does that:
+
+```typescript
+import {
+  CLOUDFLARE_GATEWAY_BINDING_AUTH_SENTINEL,
+  createAgentSession,
+  createGatewayBindingFetch,
+  DefaultResourceLoader,
+  type AiGatewayBinding,
+} from "@bastani/atomic";
+import { streamSimple as anthropicStreamSimple } from "@earendil-works/pi-ai/api/anthropic-messages";
+
+// `AI` is the Workers AI binding; `AiGatewayBinding` is the structural type for it,
+// so the snippet needs no `@cloudflare/workers-types` dependency.
+interface Env {
+  AI: AiGatewayBinding;
+  CLOUDFLARE_ACCOUNT_ID: string;
+  CLOUDFLARE_GATEWAY_ID: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const gatewayPrefix = `https://gateway.ai.cloudflare.com/v1/${env.CLOUDFLARE_ACCOUNT_ID}/${env.CLOUDFLARE_GATEWAY_ID}`;
+    const loader = new DefaultResourceLoader({
+      cwd: "/workspace",
+      agentDir: "/workspace/.atomic/agent",
+      extensionFactories: [
+        {
+          name: "cloudflare-gateway-binding",
+          factory: (pi) => {
+            pi.registerProvider("cloudflare-ai-gateway", {
+              // Placeholder credential: it marks the provider configured and becomes
+              // `cf-aig-authorization: Bearer cloudflare-gateway-binding`, which the
+              // transport strips before the binding call. Never sent to the gateway.
+              apiKey: CLOUDFLARE_GATEWAY_BINDING_AUTH_SENTINEL,
+              api: "anthropic-messages",
+              streamSimple: (model, context, options) =>
+                anthropicStreamSimple(
+                  {
+                    ...model,
+                    baseUrl: (model.baseUrl ?? gatewayPrefix)
+                      .replaceAll("{CLOUDFLARE_ACCOUNT_ID}", env.CLOUDFLARE_ACCOUNT_ID)
+                      .replaceAll("{CLOUDFLARE_GATEWAY_ID}", env.CLOUDFLARE_GATEWAY_ID)
+                  },
+                  context,
+                  {
+                    ...options,
+                    fetch: createGatewayBindingFetch({
+                      binding: env.AI,
+                      gateway: env.CLOUDFLARE_GATEWAY_ID,
+                      baseUrl: gatewayPrefix
+                    })
+                  }
+                )
+            });
+          }
+        }
+      ]
+    });
+    await loader.reload();
+
+    const { session } = await createAgentSession({
+      resourceLoader: loader
+      // Pass `model:` with a cloudflare-ai-gateway entry (e.g. claude-sonnet-4-5)
+      // resolved from your ModelRuntime, or leave it out to use the saved default.
+    });
+    // ...run the session and return a Response
+  }
+};
+```
+
+Every request under the gateway prefix becomes one `env.AI.gateway(id).run({ provider, endpoint, headers, query })` call in the provider's native wire format, so streaming behaves identically to the HTTPS route. The transport serves only its gateway-bound client: URLs outside the prefix, and in-prefix requests the universal endpoint cannot express (non-POST, non-JSON body), reject with a descriptive error rather than being forwarded. Repeat the same pattern with `@earendil-works/pi-ai/api/openai-completions` (or `openai-responses`) to cover the `/openai` and `/compat` passthrough models of the same provider.
+
 ### Cloudflare Workers AI
 
 `CLOUDFLARE_API_KEY` can be set via `/login`. `CLOUDFLARE_ACCOUNT_ID` must be set as an environment variable.

package/docs/quickstart.md

@@ -112,7 +112,7 @@ Atomic ships with nine workflows you can run immediately. Use `/workflow list` t
 | `loop-until-done` | Iterate with a durable ledger until completion or bound exhaustion. | `/workflow loop-until-done prompt="Repair failures until the test suite passes"` |
 | `goal` | Autonomous work that needs a durable ledger, bounded sub-agent orchestration, receipts, and reviewer-gated completion. | `/workflow goal objective="Update the CLI docs, add one example, and validate the docs build"` |
 | `ralph` | Research-first autonomous work with prompt refinement, delegated implementation, and iterative multi-model review. | `/workflow ralph prompt="Implement specs/rate-limit.md and validate burst traffic"` |
-| `open-claude-design` | UI and design-system work with separate generate and feedback passes and a live `preview.html`. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy as a page"` |
+| `open-claude-design` | UI and design-system work with one generated preview, one live review session, and export. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy as a page"` |
 
 <p align="center"><img src="images/workflow-list.png" alt="Workflow List" width="600" /></p>
 
@@ -168,10 +168,12 @@ Skills are reusable expert instructions. Trigger one with `/skill:<name>` follow
 | `create-spec` | Turn research into an implementation-ready plan. | `/skill:create-spec from research/docs/2026-03-rate-limit.md` |
 | `prompt-engineer` | Create, optimize, evaluate, or troubleshoot prompts for GPT-5.6, Claude Opus 5, and Claude Fable 5. | `/skill:prompt-engineer Draft a sharper repo-research prompt for payment retries end to end.` |
 | `tdd` | Test-first feature or bug work. | `/skill:tdd` |
-| `impeccable` | Critique or refine web/native frontend and product UI; includes detector hooks. | `/skill:impeccable` |
+| `impeccable` | Critique or refine web/native frontend and product UI; includes detector hooks, framework-aware live review, and mount-failure recovery. | `/skill:impeccable` |
 | `playwright-cli` | Drive a real browser for end-to-end UI checks, screenshots, and reviewable proof videos. | `/skill:playwright-cli` |
 | `liteparse` | Pull text, tables, or values out of PDF, DOCX, PPTX, XLSX, and image files locally. | `/skill:liteparse` |
 
+Impeccable 4.1.1 resolves Live sessions to the selected app root, supports SvelteKit, Nuxt, TanStack Start, Astro, Next.js, Vite, and static HTML injection, and rejects absolute, traversing, or symlinked configured write targets. Its concept roll may contact `impeccable.style`; set `IMPECCABLE_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to disable the anonymous choice ping. The image fallback runs only with `OPENAI_API_KEY`, sends prompts and optional reference images to OpenAI, and spends that account's API credit. Generated image prompts are embedded in the image or a sidecar, so do not include secrets.
+
 Use `/skill:research-codebase` for a focused subsystem or question. For repository-wide research, use `fan-out-and-synthesize` with distinct repository partitions and an artifact synthesis barrier. Use Goal for ledger-backed bounded orchestration and Ralph for research-first delegated implementation with iterative review; task size alone does not select either workflow.
 
 ### Create your own workflow in natural language

package/docs/rpc.md

@@ -954,17 +954,31 @@ Emitted when a message begins and completes. The `message` field contains an `Ag
 
 ### message_update (Streaming)
 
-Emitted during streaming of assistant messages. Carries only the streaming delta.
+Emitted during streaming of assistant messages. Carries the streaming delta plus the latest cumulative usage.
 
-`message_update` deliberately omits any cumulative snapshot: there is no `message`
+`message_update` deliberately omits the cumulative message snapshot: there is no `message`
 field, and `assistantMessageEvent` has no `partial`. `message_start` provides the
 initial message, the deltas build it, and `message_end` provides the final
 authoritative message. Repeating a snapshot on every frame would make the bytes
 written per assistant turn grow with the square of its length.
 
+The top-level `usage` field carries the latest cumulative provider-reported usage; it may
+remain zero until completion when a provider does not report usage during streaming. When
+the provider reports an explicit end-of-turn signal (pi-ai's `AssistantMessage.endTurn`,
+for example OpenAI Codex `end_turn`), the update carries it as a top-level `endTurn`
+boolean — present only when the provider reported one.
+
 ```json
 {
   "type": "message_update",
+  "usage": {
+    "input": 100,
+    "output": 1,
+    "cacheRead": 0,
+    "cacheWrite": 0,
+    "totalTokens": 101,
+    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "total": 0}
+  },
   "assistantMessageEvent": {
     "type": "text_delta",
     "contentIndex": 0,
@@ -992,10 +1006,10 @@ The `assistantMessageEvent` field contains one of these delta types:
 
 Example streaming a text response:
 ```json
-{"type":"message_update","assistantMessageEvent":{"type":"text_start","contentIndex":0}}
-{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
-{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world"}}
-{"type":"message_update","assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world"}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_start","contentIndex":0}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world"}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world"}}
 ```
 
 ### tool_execution_start / tool_execution_update / tool_execution_end
@@ -1465,7 +1479,7 @@ The `content` field can be a string or an array of `TextContent`/`ImageContent`
 }
 ```
 
-Stop reasons: `"stop"`, `"length"`, `"toolUse"`, `"error"`, `"aborted"`. A streaming message carries `"pending"` until the terminal event replaces it, so a client that switches on the reason needs that case; a completed message never carries it. On the wire the pending reason appears on the `message_start` message — `message_update` frames carry no message at all — and `message_end` carries the terminal reason.
+Stop reasons: `"stop"`, `"length"`, `"toolUse"`, `"error"`, `"aborted"`. A streaming message carries `"pending"` until the terminal event replaces it, so a client that switches on the reason needs that case; a completed message never carries it. On the wire the pending reason appears on the `message_start` message — `message_update` frames carry no message at all — and `message_end` carries the terminal reason. A provider that reports an explicit end-of-turn signal (pi-ai's `AssistantMessage.endTurn`, for example OpenAI Codex `end_turn`) sets `endTurn: true` on the assistant message; `message_update` frames echo it as a top-level boolean only when the provider reported one.
 
 ### ToolResultMessage
 

package/docs/sdk.md

@@ -46,7 +46,7 @@ const { session } = await createAgentSession({
 });
 ```
 
-`ModelRuntime.create()` accepts custom `authPath`, `modelsPath`, credential storage, and runtime auth overrides. `ModelRegistry` and `AuthStorage` remain available as Atomic's synchronous compatibility facades. Use `readStoredCredential(provider, authPath?)` for a lightweight read of one stored provider credential.
+`ModelRuntime.create()` accepts custom `authPath`, `modelsPath`, credential storage, and runtime auth overrides, plus the model-catalog options `allowModelNetwork`, `modelRefreshTimeoutMs`, `modelsStorePath`, and `modelsStore` (see [Model catalog persistence and refresh](#model-catalog-persistence-and-refresh)). `ModelRegistry` and `AuthStorage` remain available as Atomic's synchronous compatibility facades. Use `readStoredCredential(provider, authPath?)` for a lightweight read of one stored provider credential.
 
 Extensions supplied directly to SDK sessions can use the exported `InlineExtension` type. Extension APIs and event types include native `registerProvider(Provider)`, `registerEntryRenderer`, `entry_appended`, `before_provider_headers`, and `agent_settled`.
 
@@ -485,6 +485,31 @@ If no model is provided:
 
 > See [examples/sdk/02-custom-model.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/02-custom-model.ts)
 
+#### Model catalog persistence and refresh
+
+`ModelRuntime.create()` restores cached catalogs from local persistence but does not contact
+pi.dev unless you opt in. `allowModelNetwork` (default `false`) enables a create-time network
+refresh, and `modelRefreshTimeoutMs` (default `15_000`) bounds how long that refresh may run
+before it is aborted. Pass `refreshOnCreate: false` to skip the initial catalog and
+availability refresh entirely; built-in models remain available.
+
+```typescript
+const refreshedRuntime = await ModelRuntime.create({
+  allowModelNetwork: true,
+  modelRefreshTimeoutMs: 15_000,
+});
+```
+
+Remote catalogs are persisted locally so later runtimes can restore them without a network
+request. The default file is `models-store.json` next to `models.json` — with the default
+`modelsPath` that is `~/.atomic/agent/models-store.json`. Set `modelsStorePath` to choose
+another location, or inject `modelsStore` to control persistence entirely; a runtime created
+with `modelsPath: null` keeps its store in memory. Network refreshes are throttled to once
+per provider every four hours unless forced. To force an immediate refresh, call
+`await modelRuntime.refresh({ allowNetwork: true, force: true, signal })`. Setting
+`ATOMIC_OFFLINE` (legacy alias `PI_OFFLINE`) disables model network access, and a
+`refresh()` call that omits `allowNetwork` follows that same runtime network policy.
+
 ### API Keys and OAuth
 
 `ModelRuntime` is the asynchronous SDK engine for provider composition, credentials, model catalogs, and requests. `ModelRegistry` remains a thin compatibility facade for extensions; `await modelRegistry.complete(model, context, options)` routes a request through its runtime with the resolved provider and auth. New SDK integrations should pass `modelRuntime` to `createAgentSession` and use `modelRuntime.complete()` directly when they issue standalone requests.

package/docs/session-format.md

@@ -307,6 +307,8 @@ Session metadata (e.g., user-defined display name). Set via `/name`, `--name` /
 
 The session name is displayed in the session selector (`/resume`) instead of the first message when set.
 
+Appending a `session_info` entry with an empty `name` clears the title. The distinction is durable: a cleared session keeps its trailing empty-name entry, while a never-named session has no `session_info` entry at all. Readers can tell them apart through `getSessionNameState()` (`{ hasName: false }` for never-named, `{ hasName: true }` for cleared) and through the `hasName` flag on listed `SessionInfo` rows; the bare `name` string is `undefined` in both cases.
+
 ### SessionSummaryEntry
 
 A generated one-line description of the session, written automatically once the agent goes idle and shown in the session selector. Never sent to the LLM.
@@ -433,7 +435,7 @@ for (const stage of stages.filter((session) => session.internal)) {
 - `appendModelChange(provider, modelId)` - Record model change
 - `appendCompaction(compactedText, firstKeptEntryId, tokensBefore, details)` - Add a durable verbatim-line compaction boundary; pass `null` when no pre-boundary message is retained
 - `appendCustomEntry(customType, data?)` - Extension state (not in context)
-- `appendSessionInfo(name)` - Set session display name
+- `appendSessionInfo(name)` - Set session display name; an empty string clears it
 - `appendSessionSummary(summary, summarizedThroughId, usage?)` - Store a generated resume-picker summary, anchored to the message it describes
 - `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
 - `appendLabelChange(targetId, label)` - Set/clear label
@@ -454,7 +456,8 @@ for (const stage of stages.filter((session) => session.internal)) {
 - `buildSessionContext()` - Get messages, thinkingLevel, and model for LLM
 - `getEntries()` - All entries (excluding header)
 - `getHeader()` - Session header metadata
-- `getSessionName()` - Get display name from latest session_info entry
+- `getSessionName()` - Get display name from latest session_info entry (`undefined` when cleared or never named)
+- `getSessionNameState()` - Get the name state: `{ hasName: false }` when never named, `{ hasName: true }` when the latest entry cleared it, `{ hasName: true, name }` when currently named
 - `getCwd()` - Working directory
 - `getSessionDir()` - Session storage directory
 - `getSessionId()` - Session UUID

package/docs/settings.md

@@ -86,7 +86,7 @@ Fallback attempts are visible as model changes in the session transcript and as
 
 ### Codex Fast Mode
 
-Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode only to supported `openai/*` and `openai-codex/*` providers, not `github-copilot/*` or other OpenAI-compatible providers. Chat and workflow-stage scopes are independent. Workflow stages, nested `ctx.workflow(...)` stages, and subagents launched by those stages use `codexFastMode.workflow`; normal-chat subagents use `codexFastMode.chat`. Fast mode is resolved again for each fallback model, so the marker and priority tier follow the effective provider. When fast mode is active for the current supported model, Atomic shows `fast` after the model name in the chat footer, workflow stage model labels, and subagent results. Enable the workflow scope deliberately for broad fan-outs because each eligible stage can consume priority-tier requests.
+Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode to supported `openai/*` and `openai-codex/*` providers and to provider aliases that use the shared `openai-codex-responses` transport, not `github-copilot/*` or generic OpenAI-compatible providers. Chat and workflow-stage scopes are independent. Workflow stages, nested `ctx.workflow(...)` stages, and subagents launched by those stages use `codexFastMode.workflow`; normal-chat subagents use `codexFastMode.chat`. Fast mode is resolved again for each fallback model, so the marker and priority tier follow the effective provider. When fast mode is active for the current supported model, Atomic shows `fast` after the model name in the chat footer, workflow stage model labels, and subagent results. Enable the workflow scope deliberately for broad fan-outs because each eligible stage can consume priority-tier requests.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
@@ -108,6 +108,7 @@ Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode
 |---------|------|---------|-------------|
 | `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, a Catppuccin built-in, or custom) |
 | `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows it temporarily while scrolling, `"always"` reserves the rightmost transcript column and keeps it visible, and `"hidden"` hides it. The thumb can be dragged when shown. |
+| `fullscreenExitOutput` | string | `"transcript"` | Fullscreen exit output: `"transcript"` prints the final transcript and session resume hint, while `"resume-hint"` restores the terminal's previous screen and prints only the resume hint. Settable from `/settings` |
 | `quietStartup` | boolean | `false` | Hide startup header |
 | `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
 | `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
@@ -128,7 +129,7 @@ Interactive sessions always use the fullscreen renderer. The transcript scrolls
 
 The fullscreen renderer keeps minimum sizes for nested layout stacks during resize, and transient fullscreen notices stack instead of replacing a notice that is still visible.
 
-The alternate screen restores the terminal's prior contents on exit, so an interactive transcript does not remain in terminal scrollback. Use `/export` before exit for an HTML copy, or resume the saved session later to review it in Atomic.
+The alternate screen normally restores the terminal's prior contents on exit, so an interactive transcript does not remain in terminal scrollback. The `fullscreenExitOutput` setting changes what exiting prints: `"transcript"` (the default) paints the final transcript plus a session resume hint on the main screen, while `"resume-hint"` restores the previous screen and prints only the resume hint. Use `/export` before exit for an HTML copy, or resume the saved session later to review it in Atomic.
 
 Ctrl+G in main chat, embedded chat, and extension editor dialogs uses one shared asynchronous launcher. Atomic chooses `externalEditor`, then `$VISUAL`, then `$EDITOR`, then Notepad on Windows or `nano` elsewhere. Each edit uses a private `atomic-editor-*` directory containing only `prompt.md`, removes the directory recursively afterward, and never scans the system temporary directory. A successful empty edit is preserved; a failed editor leaves the original text unchanged, and the TUI always restarts and renders after the editor exits.
 
@@ -305,6 +306,36 @@ When `images.autoResize` is enabled, Atomic normalizes images before sending the
 
 Normally the package manager's global modules location is queried using `root -g`. As a special case, if the first element of `npmCommand` is `"bun"`, the modules location will instead be queried with `pm bin -g`.
 
+On Windows, JSON paths must use forward slashes or escaped backslashes:
+
+```json
+{
+  "shellPath": "C:/Program Files/Git/bin/bash.exe"
+}
+```
+
+```json
+{
+  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
+}
+```
+
+### Tools
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `defaultTools` | string[] | - | Built-in tools enabled at startup. When omitted, Atomic uses its standard defaults |
+
+`defaultTools` selects the built-in tools a session starts with. Extension and SDK custom tools stay enabled regardless:
+
+```json
+{
+  "defaultTools": ["bash", "edit", "write"]
+}
+```
+
+An empty array starts with no built-in tools while preserving extension and custom tools. `--tools` replaces this behavior with a strict allowlist covering all tools, `--no-tools` disables all tools, and `--no-builtin-tools` disables only the built-in defaults. `--exclude-tools` filters the resulting list. A project `defaultTools` array replaces the global array.
+
 ### Sessions
 
 | Setting | Type | Default | Description |
@@ -342,7 +373,7 @@ When multiple sources specify a session directory, precedence is `--session-dir`
 
 Mermaid code blocks render as themed Unicode diagrams in interactive transcripts when they fit the available width. `"off"` keeps the Markdown fence, `"final"` renders only finalized responses, and `"streaming"` also renders partial assistant responses. Invalid or too-wide diagrams remain as code, and rendering is display-only: stored messages and model context keep the original Markdown. LaTeX rendering is also display-only and converts supported expressions to terminal-friendly Unicode math; set `markdown.latex` to `false` to keep the source form.
 
-The installed pi-tui 0.84.1 LaTeX renderer also handles whitespace and matrix layouts correctly.
+The installed pi-tui 0.84.2 LaTeX renderer also handles whitespace and matrix layouts correctly.
 
 ### Resources
 

package/docs/skills.md

@@ -85,6 +85,21 @@ Skills register as `/skill:name` commands:
 /skill:pdf-tools extract      # Load skill with arguments
 ```
 
+When multiple real skill files declare the same name, Atomic keeps the existing precedence winner for the bare command and retains every distinct file as an exact candidate. Use a source-qualified command to select one explicitly:
+
+```bash
+/skill:review                  # Current precedence winner
+/skill:review@project          # Unique project candidate
+/skill:review@user             # Unique user candidate
+/skill:review@builtin          # Unique bundled candidate
+```
+
+`@project`, `@user`, and `@builtin` are available only when that family has one candidate in the collision. If a family contains multiple package candidates, Atomic advertises package-qualified aliases instead, such as `/skill:review@team-review` and `/skill:review@company-review`; the family selector is ambiguous and reports the exact choices. Autocomplete, `pi.getCommands()`, and RPC `get_commands` return the same advertised names.
+
+Qualified selection is exact. An unknown or ambiguous qualified selector reports an error and never falls back to the bare winner. Aliases are recalculated on reload, so a qualified alias disappears when its collision disappears. The model-visible skill list uses the same aliases, while the opaque candidate IDs stored in transcripts and collision diagnostics are internal identity, not command names.
+
+Subagent definitions and per-call `skills` overrides accept these same selectors. Live in-process children resolve them from their own loader catalog after resource reload; a missing or ambiguous selector is reported in the child result instead of silently selecting the bare skill. The parent-only `subagent` orchestration skill cannot be injected into a child, including qualified aliases such as `subagent@builtin`. Extensions can read the same catalog through `ctx.getSkillCatalog()`.
+
 Arguments after the command are appended to the skill content as `User: <args>`.
 
 Toggle skill commands via `/settings` in interactive mode or in `settings.json`:
@@ -194,7 +209,7 @@ Unknown frontmatter fields are ignored.
 
 **Exception:** Skills with missing description are not loaded.
 
-Name collisions (same name from different locations) warn and keep the first skill found.
+Name collisions (the same name from different real files) produce diagnostics and keep the existing first-winner precedence for `/skill:name`. Atomic also retains the other files as source-qualified candidates as described in [Skill Commands](#skill-commands).
 
 ## Example