@bastani/atomic 0.9.14-alpha.1 → 0.9.14-alpha.2

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
 

package/docs/terminal-setup.md

@@ -6,9 +6,20 @@ Atomic uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboa
 
 On normal interactive TTY startup, Atomic starts a short-lived raw keyboard capture before deferred resources finish loading and keeps it active until the TUI input handler is mounted. Text typed before the prompt box is fully mounted is replayed into the editor. Enter-submitted ordinary prompts are queued for the prompt loop once startup is ready; command-like submissions such as `/settings` or `!pwd` are replayed as standalone editor submissions through normal command routing. If a command-like submission is captured, later captured submissions wait behind it and replay in original input order after that command is routed, so a later ordinary prompt cannot run before the earlier command and commands are not merged with following prompts. Startup work that can affect correctness, such as project trust prompts, resume/session selectors, cross-project session confirmations, explicit resource flags, metadata commands, non-TTY input, or explicit provider/model selection, still stays on the synchronous path instead of using this pre-session capture.
 
-## Kitty, iTerm2
+## Kitty
 
-Work out of the box.
+Works out of the box.
+
+## iTerm2
+
+Key reporting works out of the box. In the fullscreen TUI, Atomic owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling its native scrollback. With iTerm2's default fast-trackpad behavior, those reports can lose most of an accelerated wheel delta, making fullscreen scrolling much slower than iTerm2's native scrolling.
+
+If fast mouse-wheel gestures move only about one line at a time in Atomic:
+
+1. Open **iTerm2 → Settings → Advanced**.
+2. Search for **Trackpad scrolls fast?** and set it to **No**.
+
+This is an iTerm2-wide workaround and may also change native trackpad scrolling. The underlying behavior is tracked in [iTerm2 issue 9619](https://gitlab.com/gnachman/iterm2/-/work_items/9619).
 
 ## Apple Terminal
 
@@ -42,6 +53,8 @@ If you want `SHIFT+Enter` to keep working in tmux via that remap, add `ctrl+j` t
 }
 ```
 
+In the fullscreen TUI, links remain clickable, but Ghostty does not show its hover underline or lower-left URL preview while Atomic captures mouse input. Hold `Shift+Command` on macOS or `Shift+Ctrl` on Linux to use Ghostty's native link handling.
+
 ## WezTerm
 
 WezTerm usually works out of the box for `SHIFT+Enter` via xterm modifyOtherKeys. To use the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:

package/docs/themes.md

@@ -25,7 +25,7 @@ Atomic loads themes from:
 - Settings: `themes` array with files or directories
 - CLI: `--theme <path>` (repeatable)
 
-Disable discovery with `--no-themes`.
+Disable discovery with `--no-themes`. `--theme <path>` loads a theme file; `--use-theme <name>` (see [Initial Theme](#initial-theme)) selects an already-loaded theme for this run without saving it.
 
 ## Selecting a Theme
 
@@ -41,6 +41,22 @@ Use `"theme": "light-theme/dark-theme"` for automatic mode. Atomic chooses the f
 
 On first run, Atomic detects your terminal background and defaults to `dark` or `light`.
 
+### Initial Theme
+
+Start an interactive run with a theme without changing the saved setting:
+
+```bash
+atomic --use-theme light
+```
+
+To follow terminal appearance, use the `lightTheme/darkTheme` form:
+
+```bash
+atomic --use-theme light/dark
+```
+
+The CLI value is the initial theme for that run only. Choosing another theme later in `/settings` applies it immediately and saves it normally; an unknown theme name reports the ordinary theme error.
+
 ## Creating a Custom Theme
 
 1. Create a theme file:
@@ -150,14 +166,14 @@ vim ~/.atomic/agent/themes/my-theme.json
 
 - `name` is required, must be unique, and must not contain `/`.
 - `vars` is optional. Define reusable colors here, then reference them in `colors` or `workingIndicator`.
-- `colors` must define all 51 required tokens. `scrollbarThumb` is optional and falls back to `selectedBg` when omitted.
+- `colors` must define all 51 required tokens. `scrollbarThumb` is optional and falls back to `selectedBg` when omitted. `searchMatchBg` and `searchMatchText` remain accepted for older theme files but are unused.
 - `workingIndicator` is optional and may override any subset of the six tones in the outward half of the ordinary `∀` ramp; Atomic derives omitted tones from selected background, accent, and text roles, then mirrors the palette back after `peak`. Explicit numeric values from 0 through 255 remain exact terminal palette indices. When a numeric index from 0 through 15 seeds an omitted tone, Atomic mixes from its built-in approximation of the common ANSI RGB value; the terminal still controls the actual appearance of the explicit index. Both explicit and derived tones update on theme hot reload.
 
 The `$schema` field enables editor auto-completion and validation.
 
 ## Color Tokens
 
-Every theme must define all 51 required color tokens. `scrollbarThumb` is optional and falls back to `selectedBg` when omitted.
+Every theme must define all 51 required color tokens. The optional tokens preserve compatibility with themes written before they existed: `scrollbarThumb` and unused `searchMatchBg` fall back to `selectedBg`, and unused `searchMatchText` falls back to `text`.
 
 ### Core UI (11 colors)
 
@@ -175,12 +191,14 @@ Every theme must define all 51 required color tokens. `scrollbarThumb` is option
 | `text` | Default text (usually `""`) |
 | `thinkingText` | Thinking block text |
 
-### Backgrounds & Content (11 required, 1 optional)
+### Backgrounds & Content (11 required, 3 optional)
 
 | Token | Purpose |
 |-------|---------|
 | `selectedBg` | Selected line background |
 | `scrollbarThumb` | Fullscreen scrollbar thumb background; optional, falls back to `selectedBg` |
+| `searchMatchBg` | Unused leftover token; optional, falls back to `selectedBg` |
+| `searchMatchText` | Unused leftover token; optional, falls back to `text` |
 | `userMessageBg` | User message background |
 | `userMessageText` | User message text |
 | `customMessageBg` | Extension message background |

package/docs/tools.md

@@ -24,7 +24,9 @@ insert tail:
 
 Supported hashline operations include `replace N..M:`, `replace block N:`, `delete N..M`, `delete block N`, `insert before N:`, `insert after N:`, `insert after block N:`, `insert head:`, and `insert tail:`. Safe lenient variants such as `replace N`, `replace N-M:`, `replace N M:`, `replace N…M:`, bare body rows, and `*** Begin Patch` envelopes are accepted. Bare body rows are auto-prefixed and reported as warnings. `*** Abort` stops parsing the remaining input, while apply-patch sentinels, `@@` hunk headers, bare numeric hunk headers, `delete` bodies, empty `replace`/`insert` bodies, and `-` diff rows are rejected with guidance instead of silently deleting content. Line numbers refer to the original tagged snapshot and do not shift within a call.
 
-Before writing, Atomic verifies the current file against the tagged snapshot. If the file drifted, `edit` first attempts a snapshot-based recovery for provably non-overlapping external changes and appends a warning when it preserves those changes; unknown tags, overlapping stale edits, and unrecoverable drift fail clearly with the current file hash (and anchor context for drifted files) and leave the file unchanged. Byte-identical no-op edits return a no-op warning without writing, and repeated identical no-ops escalate to an error to stop looped retries. Hashline snapshots are scoped to the active tool/session store, so tags emitted in another session or stale context do not authorize edits. One `edit` input may contain multiple `[PATH#TAG]` sections; Atomic preflights every section before writing, but this is preflight atomicity rather than transactional rollback, so a mid-batch filesystem write failure can leave earlier sections already written. Each successful `write` or `edit` returns a fresh tag for follow-up edits; hashline edit success output is compact and includes the refreshed header plus block-resolution/change metadata while the full diff remains in tool details. Plain `write` success output is likewise compact (`[path#TAG]` plus a byte-count summary), not a full reprint of the file. `write` strips copied hashline headers and `LINE:`/`*LINE:` display prefixes only when the pasted content matches a known current-store snapshot and notes when stripping occurred. Literal or unknown hashline-looking content is preserved instead of being stripped.
+Before writing, Atomic verifies the current file against the tagged snapshot. If the file drifted, `edit` first attempts a snapshot-based recovery for provably non-overlapping external changes and appends a warning when it preserves those changes; unknown tags, overlapping stale edits, and unrecoverable drift fail clearly with the current file hash (and anchor context for drifted files) and leave the file unchanged. Byte-identical no-op edits return a no-op warning without writing, and repeated identical no-ops escalate to an error to stop looped retries. Hashline snapshots are scoped to the active tool/session store, so tags emitted in another session or stale context do not authorize edits. One `edit` input may contain multiple `[PATH#TAG]` sections; Atomic preflights every section before writing, but this is preflight atomicity rather than transactional rollback, so a mid-batch filesystem write failure can leave earlier sections already written. Each successful `write` or `edit` returns a fresh tag for follow-up edits; hashline edit success output is compact and includes the refreshed header plus block-resolution/change metadata while the full diff remains in tool details. Plain `write` success output is likewise compact (`[path#TAG]` plus a byte-count summary), not a full reprint of the file. `write` strips copied hashline headers and `LINE:`/`*LINE:` display prefixes only when the pasted content matches a known current-store snapshot and notes when stripping occurred; complete copied output preserves whether that snapshot had a terminal newline. Literal or unknown hashline-looking content is preserved instead of being stripped.
+
+Hashline anchors must be positive safe integers. Inclusive numeric ranges are limited to 100,000 lines before expansion. An explicit `+TEXT` row that looks like a valid hunk header remains literal and emits a warning. Across whole-file, truncated, and range/offset reads of LF or CRLF text, numbered hashline output treats a terminal newline as a separator rather than an additional synthetic row; genuine blank lines, including one immediately before that newline, remain visible. Truncation totals and continuation selectors count real lines. Files using bare CR line endings retain their existing compatibility behavior and are outside this newline guarantee.
 
 ## `bash` and `bashInterceptor`
 

package/docs/tui.md

@@ -28,6 +28,8 @@ interface Component {
 
 The installed pi-tui type still permits handlers that return `void`; Atomic treats a missing or `undefined` result as unhandled only for a matching fullscreen viewport key or a mouse event deferred to a focused overlay. Components that mutate state for such an input must return `true` so the viewport does not apply it a second time.
 
+Omitting `handleInput` altogether is the same answer as declining: a focused overlay with no handler still lets fullscreen viewport keys and mouse wheel reports reach the transcript, so a notice or progress panel does not freeze scrolling behind it. An asynchronous handler is judged when it settles — only a promise that resolves `true` consumes the input, while `false`, `undefined`, and a rejection all fall through to the viewport. Input that moved focus while such a promise was pending is left to whatever holds focus when it settles.
+
 The TUI appends a full SGR reset and OSC 8 reset at the end of each rendered line. Styles do not carry across lines. If you emit multi-line text with styling, reapply styles per line or use `wrapTextWithAnsi()` so styles are preserved for each wrapped line.
 
 ## Focusable Interface (IME Support)